Debian Codegraph @

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