man3/pthread_getcpuclockid.3

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_GETCPUCLOCKID 3 2021-03-22 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock
   9 .SH LIBRARY
  10 POSIX threads library
  11 .RI ( libpthread ", " \-lpthread )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <pthread.h>
  15 .B #include <time.h>
  16 .PP
  17 .BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid );
  18 .fi
  19 .SH DESCRIPTION
  20 The
  21 .BR pthread_getcpuclockid ()
  22 function obtains the ID of the CPU-time clock of the thread whose ID is
  23 given in
  24 .IR thread ,
  25 and returns it in the location pointed to by
  26 .IR clockid .
  27 .\" The clockid is constructed as follows:
  28 .\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE)
  29 .\" where CLOCK_IDFIELD_SIZE is 3.
  30 .SH RETURN VALUE
  31 On success, this function returns 0;
  32 on error, it returns a nonzero error number.
  33 .SH ERRORS
  34 .TP
  35 .B ENOENT
  36 .\" CLOCK_THREAD_CPUTIME_ID not defined
  37 Per-thread CPU time clocks are not supported by the system.
  38 .\"
  39 .\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would
  40 .\" be possible if kernel thread IDs took more than 29 bits (which
  41 .\" they currently cannot).
  42 .TP
  43 .B ESRCH
  44 No thread with the ID
  45 .I thread
  46 could be found.
  47 .SH VERSIONS
  48 This function is available in glibc since version 2.2.
  49 .SH ATTRIBUTES
  50 For an explanation of the terms used in this section, see
  51 .BR attributes (7).
  52 .ad l
  53 .nh
  54 .TS
  55 allbox;
  56 lbx lb lb
  57 l l l.
  58 Interface       Attribute       Value
  59 T{
  60 .BR pthread_getcpuclockid ()
  61 T}      Thread safety   MT-Safe
  62 .TE
  63 .hy
  64 .ad
  65 .sp 1
  66 .SH STANDARDS
  67 POSIX.1-2001, POSIX.1-2008.
  68 .SH NOTES
  69 When
  70 .I thread
  71 refers to the calling thread,
  72 this function returns an identifier that refers to the same clock
  73 manipulated by
  74 .BR clock_gettime (2)
  75 and
  76 .BR clock_settime (2)
  77 when given the clock ID
  78 .BR CLOCK_THREAD_CPUTIME_ID .
  79 .SH EXAMPLES
  80 The program below creates a thread and then uses
  81 .BR clock_gettime (2)
  82 to retrieve the total process CPU time,
  83 and the per-thread CPU time consumed by the two threads.
  84 The following shell session shows an example run:
  85 .PP
  86 .in +4n
  87 .EX
  88 $ \fB./a.out\fP
  89 Main thread sleeping
  90 Subthread starting infinite loop
  91 Main thread consuming some CPU time...
  92 Process total CPU time:    1.368
  93 Main thread CPU time:      0.376
  94 Subthread CPU time:        0.992
  95 .EE
  96 .in
  97 .SS Program source
  98 \&
  99 .EX
 100 /* Link with "\-lrt" */
 101
 102 #include <time.h>
 103 #include <stdio.h>
 104 #include <stdint.h>
 105 #include <stdlib.h>
 106 #include <unistd.h>
 107 #include <pthread.h>
 108 #include <string.h>
 109 #include <errno.h>
 110
 111 #define handle_error(msg) \e
 112         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 113
 114 #define handle_error_en(en, msg) \e
 115         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 116
 117 static void *
 118 thread_start(void *arg)
 119 {
 120     printf("Subthread starting infinite loop\en");
 121     for (;;)
 122         continue;
 123 }
 124
 125 static void
 126 pclock(char *msg, clockid_t cid)
 127 {
 128     struct timespec ts;
 129
 130     printf("%s", msg);
 131     if (clock_gettime(cid, &ts) == \-1)
 132         handle_error("clock_gettime");
 133     printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
 134 }
 135
 136 int
 137 main(int argc, char *argv[])
 138 {
 139     pthread_t thread;
 140     clockid_t cid;
 141     int s;
 142
 143     s = pthread_create(&thread, NULL, thread_start, NULL);
 144     if (s != 0)
 145         handle_error_en(s, "pthread_create");
 146
 147     printf("Main thread sleeping\en");
 148     sleep(1);
 149
 150     printf("Main thread consuming some CPU time...\en");
 151     for (int j = 0; j < 2000000; j++)
 152         getppid();
 153
 154     pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);
 155
 156     s = pthread_getcpuclockid(pthread_self(), &cid);
 157     if (s != 0)
 158         handle_error_en(s, "pthread_getcpuclockid");
 159     pclock("Main thread CPU time:   ", cid);
 160
 161     /* The preceding 4 lines of code could have been replaced by:
 162        pclock("Main thread CPU time:   ", CLOCK_THREAD_CPUTIME_ID); */
 163
 164     s = pthread_getcpuclockid(thread, &cid);
 165     if (s != 0)
 166         handle_error_en(s, "pthread_getcpuclockid");
 167     pclock("Subthread CPU time: 1    ", cid);
 168
 169     exit(EXIT_SUCCESS);         /* Terminates both threads */
 170 }
 171 .EE
 172 .SH SEE ALSO
 173 .BR clock_gettime (2),
 174 .BR clock_settime (2),
 175 .BR timer_create (2),
 176 .BR clock_getcpuclockid (3),
 177 .BR pthread_self (3),
 178 .BR pthreads (7),
 179 .BR time (7)