Debian Codegraph @

upstream/mageia-cauldron/man2/clock_getres.2

raw
1 '\" t
2 .\" Copyright 2003, Nick Clifford <[email protected]>
3 .\" Copyright 2003, Andries E. Brouwer <[email protected]>
4 .\" Copyright 2020, Michael Kerrisk <[email protected]>
5 .\" Copyright, the authors of the Linux man-pages project
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .TH clock_getres 2 2026-02-08 "Linux man-pages 6.17"
10 .SH NAME
11 clock_getres, clock_gettime, clock_settime \- clock and time functions
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc ),
15 since glibc 2.17
16 .P
17 Before glibc 2.17,
18 Real-time library
19 .RI ( librt ,\~ \-lrt )
20 .SH SYNOPSIS
21 .nf
22 .B #include <time.h>
23 .P
24 .BI "int clock_getres(clockid_t " clockid ", struct timespec *_Nullable " res );
25 .P
26 .BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp );
27 .BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp );
28 .fi
29 .P
30 .RS -4
31 Feature Test Macro Requirements for glibc (see
32 .BR feature_test_macros (7)):
33 .RE
34 .P
35 .BR clock_getres (),
36 .BR clock_gettime (),
37 .BR clock_settime ():
38 .nf
39 _POSIX_C_SOURCE >= 199309L
40 .fi
41 .SH DESCRIPTION
42 The function
43 .BR clock_getres ()
44 finds the resolution (precision) of the specified clock
45 .IR clockid ,
46 and, if
47 .I res
48 is non-NULL, stores it in the
49 .I struct\ timespec
50 pointed to by
51 .IR res .
52 The resolution of clocks depends on the implementation and cannot be
53 configured by a particular process.
54 If the time value pointed to by the argument
55 .I tp
56 of
57 .BR clock_settime ()
58 is not a multiple of
59 .IR res ,
60 then it is truncated to a multiple of
61 .IR res .
62 .P
63 The functions
64 .BR clock_gettime ()
65 and
66 .BR clock_settime ()
67 retrieve and set the time of the specified clock
68 .IR clockid .
69 .P
70 The
71 .I res
72 and
73 .I tp
74 arguments are
75 .BR timespec (3)
76 structures.
77 .P
78 The
79 .I clockid
80 argument is the identifier of the particular clock on which to act.
81 A clock may be system-wide and hence visible for all processes, or
82 per-process if it measures time only within a single process.
83 .P
84 All implementations support the system-wide real-time clock,
85 which is identified by
86 .BR CLOCK_REALTIME .
87 Its time represents seconds and nanoseconds since the Epoch.
88 When its time is changed, timers for a relative interval are
89 unaffected, but timers for an absolute point in time are affected.
90 .P
91 More clocks may be implemented.
92 The interpretation of the
93 corresponding time values and the effect on timers is unspecified.
94 .P
95 Sufficiently recent versions of glibc and the Linux kernel
96 support the following clocks:
97 .TP
98 .B CLOCK_REALTIME
99 A settable system-wide clock that measures real (i.e., wall-clock) time.
100 Setting this clock requires appropriate privileges.
101 This clock is affected by discontinuous jumps in the system time
102 (e.g., if the system administrator manually changes the clock),
103 and by frequency adjustments performed by NTP and similar applications via
104 .BR adjtime (3),
105 .BR adjtimex (2),
106 .BR clock_adjtime (2),
107 and
108 .BR ntp_adjtime (3).
109 This clock normally counts the number of seconds since
110 1970-01-01 00:00:00 Coordinated Universal Time (UTC)
111 except that it ignores leap seconds;
112 near a leap second it is typically adjusted by NTP
113 to stay roughly in sync with UTC.
114 .TP
115 .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)"
116 Like
117 .BR CLOCK_REALTIME ,
118 but not settable.
119 See
120 .BR timer_create (2)
121 for further details.
122 .TP
123 .BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)"
124 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
125 A faster but less precise version of
126 .BR CLOCK_REALTIME .
127 This clock is not settable.
128 Use when you need very fast, but not fine-grained timestamps.
129 Requires per-architecture support,
130 and probably also architecture support for this flag in the
131 .BR vdso (7).
132 .TP
133 .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)"
134 .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4
135 A nonsettable system-wide clock derived from wall-clock time
136 but counting leap seconds.
137 This clock does
138 not experience discontinuities or frequency adjustments caused by
139 inserting leap seconds as
140 .B CLOCK_REALTIME
141 does.
142 .IP
143 The acronym TAI refers to International Atomic Time.
144 .TP
145 .B CLOCK_MONOTONIC
146 A nonsettable system-wide clock that
147 represents monotonic time since\[em]as described
148 by POSIX\[em]"some unspecified point in the past".
149 On Linux, that point corresponds to the number of seconds that the system
150 has been running since it was booted.
151 .IP
152 The
153 .B CLOCK_MONOTONIC
154 clock is not affected by discontinuous jumps in the system time
155 (e.g., if the system administrator manually changes the clock),
156 but is affected by frequency adjustments.
157 This clock does not count time that the system is suspended.
158 All
159 .B CLOCK_MONOTONIC
160 variants guarantee that the time returned by consecutive calls will not go
161 backwards, but successive calls may\[em]depending on the architecture\[em]return
162 identical (not-increased) time values.
163 .TP
164 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
165 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
166 A faster but less precise version of
167 .BR CLOCK_MONOTONIC .
168 Use when you need very fast, but not fine-grained timestamps.
169 Requires per-architecture support,
170 and probably also architecture support for this flag in the
171 .BR vdso (7).
172 .TP
173 .BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)"
174 .\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz
175 Similar to
176 .BR CLOCK_MONOTONIC ,
177 but provides access to a raw hardware-based time
178 that is not subject to frequency adjustments.
179 This clock does not count time that the system is suspended.
180 .TP
181 .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)"
182 .\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0
183 .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0
184 A nonsettable system-wide clock that is identical to
185 .BR CLOCK_MONOTONIC ,
186 except that it also includes any time that the system is suspended.
187 This allows applications to get a suspend-aware monotonic clock
188 without having to deal with the complications of
189 .BR CLOCK_REALTIME ,
190 which may have discontinuities if the time is changed using
191 .BR settimeofday (2)
192 or similar.
193 .TP
194 .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0; Linux-specific)"
195 Like
196 .BR CLOCK_BOOTTIME .
197 See
198 .BR timer_create (2)
199 for further details.
200 .TP
201 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
202 This is a clock that measures CPU time consumed by this process
203 (i.e., CPU time consumed by all threads in the process).
204 On Linux, this clock is not settable.
205 .TP
206 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
207 This is a clock that measures CPU time consumed by this thread.
208 On Linux, this clock is not settable.
209 .P
210 Linux also implements dynamic clock instances as described below.
211 .SS Dynamic clocks
212 In addition to the hard-coded System-V style clock IDs described above,
213 Linux also supports
214 POSIX clock operations on certain character devices.
215 Such devices are
216 called "dynamic" clocks, and are supported since Linux 2.6.39.
217 .P
218 Using the appropriate macros, open file
219 descriptors may be converted into clock IDs and passed to
220 .BR clock_gettime (),
221 .BR clock_settime (),
222 and
223 .BR clock_adjtime (2).
224 The following example shows how to convert a file descriptor into a
225 dynamic clock ID.
226 .P
227 .in +4n
228 .EX
229 #define CLOCKFD 3
230 #define FD_TO_CLOCKID(fd) ((\[ti](clockid_t) (fd) << 3) | CLOCKFD)
231 #define CLOCKID_TO_FD(clk) ((unsigned int) \[ti]((clk) >> 3))
232 \&
233 struct timespec ts;
234 clockid_t clkid;
235 int fd;
236 \&
237 fd = open("/dev/ptp0", O_RDWR);
238 clkid = FD_TO_CLOCKID(fd);
239 clock_gettime(clkid, &ts);
240 .EE
241 .in
242 .SH RETURN VALUE
243 .BR clock_gettime (),
244 .BR clock_settime (),
245 and
246 .BR clock_getres ()
247 return 0 for success.
248 On error, \-1 is returned and
249 .I errno
250 is set to indicate the error.
251 .SH ERRORS
252 .TP
253 .B EACCES
254 .BR clock_settime ()
255 does not have write permission for the dynamic POSIX
256 clock device indicated.
257 .TP
258 .B EFAULT
259 .I tp
260 points outside the accessible address space.
261 .TP
262 .B EINVAL
263 The
264 .I clockid
265 specified is invalid for one of two reasons.
266 Either the System-V style
267 hard coded positive value is out of range, or the dynamic clock ID
268 does not refer to a valid instance of a clock object.
269 .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID
270 .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be
271 .\" EPERM.
272 .TP
273 .B EINVAL
274 .RB ( clock_settime ()):
275 .I tp.tv_sec
276 is negative or
277 .I tp.tv_nsec
278 is outside the range [0, 999,999,999].
279 .TP
280 .B EINVAL
281 The
282 .I clockid
283 specified in a call to
284 .BR clock_settime ()
285 is not a settable clock.
286 .TP
287 .BR EINVAL " (since Linux 4.3)"
288 .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
289 A call to
290 .BR clock_settime ()
291 with a
292 .I clockid
293 of
294 .B CLOCK_REALTIME
295 attempted to set the time to a value less than
296 the current value of the
297 .B CLOCK_MONOTONIC
298 clock.
299 .TP
300 .B ENODEV
301 The hot-pluggable device (like USB for example) represented by a
302 dynamic
303 .I clk_id
304 has disappeared after its character device was opened.
305 .TP
306 .B ENOTSUP
307 The operation is not supported by the dynamic POSIX clock device
308 specified.
309 .TP
310 .B EOVERFLOW
311 The timestamp would not fit in
312 .I time_t
313 range.
314 This can happen if an executable with 32-bit
315 .I time_t
316 is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later.
317 However, when the system time is out of
318 .I time_t
319 range in other situations, the behavior is undefined.
320 .TP
321 .B EPERM
322 .BR clock_settime ()
323 does not have permission to set the clock indicated.
324 .SH ATTRIBUTES
325 For an explanation of the terms used in this section, see
326 .BR attributes (7).
327 .TS
328 allbox;
329 lbx lb lb
330 l l l.
331 Interface Attribute Value
332 T{
333 .na
334 .nh
335 .BR clock_getres (),
336 .BR clock_gettime (),
337 .BR clock_settime ()
338 T} Thread safety MT-Safe
339 .TE
340 .SH VERSIONS
341 POSIX.1 specifies the following:
342 .RS
343 .P
344 Setting the value of the
345 .B CLOCK_REALTIME
346 clock via
347 .BR clock_settime ()
348 shall have no effect on threads that are blocked waiting for a relative time
349 service based upon this clock, including the
350 .BR nanosleep ()
351 function;
352 nor on the expiration of relative timers based upon this clock.
353 Consequently,
354 these time services shall expire when the requested relative interval elapses,
355 independently of the new or old value of the clock.
356 .RE
357 .P
358 According to POSIX.1-2001, a process with "appropriate privileges" may set the
359 .B CLOCK_PROCESS_CPUTIME_ID
360 and
361 .B CLOCK_THREAD_CPUTIME_ID
362 clocks using
363 .BR clock_settime ().
364 On Linux, these clocks are not settable
365 (i.e., no process has "appropriate privileges").
366 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972
367 .SS C library/kernel differences
368 On some architectures, an implementation of
369 .BR clock_gettime ()
370 is provided in the
371 .BR vdso (7).
372 .SH STANDARDS
373 POSIX.1-2024.
374 .SH HISTORY
375 POSIX.1-1996,
376 Linux 2.6.
377 .P
378 On POSIX systems on which these functions are available, the symbol
379 .B _POSIX_TIMERS
380 is defined in
381 .I <unistd.h>
382 to a value greater than 0.
383 POSIX.1-2008 makes these functions mandatory.
384 .P
385 The symbols
386 .BR _POSIX_MONOTONIC_CLOCK ,
387 .BR _POSIX_CPUTIME ,
388 .B _POSIX_THREAD_CPUTIME
389 indicate that
390 .BR CLOCK_MONOTONIC ,
391 .BR CLOCK_PROCESS_CPUTIME_ID ,
392 .B CLOCK_THREAD_CPUTIME_ID
393 are available.
394 (See also
395 .BR sysconf (3).)
396 .\"
397 .P
398 POSIX.1-2024 made
399 .B CLOCK_MONOTONIC
400 mandatory.
401 .SS Historical note for SMP systems
402 Before Linux added kernel support for
403 .B CLOCK_PROCESS_CPUTIME_ID
404 and
405 .BR CLOCK_THREAD_CPUTIME_ID ,
406 glibc implemented these clocks on many platforms using timer
407 registers from the CPUs
408 (TSC on i386, AR.ITC on Itanium).
409 These registers may differ between CPUs and as a consequence
410 these clocks may return
411 .B bogus results
412 if a process is migrated to another CPU.
413 .P
414 If the CPUs in an SMP system have different clock sources, then
415 there is no way to maintain a correlation between the timer registers since
416 each CPU will run at a slightly different frequency.
417 If that is the case, then
418 .I clock_getcpuclockid(0)
419 will return
420 .B ENOENT
421 to signify this condition.
422 The two clocks will then be useful only if it
423 can be ensured that a process stays on a certain CPU.
424 .P
425 The processors in an SMP system do not start all at exactly the same
426 time and therefore the timer registers are typically running at an offset.
427 Some architectures include code that attempts to limit these offsets on bootup.
428 However, the code cannot guarantee to accurately tune the offsets.
429 glibc contains no provisions to deal with these offsets (unlike the Linux
430 Kernel).
431 Typically these offsets are small and therefore the effects may be
432 negligible in most cases.
433 .P
434 Since glibc 2.4,
435 the wrapper functions for the system calls described in this page avoid
436 the abovementioned problems by employing the kernel implementation of
437 .B CLOCK_PROCESS_CPUTIME_ID
438 and
439 .BR CLOCK_THREAD_CPUTIME_ID ,
440 on systems that provide such an implementation
441 (i.e., Linux 2.6.12 and later).
442 .SH EXAMPLES
443 The program below demonstrates the use of
444 .BR clock_gettime ()
445 and
446 .BR clock_getres ()
447 with various clocks.
448 This is an example of what we might see when running the program:
449 .P
450 .in +4n
451 .EX
452 .RB $ " ./clock_times x" ;
453 CLOCK_REALTIME : 1585985459.446 (18356 days + 7h 30m 59s)
454 resolution: 0.000000001
455 CLOCK_TAI : 1585985496.447 (18356 days + 7h 31m 36s)
456 resolution: 0.000000001
457 CLOCK_MONOTONIC: 52395.722 (14h 33m 15s)
458 resolution: 0.000000001
459 CLOCK_BOOTTIME : 72691.019 (20h 11m 31s)
460 resolution: 0.000000001
461 .EE
462 .in
463 .SS Program source
464 \&
465 .\" SRC BEGIN (clock_getres.c)
466 .EX
467 /* clock_times.c
468 \&
469 Licensed under GNU General Public License v2 or later.
470 */
471 #define _XOPEN_SOURCE 600
472 #include <stdbool.h>
473 #include <stdint.h>
474 #include <stdio.h>
475 #include <stdlib.h>
476 #include <sys/types.h>
477 #include <time.h>
478 \&
479 #define SECS_IN_DAY (24 * 60 * 60)
480 \&
481 static void
482 displayClock(clockid_t clock, const char *name, bool showRes)
483 {
484 long days;
485 struct timespec ts;
486 \&
487 if (clock_gettime(clock, &ts) == \-1) {
488 perror("clock_gettime");
489 exit(EXIT_FAILURE);
490 }
491 \&
492 printf("%\-15s: %10jd.%03ld (", name,
493 (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
494 \&
495 days = ts.tv_sec / SECS_IN_DAY;
496 if (days > 0)
497 printf("%ld days + ", days);
498 \&
499 printf("%2dh %2dm %2ds",
500 (int) (ts.tv_sec % SECS_IN_DAY) / 3600,
501 (int) (ts.tv_sec % 3600) / 60,
502 (int) ts.tv_sec % 60);
503 printf(")\[rs]n");
504 \&
505 if (clock_getres(clock, &ts) == \-1) {
506 perror("clock_getres");
507 exit(EXIT_FAILURE);
508 }
509 \&
510 if (showRes)
511 printf(" resolution: %10jd.%09ld\[rs]n",
512 (intmax_t) ts.tv_sec, ts.tv_nsec);
513 }
514 \&
515 int
516 main(int argc, char *[])
517 {
518 bool showRes = argc > 1;
519 \&
520 displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
521 #ifdef CLOCK_TAI
522 displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
523 #endif
524 displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
525 #ifdef CLOCK_BOOTTIME
526 displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
527 #endif
528 exit(EXIT_SUCCESS);
529 }
530 .EE
531 .\" SRC END
532 .SH SEE ALSO
533 .BR date (1),
534 .BR gettimeofday (2),
535 .BR settimeofday (2),
536 .BR time (2),
537 .BR adjtime (3),
538 .BR clock_getcpuclockid (3),
539 .BR ctime (3),
540 .BR ftime (3),
541 .BR pthread_getcpuclockid (3),
542 .BR sysconf (3),
543 .BR timespec (3),
544 .BR time (7),
545 .BR time_namespaces (7),
546 .BR vdso (7),
547 .BR hwclock (8)