Debian Codegraph @

upstream/debian-unstable/man3/pthread_getcpuclockid.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_getcpuclockid 3 2025-08-20 "Linux man-pages 6.18"
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 .P
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 ATTRIBUTES
48 For an explanation of the terms used in this section, see
49 .BR attributes (7).
50 .TS
51 allbox;
52 lbx lb lb
53 l l l.
54 Interface Attribute Value
55 T{
56 .na
57 .nh
58 .BR pthread_getcpuclockid ()
59 T} Thread safety MT-Safe
60 .TE
61 .SH STANDARDS
62 POSIX.1-2008.
63 .SH HISTORY
64 glibc 2.2.
65 POSIX.1-2001.
66 .SH NOTES
67 When
68 .I thread
69 refers to the calling thread,
70 this function returns an identifier that refers to the same clock
71 manipulated by
72 .BR clock_gettime (2)
73 and
74 .BR clock_settime (2)
75 when given the clock ID
76 .BR CLOCK_THREAD_CPUTIME_ID .
77 .SH EXAMPLES
78 The program below creates a thread and then uses
79 .BR clock_gettime (2)
80 to retrieve the total process CPU time,
81 and the per-thread CPU time consumed by the two threads.
82 The following shell session shows an example run:
83 .P
84 .in +4n
85 .EX
86 .RB $ " ./a.out" ;
87 Main thread sleeping
88 Subthread starting infinite loop
89 Main thread consuming some CPU time...
90 Process total CPU time: 1.368
91 Main thread CPU time: 0.376
92 Subthread CPU time: 0.992
93 .EE
94 .in
95 .SS Program source
96 \&
97 .\" SRC BEGIN (pthread_getcpuclockid.c)
98 .EX
99 /* Link with "\-lrt" */
100 \&
101 #include <err.h>
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 <sys/time.h>
109 #include <time.h>
110 #include <unistd.h>
111 \&
112 static void *
113 thread_start(void *arg)
114 {
115 printf("Subthread starting infinite loop\[rs]n");
116 for (;;)
117 continue;
118 }
119 \&
120 static void
121 pclock(char *msg, clockid_t cid)
122 {
123 struct timespec ts;
124 \&
125 printf("%s", msg);
126 if (clock_gettime(cid, &ts) == \-1)
127 err(EXIT_FAILURE, "clock_gettime");
128 printf("%4jd.%03ld\[rs]n", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
129 }
130 \&
131 int
132 main(void)
133 {
134 pthread_t thread;
135 clockid_t cid;
136 int s;
137 \&
138 s = pthread_create(&thread, NULL, thread_start, NULL);
139 if (s != 0)
140 errc(EXIT_FAILURE, s, "pthread_create");
141 \&
142 printf("Main thread sleeping\[rs]n");
143 sleep(1);
144 \&
145 printf("Main thread consuming some CPU time...\[rs]n");
146 for (unsigned int j = 0; j < 2000000; j++)
147 getppid();
148 \&
149 pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID);
150 \&
151 s = pthread_getcpuclockid(pthread_self(), &cid);
152 if (s != 0)
153 errc(EXIT_FAILURE, s, "pthread_getcpuclockid");
154 pclock("Main thread CPU time: ", cid);
155 \&
156 /* The preceding 4 lines of code could have been replaced by:
157 pclock("Main thread CPU time: ", CLOCK_THREAD_CPUTIME_ID); */
158 \&
159 s = pthread_getcpuclockid(thread, &cid);
160 if (s != 0)
161 errc(EXIT_FAILURE, s, "pthread_getcpuclockid");
162 pclock("Subthread CPU time: 1 ", cid);
163 \&
164 exit(EXIT_SUCCESS); /* Terminates both threads */
165 }
166 .EE
167 .\" SRC END
168 .SH SEE ALSO
169 .BR clock_gettime (2),
170 .BR clock_settime (2),
171 .BR timer_create (2),
172 .BR clock_getcpuclockid (3),
173 .BR pthread_self (3),
174 .BR pthreads (7),
175 .BR time (7)