man3/pthread_getcpuclockid.3

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