man3/pthread_getcpuclockid.3

   1 '\" t
   2 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH pthread_getcpuclockid 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock
  10 .SH LIBRARY
  11 POSIX threads library
  12 .RI ( libpthread ", " \-lpthread )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <pthread.h>
  16 .B #include <time.h>
  17 .P
  18 .BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid );
  19 .fi
  20 .SH DESCRIPTION
  21 The
  22 .BR pthread_getcpuclockid ()
  23 function obtains the ID of the CPU-time clock of the thread whose ID is
  24 given in
  25 .IR thread ,
  26 and returns it in the location pointed to by
  27 .IR clockid .
  28 .\" The clockid is constructed as follows:
  29 .\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE)
  30 .\" where CLOCK_IDFIELD_SIZE is 3.
  31 .SH RETURN VALUE
  32 On success, this function returns 0;
  33 on error, it returns a nonzero error number.
  34 .SH ERRORS
  35 .TP
  36 .B ENOENT
  37 .\" CLOCK_THREAD_CPUTIME_ID not defined
  38 Per-thread CPU time clocks are not supported by the system.
  39 .\"
  40 .\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would
  41 .\" be possible if kernel thread IDs took more than 29 bits (which
  42 .\" they currently cannot).
  43 .TP
  44 .B ESRCH
  45 No thread with the ID
  46 .I thread
  47 could be found.
  48 .SH ATTRIBUTES
  49 For an explanation of the terms used in this section, see
  50 .BR attributes (7).
  51 .TS
  52 allbox;
  53 lbx lb lb
  54 l l l.
  55 Interface       Attribute       Value
  56 T{
  57 .na
  58 .nh
  59 .BR pthread_getcpuclockid ()
  60 T}      Thread safety   MT-Safe
  61 .TE
  62 .SH STANDARDS
  63 POSIX.1-2008.
  64 .SH HISTORY
  65 glibc 2.2.
  66 POSIX.1-2001.
  67 .SH NOTES
  68 When
  69 .I thread
  70 refers to the calling thread,
  71 this function returns an identifier that refers to the same clock
  72 manipulated by
  73 .BR clock_gettime (2)
  74 and
  75 .BR clock_settime (2)
  76 when given the clock ID
  77 .BR CLOCK_THREAD_CPUTIME_ID .
  78 .SH EXAMPLES
  79 The program below creates a thread and then uses
  80 .BR clock_gettime (2)
  81 to retrieve the total process CPU time,
  82 and the per-thread CPU time consumed by the two threads.
  83 The following shell session shows an example run:
  84 .P
  85 .in +4n
  86 .EX
  87 $ \fB./a.out\fP
  88 Main thread sleeping
  89 Subthread starting infinite loop
  90 Main thread consuming some CPU time...
  91 Process total CPU time:    1.368
  92 Main thread CPU time:      0.376
  93 Subthread CPU time:        0.992
  94 .EE
  95 .in
  96 .SS Program source
  97 \&
  98 .\" SRC BEGIN (pthread_getcpuclockid.c)
  99 .EX
 100 /* Link with "\-lrt" */
 101 \&
 102 #include <errno.h>
 103 #include <pthread.h>
 104 #include <stdint.h>
 105 #include <stdio.h>
 106 #include <stdlib.h>
 107 #include <string.h>
 108 #include <time.h>
 109 #include <unistd.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(void)
 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 (unsigned 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 .\" SRC END
 173 .SH SEE ALSO
 174 .BR clock_gettime (2),
 175 .BR clock_settime (2),
 176 .BR timer_create (2),
 177 .BR clock_getcpuclockid (3),
 178 .BR pthread_self (3),
 179 .BR pthreads (7),
 180 .BR time (7)