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 .SH DESCRIPTION
  36 The
  37 .BR pthread_getcpuclockid ()
  38 function returns the clock ID for the CPU time clock of the thread
  39 .IR thread .
  40 .\" The clockid is constructed as follows:
  41 .\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE)
  42 .\" where CLOCK_IDFIELD_SIZE is 3.
  43 .SH RETURN VALUE
  44 On success, this function returns 0;
  45 on error, it returns a nonzero error number.
  46 .SH ERRORS
  47 .TP
  48 .B ENOENT
  49 .\" CLOCK_THREAD_CPUTIME_ID not defined
  50 Per-thread CPU time clocks are not supported by the system.
  51 .\"
  52 .\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would
  53 .\" be possible if kernel thread IDs took more than 29 bits (which
  54 .\" they currently cannot).
  55 .TP
  56 .B ESRCH
  57 No thread with the ID
  58 .I thread
  59 could be found.
  60 .SH VERSIONS
  61 This function is available in glibc since version 2.2.
  62 .SH CONFORMING TO
  63 POSIX.1-2001.
  64 .SH NOTES
  65 When
  66 .I thread
  67 refers to the calling thread,
  68 this function returns an identifier that refers to the same clock
  69 manipulated by
  70 .BR clock_gettime (2)
  71 and
  72 .BR clock_settime (2)
  73 when given the clock ID
  74 .BR CLOCK_THREAD_CPUTIME_ID .
  75 .SH EXAMPLE
  76 The program below creates a thread and then uses
  77 .BR clock_gettime (2)
  78 to retrieve the total process CPU time,
  79 and the per-thread CPU time consumed by the two threads.
  80 The following shell session shows an example run:
  81 .in +4n
  82 .nf
  83 $ \fB./a.out\fP
  84 Main thread sleeping
  85 Subthread starting infinite loop
  86 Main thread consuming some CPU time...
  87 Process total CPU time:    1.368
  88 Main thread CPU time:      0.376
  89 Subthread CPU time:        0.992
  90 .fi
  91 .in
  92 .SS Program source
  93 \&
  94 .nf
  95 /* Link with "\-lrt" */
  96
  97 #include <time.h>
  98 #include <stdio.h>
  99 #include <stdlib.h>
 100 #include <unistd.h>
 101 #include <pthread.h>
 102 #include <string.h>
 103 #include <errno.h>
 104
 105 #define handle_error(msg) \\
 106         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 107
 108 #define handle_error_en(en, msg) \\
 109         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 110
 111 static void *
 112 thread_start(void *arg)
 113 {
 114     printf("Subthread starting infinite loop\\n");
 115     for (;;)
 116         continue;
 117 }
 118
 119 static void
 120 pclock(char *msg, clockid_t cid)
 121 {
 122     struct timespec ts;
 123
 124     printf("%s", msg);
 125     if (clock_gettime(cid, &ts) == \-1)
 126         handle_error("clock_gettime");
 127     printf("%4ld.%03ld\\n", ts.tv_sec, ts.tv_nsec / 1000000);
 128 }
 129
 130 int
 131 main(int argc, char *argv[])
 132 {
 133     pthread_t thread;
 134     clockid_t cid;
 135     int j, s;
 136
 137     s = pthread_create(&thread, NULL, thread_start, NULL);
 138     if (s != 0)
 139         handle_error_en(s, "pthread_create");
 140
 141     printf("Main thread sleeping\\n");
 142     sleep(1);
 143
 144     printf("Main thread consuming some CPU time...\\n");
 145     for (j = 0; j < 2000000; j++)
 146         getppid();
 147
 148     pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);
 149
 150     s = pthread_getcpuclockid(pthread_self(), &cid);
 151     if (s != 0)
 152         handle_error_en(s, "pthread_getcpuclockid");
 153     pclock("Main thread CPU time:   ", cid);
 154
 155     /* The preceding 4 lines of code could have been replaced by:
 156        pclock("Main thread CPU time:   ", CLOCK_THREAD_CPUTIME_ID); */
 157
 158     s = pthread_getcpuclockid(thread, &cid);
 159     if (s != 0)
 160         handle_error_en(s, "pthread_getcpuclockid");
 161     pclock("Subthread CPU time: 1    ", cid);
 162
 163     exit(EXIT_SUCCESS);         /* Terminates both threads */
 164 }
 165 .fi
 166 .SH SEE ALSO
 167 .BR clock_gettime (2),
 168 .BR clock_settime (2),
 169 .BR timer_create (2),
 170 .BR clock_getcpuclockid (3),
 171 .BR pthread_self (3),
 172 .BR pthreads (7),
 173 .BR time (7)