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 (date) "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 .\" SRC BEGIN (pthread_getcpuclockid.c)
 100 .EX
 101 /* Link with "\-lrt" */
 102
 103 #include <errno.h>
 104 #include <pthread.h>
 105 #include <stdint.h>
 106 #include <stdio.h>
 107 #include <stdlib.h>
 108 #include <string.h>
 109 #include <time.h>
 110 #include <unistd.h>
 111
 112 #define handle_error(msg) \e
 113         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 114
 115 #define handle_error_en(en, msg) \e
 116         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 117
 118 static void *
 119 thread_start(void *arg)
 120 {
 121     printf("Subthread starting infinite loop\en");
 122     for (;;)
 123         continue;
 124 }
 125
 126 static void
 127 pclock(char *msg, clockid_t cid)
 128 {
 129     struct timespec ts;
 130
 131     printf("%s", msg);
 132     if (clock_gettime(cid, &ts) == \-1)
 133         handle_error("clock_gettime");
 134     printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
 135 }
 136
 137 int
 138 main(void)
 139 {
 140     pthread_t thread;
 141     clockid_t cid;
 142     int s;
 143
 144     s = pthread_create(&thread, NULL, thread_start, NULL);
 145     if (s != 0)
 146         handle_error_en(s, "pthread_create");
 147
 148     printf("Main thread sleeping\en");
 149     sleep(1);
 150
 151     printf("Main thread consuming some CPU time...\en");
 152     for (unsigned int j = 0; j < 2000000; j++)
 153         getppid();
 154
 155     pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);
 156
 157     s = pthread_getcpuclockid(pthread_self(), &cid);
 158     if (s != 0)
 159         handle_error_en(s, "pthread_getcpuclockid");
 160     pclock("Main thread CPU time:   ", cid);
 161
 162     /* The preceding 4 lines of code could have been replaced by:
 163        pclock("Main thread CPU time:   ", CLOCK_THREAD_CPUTIME_ID); */
 164
 165     s = pthread_getcpuclockid(thread, &cid);
 166     if (s != 0)
 167         handle_error_en(s, "pthread_getcpuclockid");
 168     pclock("Subthread CPU time: 1    ", cid);
 169
 170     exit(EXIT_SUCCESS);         /* Terminates both threads */
 171 }
 172 .EE
 173 .\" SRC END
 174 .SH SEE ALSO
 175 .BR clock_gettime (2),
 176 .BR clock_settime (2),
 177 .BR timer_create (2),
 178 .BR clock_getcpuclockid (3),
 179 .BR pthread_self (3),
 180 .BR pthreads (7),
 181 .BR time (7)