1 .\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003
2 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003
3 .\" Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" 2003-08-23 Martin Schulze <joey@infodrom.org> improvements
28 .\" 2003-08-24 aeb, large parts rewritten
29 .\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note
31 .TH CLOCK_GETRES 2 2020-04-11 "" "Linux Programmer's Manual"
33 clock_getres, clock_gettime, clock_settime \- clock and time functions
37 .BI "int clock_getres(clockid_t " clockid ", struct timespec *" res );
39 .BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp );
41 .BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp );
43 Link with \fI\-lrt\fP (only for glibc versions before 2.17).
46 Feature Test Macro Requirements for glibc (see
47 .BR feature_test_macros (7)):
55 _POSIX_C_SOURCE\ >=\ 199309L
61 finds the resolution (precision) of the specified clock
65 is non-NULL, stores it in the \fIstruct timespec\fP pointed to by
67 The resolution of clocks depends on the implementation and cannot be
68 configured by a particular process.
69 If the time value pointed to by the argument
75 then it is truncated to a multiple of
82 retrieve and set the time of the specified clock
91 structures, as specified in
97 time_t tv_sec; /* seconds */
98 long tv_nsec; /* nanoseconds */
105 argument is the identifier of the particular clock on which to act.
106 A clock may be system-wide and hence visible for all processes, or
107 per-process if it measures time only within a single process.
109 All implementations support the system-wide real-time clock,
110 which is identified by
112 Its time represents seconds and nanoseconds since the Epoch.
113 When its time is changed, timers for a relative interval are
114 unaffected, but timers for an absolute point in time are affected.
116 More clocks may be implemented.
117 The interpretation of the
118 corresponding time values and the effect on timers is unspecified.
120 Sufficiently recent versions of glibc and the Linux kernel
121 support the following clocks:
124 A settable system-wide clock that measures real (i.e., wall-clock) time.
125 Setting this clock requires appropriate privileges.
126 This clock is affected by discontinuous jumps in the system time
127 (e.g., if the system administrator manually changes the clock),
128 and by the incremental adjustments performed by
132 .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)"
140 .BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)"
141 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
142 A faster but less precise version of
144 This clock is not settable.
145 Use when you need very fast, but not fine-grained timestamps.
146 Requires per-architecture support,
147 and probably also architecture support for this flag in the
150 .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)"
151 .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4
152 A nonsettable system-wide clock derived from wall-clock time
153 but ignoring leap seconds.
155 not experience discontinuities and backwards jumps caused by NTP
156 inserting leap seconds as
160 The acronym TAI refers to International Atomic Time.
163 A nonsettable system-wide clock that
164 represents monotonic time since\(emas described
165 by POSIX\(em"some unspecified point in the past".
166 On Linux, that point corresponds to the number of seconds that the system
167 has been running since it was booted.
171 clock is not affected by discontinuous jumps in the system time
172 (e.g., if the system administrator manually changes the clock),
173 but is affected by the incremental adjustments performed by
176 This clock does not count time that the system is suspended.
179 variants guarantee that the time returned by consecutive calls will not go
180 backwards, but successive calls may\(emdepending on the architecture\(emreturn
181 identical (not-increased) time values.
183 .BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
184 .\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
185 A faster but less precise version of
186 .BR CLOCK_MONOTONIC .
187 Use when you need very fast, but not fine-grained timestamps.
188 Requires per-architecture support,
189 and probably also architecture support for this flag in the
192 .BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)"
193 .\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz
195 .BR CLOCK_MONOTONIC ,
196 but provides access to a raw hardware-based time
197 that is not subject to NTP adjustments or
198 the incremental adjustments performed by
200 This clock does not count time that the system is suspended.
202 .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)"
203 .\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0
204 .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0
205 A nonsettable system-wide clock that is identical to
206 .BR CLOCK_MONOTONIC ,
207 except that it also includes any time that the system is suspended.
208 This allows applications to get a suspend-aware monotonic clock
209 without having to deal with the complications of
211 which may have discontinuities if the time is changed using
215 .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0; Linux-specific)"
222 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
223 This is a clock that measures CPU time consumed by this process
224 (i.e., CPU time consumed by all threads in the process).
225 On Linux, this clock is not settable.
227 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
228 This is a clock that measures CPU time consumed by this thread.
229 On Linux, this clock is not settable.
231 Linux also implements dynamic clock instances as described below.
232 .SH DYNAMIC CLOCKS " (since Linux 2.6.39)"
233 In addition to hard coded SYS-V style clock ids, Linux also supports
234 POSIX clock operations on certain character devices.
236 called "dynamic" clocks.
237 Using the appropriate macros, open file
238 descriptors may be converted into clock ids and passed to
239 .BR clock_gettime (),
240 .BR clock_settime (),
243 The follow example shows how to convert a file descriptor into a
249 #define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD)
250 #define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3))
256 fd = open("/dev/ptp0", O_RDWR);
257 clkid = FD_TO_CLOCKID(fd);
258 clock_gettime(clkid, &tv);
262 .BR clock_gettime (),
263 .BR clock_settime (),
266 return 0 for success, or \-1 for failure (in which case
268 is set appropriately).
273 points outside the accessible address space.
278 specified is invalid for one of two reasons.
279 Either the SYS-V style
280 hard coded positive value is out of range, or the dynamic clock id
281 does not refer to a valid instance of a clock object.
282 .\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID
283 .\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be
287 .RB ( clock_settime ()):
291 is outside the range [0..999,999,999].
296 specified in a call to
298 is not a settable clock.
301 The operation is not supported by the dynamic POSIX clock device
304 .BR EINVAL " (since Linux 4.3)"
305 .\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
312 attempted to set the time to a value less than
313 the current value of the
318 The hot-plugable device (like USB for example) represented by a
321 has disappeared after its character device was opened.
325 does not have permission to set the clock indicated.
329 does not have write permission for the dynamic POSIX
330 clock device indicated.
332 These system calls first appeared in Linux 2.6.
334 For an explanation of the terms used in this section, see
340 Interface Attribute Value
343 .BR clock_gettime (),
345 T} Thread safety MT-Safe
349 POSIX.1-2001, POSIX.1-2008, SUSv2.
351 On POSIX systems on which these functions are available, the symbol
353 is defined in \fI<unistd.h>\fP to a value greater than 0.
355 .BR _POSIX_MONOTONIC_CLOCK ,
357 .B _POSIX_THREAD_CPUTIME
359 .BR CLOCK_MONOTONIC ,
360 .BR CLOCK_PROCESS_CPUTIME_ID ,
361 .B CLOCK_THREAD_CPUTIME_ID
366 POSIX.1 specifies the following:
369 Setting the value of the
373 shall have no effect on threads that are blocked waiting for a relative time
374 service based upon this clock, including the
376 function; nor on the expiration of relative timers based upon this clock.
377 Consequently, these time services shall expire when the requested relative
378 interval elapses, independently of the new or old value of the clock.
381 According to POSIX.1-2001, a process with "appropriate privileges" may set the
382 .B CLOCK_PROCESS_CPUTIME_ID
384 .B CLOCK_THREAD_CPUTIME_ID
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
391 .SS C library/kernel differences
392 On some architectures, an implementation of
397 .SS Historical note for SMP systems
398 Before Linux added kernel support for
399 .B CLOCK_PROCESS_CPUTIME_ID
401 .BR CLOCK_THREAD_CPUTIME_ID ,
402 glibc implemented these clocks on many platforms using timer
403 registers from the CPUs
404 (TSC on i386, AR.ITC on Itanium).
405 These registers may differ between CPUs and as a consequence
406 these clocks may return
408 if a process is migrated to another CPU.
410 If the CPUs in an SMP system have different clock sources, then
411 there is no way to maintain a correlation between the timer registers since
412 each CPU will run at a slightly different frequency.
413 If that is the case, then
414 .I clock_getcpuclockid(0)
417 to signify this condition.
418 The two clocks will then be useful only if it
419 can be ensured that a process stays on a certain CPU.
421 The processors in an SMP system do not start all at exactly the same
422 time and therefore the timer registers are typically running at an offset.
423 Some architectures include code that attempts to limit these offsets on bootup.
424 However, the code cannot guarantee to accurately tune the offsets.
425 Glibc contains no provisions to deal with these offsets (unlike the Linux
427 Typically these offsets are small and therefore the effects may be
428 negligible in most cases.
431 the wrapper functions for the system calls described in this page avoid
432 the abovementioned problems by employing the kernel implementation of
433 .B CLOCK_PROCESS_CPUTIME_ID
435 .BR CLOCK_THREAD_CPUTIME_ID ,
436 on systems that provide such an implementation
437 (i.e., Linux 2.6.12 and later).
439 The program below demonstrates the use of
444 This is an example of what we might see when running the program:
448 $ \fB./clock_times x\fP
449 CLOCK_REALTIME : 1585985459.446 (18356 days + 7h 30m 59s)
450 resolution: 0.000000001
451 CLOCK_TAI : 1585985496.447 (18356 days + 7h 31m 36s)
452 resolution: 0.000000001
453 CLOCK_MONOTONIC: 52395.722 (14h 33m 15s)
454 resolution: 0.000000001
455 CLOCK_BOOTTIME : 72691.019 (20h 11m 31s)
456 resolution: 0.000000001
464 Licensed under GNU General Public License v2 or later.
466 #define _XOPEN_SOURCE 600
473 #define SECS_IN_DAY (24 * 60 * 60)
476 displayClock(clockid_t clock, char *name, bool showRes)
480 if (clock_gettime(clock, &ts) == \-1) {
481 perror("clock_gettime");
485 printf("%\-15s: %10ld.%03ld (", name,
486 (long) ts.tv_sec, ts.tv_nsec / 1000000);
488 long days = ts.tv_sec / SECS_IN_DAY;
490 printf("%ld days + ", days);
492 printf("%2ldh %2ldm %2lds", (ts.tv_sec % SECS_IN_DAY) / 3600,
493 (ts.tv_sec % 3600) / 60, ts.tv_sec % 60);
496 if (clock_getres(clock, &ts) == \-1) {
497 perror("clock_getres");
502 printf(" resolution: %10ld.%09ld\en",
503 (long) ts.tv_sec, ts.tv_nsec);
507 main(int argc, char *argv[])
509 bool showRes = argc > 1;
511 displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
513 displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
515 displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
516 #ifdef CLOCK_BOOTTIME
517 displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
524 .BR gettimeofday (2),
525 .BR settimeofday (2),
528 .BR clock_getcpuclockid (3),
531 .BR pthread_getcpuclockid (3),
534 .BR time_namespaces (7),