Debian Codegraph @

upstream/debian-trixie/man3/pthread_getcpuclockid.3

raw
1 '\" t
2 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
3 .\" <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH pthread_getcpuclockid 3 2024-06-15 "Linux man-pages 6.9.1"
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) \[rs]
112 do { perror(msg); exit(EXIT_FAILURE); } while (0)
113 \&
114 #define handle_error_en(en, msg) \[rs]
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\[rs]n");
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\[rs]n", (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\[rs]n");
148 sleep(1);
149 \&
150 printf("Main thread consuming some CPU time...\[rs]n");
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)