original/man3/pthread_getcpuclockid.3

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH PTHREAD_GETCPUCLOCKID 3 2009-02-08 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock
  27 .SH SYNOPSIS
  28 .nf
  29 .B #include <pthread.h>
  30 .B #include <time.h>
  31
  32 .BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clock_id);
  33 .sp
  34 Compile and link with \fI\-pthread\fP.
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR pthread_getcpuclockid ()
  39 function returns the clock ID for the CPU time clock of the thread
  40 .IR thread .
  41 .\" The clockid is constructed as follows:
  42 .\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE)
  43 .\" where CLOCK_IDFIELD_SIZE is 3.
  44 .SH RETURN VALUE
  45 On success, this function returns 0;
  46 on error, it returns a nonzero error number.
  47 .SH ERRORS
  48 .TP
  49 .B ENOENT
  50 .\" CLOCK_THREAD_CPUTIME_ID not defined
  51 Per-thread CPU time clocks are not supported by the system.
  52 .\"
  53 .\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would
  54 .\" be possible if kernel thread IDs took more than 29 bits (which
  55 .\" they currently cannot).
  56 .TP
  57 .B ESRCH
  58 No thread with the ID
  59 .I thread
  60 could be found.
  61 .SH VERSIONS
  62 This function is available in glibc since version 2.2.
  63 .SH CONFORMING TO
  64 POSIX.1-2001.
  65 .SH NOTES
  66 When
  67 .I thread
  68 refers to the calling thread,
  69 this function returns an identifier that refers to the same clock
  70 manipulated by
  71 .BR clock_gettime (2)
  72 and
  73 .BR clock_settime (2)
  74 when given the clock ID
  75 .BR CLOCK_THREAD_CPUTIME_ID .
  76 .SH EXAMPLE
  77 The program below creates a thread and then uses
  78 .BR clock_gettime (2)
  79 to retrieve the total process CPU time,
  80 and the per-thread CPU time consumed by the two threads.
  81 The following shell session shows an example run:
  82 .in +4n
  83 .nf
  84 $ \fB./a.out\fP
  85 Main thread sleeping
  86 Subthread starting infinite loop
  87 Main thread consuming some CPU time...
  88 Process total CPU time:    1.368
  89 Main thread CPU time:      0.376
  90 Subthread CPU time:        0.992
  91 .fi
  92 .in
  93 .SS Program source
  94 \&
  95 .nf
  96 /* Link with "\-lrt" */
  97
  98 #include <time.h>
  99 #include <stdio.h>
 100 #include <stdlib.h>
 101 #include <unistd.h>
 102 #include <pthread.h>
 103 #include <string.h>
 104 #include <errno.h>
 105
 106 #define handle_error(msg) \\
 107         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 108
 109 #define handle_error_en(en, msg) \\
 110         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 111
 112 static void *
 113 thread_start(void *arg)
 114 {
 115     printf("Subthread starting infinite loop\\n");
 116     for (;;)
 117         continue;
 118 }
 119
 120 static void
 121 pclock(char *msg, clockid_t cid)
 122 {
 123     struct timespec ts;
 124
 125     printf("%s", msg);
 126     if (clock_gettime(cid, &ts) == \-1)
 127         handle_error("clock_gettime");
 128     printf("%4ld.%03ld\\n", ts.tv_sec, ts.tv_nsec / 1000000);
 129 }
 130
 131 int
 132 main(int argc, char *argv[])
 133 {
 134     pthread_t thread;
 135     clockid_t cid;
 136     int j, s;
 137
 138     s = pthread_create(&thread, NULL, thread_start, NULL);
 139     if (s != 0)
 140         handle_error_en(s, "pthread_create");
 141
 142     printf("Main thread sleeping\\n");
 143     sleep(1);
 144
 145     printf("Main thread consuming some CPU time...\\n");
 146     for (j = 0; j < 2000000; j++)
 147         getppid();
 148
 149     pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);
 150
 151     s = pthread_getcpuclockid(pthread_self(), &cid);
 152     if (s != 0)
 153         handle_error_en(s, "pthread_getcpuclockid");
 154     pclock("Main thread CPU time:   ", cid);
 155
 156     /* The preceding 4 lines of code could have been replaced by:
 157        pclock("Main thread CPU time:   ", CLOCK_THREAD_CPUTIME_ID); */
 158
 159     s = pthread_getcpuclockid(thread, &cid);
 160     if (s != 0)
 161         handle_error_en(s, "pthread_getcpuclockid");
 162     pclock("Subthread CPU time: 1    ", cid);
 163
 164     exit(EXIT_SUCCESS);         /* Terminates both threads */
 165 }
 166 .fi
 167 .SH SEE ALSO
 168 .BR clock_gettime (2),
 169 .BR clock_settime (2),
 170 .BR timer_create (2),
 171 .BR clock_getcpuclockid (3),
 172 .BR pthread_self (3),
 173 .BR pthreads (7),
 174 .BR time (7)