Debian Codegraph @

upstream/fedora-44/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-11-03 "Linux man-pages 6.13"
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 <sys/time.h>
109 #include <time.h>
110 #include <unistd.h>
111 \&
112 #define handle_error(msg) \[rs]
113 do { perror(msg); exit(EXIT_FAILURE); } while (0)
114 \&
115 #define handle_error_en(en, msg) \[rs]
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\[rs]n");
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\[rs]n", (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\[rs]n");
149 sleep(1);
150 \&
151 printf("Main thread consuming some CPU time...\[rs]n");
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)