1CLOCK_GETRES(2)            Linux Programmer's Manual           CLOCK_GETRES(2)
2
3
4

NAME

6       clock_getres, clock_gettime, clock_settime - clock and time functions
7

SYNOPSIS

9       #include <time.h>
10
11       int clock_getres(clockid_t clockid, struct timespec *res);
12
13       int clock_gettime(clockid_t clockid, struct timespec *tp);
14
15       int clock_settime(clockid_t clockid, const struct timespec *tp);
16
17       Link with -lrt (only for glibc versions before 2.17).
18
19   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20
21       clock_getres(), clock_gettime(), clock_settime():
22              _POSIX_C_SOURCE >= 199309L
23

DESCRIPTION

25       The  function  clock_getres()  finds  the resolution (precision) of the
26       specified clock clockid, and, if res is  non-NULL,  stores  it  in  the
27       struct timespec pointed to by res.  The resolution of clocks depends on
28       the implementation and cannot be configured by  a  particular  process.
29       If  the  time value pointed to by the argument tp of clock_settime() is
30       not a multiple of res, then it is truncated to a multiple of res.
31
32       The functions clock_gettime() and clock_settime() retrieve and set  the
33       time of the specified clock clockid.
34
35       The  res  and  tp  arguments  are  timespec structures, as specified in
36       <time.h>:
37
38           struct timespec {
39               time_t   tv_sec;        /* seconds */
40               long     tv_nsec;       /* nanoseconds */
41           };
42
43       The clockid argument is the identifier of the particular clock on which
44       to  act.   A  clock  may  be system-wide and hence visible for all pro‐
45       cesses, or per-process  if  it  measures  time  only  within  a  single
46       process.
47
48       All  implementations  support the system-wide real-time clock, which is
49       identified by CLOCK_REALTIME.  Its time represents seconds and nanosec‐
50       onds  since the Epoch.  When its time is changed, timers for a relative
51       interval are unaffected, but timers for an absolute point in  time  are
52       affected.
53
54       More  clocks may be implemented.  The interpretation of the correspond‐
55       ing time values and the effect on timers is unspecified.
56
57       Sufficiently recent versions of glibc and the Linux kernel support  the
58       following clocks:
59
60       CLOCK_REALTIME
61              A  settable  system-wide  clock  that measures real (i.e., wall-
62              clock) time.  Setting this  clock  requires  appropriate  privi‐
63              leges.   This  clock  is  affected by discontinuous jumps in the
64              system time (e.g., if the system administrator manually  changes
65              the clock), and by the incremental adjustments performed by adj‐
66              time(3) and NTP.
67
68       CLOCK_REALTIME_ALARM (since Linux 3.0; Linux-specific)
69              Like CLOCK_REALTIME, but not settable.  See timer_create(2)  for
70              further details.
71
72       CLOCK_REALTIME_COARSE (since Linux 2.6.32; Linux-specific)
73              A faster but less precise version of CLOCK_REALTIME.  This clock
74              is not settable.  Use when you need very  fast,  but  not  fine-
75              grained  timestamps.   Requires  per-architecture  support,  and
76              probably also architecture support for this flag in the vdso(7).
77
78       CLOCK_TAI (since Linux 3.10; Linux-specific)
79              A nonsettable system-wide clock derived from wall-clock time but
80              ignoring leap seconds.  This clock does not experience disconti‐
81              nuities and backwards jumps caused by NTP inserting leap seconds
82              as CLOCK_REALTIME does.
83
84              The acronym TAI refers to International Atomic Time.
85
86       CLOCK_MONOTONIC
87              A  nonsettable  system-wide clock that represents monotonic time
88              since—as described  by  POSIX—"some  unspecified  point  in  the
89              past".   On  Linux, that point corresponds to the number of sec‐
90              onds that the system has been running since it was booted.
91
92              The CLOCK_MONOTONIC clock is not affected by discontinuous jumps
93              in  the  system time (e.g., if the system administrator manually
94              changes the clock), but is affected by the  incremental  adjust‐
95              ments  performed  by  adjtime(3)  and  NTP.  This clock does not
96              count time that the system is  suspended.   All  CLOCK_MONOTONIC
97              variants  guarantee  that the time returned by consecutive calls
98              will not go backwards, but successive calls may—depending on the
99              architecture—return identical (not-increased) time values.
100
101       CLOCK_MONOTONIC_COARSE (since Linux 2.6.32; Linux-specific)
102              A  faster but less precise version of CLOCK_MONOTONIC.  Use when
103              you need very fast, but not fine-grained  timestamps.   Requires
104              per-architecture support, and probably also architecture support
105              for this flag in the vdso(7).
106
107       CLOCK_MONOTONIC_RAW (since Linux 2.6.28; Linux-specific)
108              Similar to CLOCK_MONOTONIC, but provides access to a  raw  hard‐
109              ware-based  time  that  is not subject to NTP adjustments or the
110              incremental adjustments performed  by  adjtime(3).   This  clock
111              does not count time that the system is suspended.
112
113       CLOCK_BOOTTIME (since Linux 2.6.39; Linux-specific)
114              A nonsettable system-wide clock that is identical to CLOCK_MONO‐
115              TONIC, except that it also includes any time that the system  is
116              suspended.   This  allows  applications  to  get a suspend-aware
117              monotonic clock without having to deal with the complications of
118              CLOCK_REALTIME,  which  may  have discontinuities if the time is
119              changed using settimeofday(2) or similar.
120
121       CLOCK_BOOTTIME_ALARM (since Linux 3.0; Linux-specific)
122              Like CLOCK_BOOTTIME.  See timer_create(2) for further details.
123
124       CLOCK_PROCESS_CPUTIME_ID (since Linux 2.6.12)
125              This is a clock that measures CPU time consumed by this  process
126              (i.e.,  CPU  time  consumed  by all threads in the process).  On
127              Linux, this clock is not settable.
128
129       CLOCK_THREAD_CPUTIME_ID (since Linux 2.6.12)
130              This is a clock that measures CPU time consumed by this  thread.
131              On Linux, this clock is not settable.
132
133       Linux also implements dynamic clock instances as described below.
134
135   Dynamic clocks
136       In addition to the hard-coded System-V style clock IDs described above,
137       Linux also supports POSIX clock operations  on  certain  character  de‐
138       vices.   Such  devices  are  called "dynamic" clocks, and are supported
139       since Linux 2.6.39.
140
141       Using the appropriate macros, open file descriptors  may  be  converted
142       into  clock  IDs  and  passed  to clock_gettime(), clock_settime(), and
143       clock_adjtime(2).  The following example shows how to  convert  a  file
144       descriptor into a dynamic clock ID.
145
146           #define CLOCKFD 3
147           #define FD_TO_CLOCKID(fd)   ((~(clockid_t) (fd) << 3) | CLOCKFD)
148           #define CLOCKID_TO_FD(clk)  ((unsigned int) ~((clk) >> 3))
149
150           struct timespec ts;
151           clockid_t clkid;
152           int fd;
153
154           fd = open("/dev/ptp0", O_RDWR);
155           clkid = FD_TO_CLOCKID(fd);
156           clock_gettime(clkid, &ts);
157

RETURN VALUE

159       clock_gettime(),  clock_settime(), and clock_getres() return 0 for suc‐
160       cess, or -1 for failure (in which case errno is set appropriately).
161

ERRORS

163       EACCES clock_settime() does not have write permission for  the  dynamic
164              POSIX clock device indicated.
165
166       EFAULT tp points outside the accessible address space.
167
168       EINVAL The clockid specified is invalid for one of two reasons.  Either
169              the System-V style hard coded positive value is out of range, or
170              the  dynamic  clock  ID  does not refer to a valid instance of a
171              clock object.
172
173       EINVAL (clock_settime()): tp.tv_sec is negative or tp.tv_nsec  is  out‐
174              side the range [0..999,999,999].
175
176       EINVAL The clockid specified in a call to clock_settime() is not a set‐
177              table clock.
178
179       EINVAL (since Linux 4.3)
180              A call to clock_settime() with a clockid of  CLOCK_REALTIME  at‐
181              tempted  to  set the time to a value less than the current value
182              of the CLOCK_MONOTONIC clock.
183
184       ENODEV The hot-pluggable device (like USB for example) represented by a
185              dynamic  clk_id  has  disappeared after its character device was
186              opened.
187
188       ENOTSUP
189              The operation is not supported by the dynamic POSIX clock device
190              specified.
191
192       EPERM  clock_settime()  does not have permission to set the clock indi‐
193              cated.
194

VERSIONS

196       These system calls first appeared in Linux 2.6.
197

ATTRIBUTES

199       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
200       tributes(7).
201
202       ┌─────────────────────────────────┬───────────────┬─────────┐
203Interface                        Attribute     Value   
204       ├─────────────────────────────────┼───────────────┼─────────┤
205clock_getres(), clock_gettime(), │ Thread safety │ MT-Safe │
206clock_settime()                  │               │         │
207       └─────────────────────────────────┴───────────────┴─────────┘
208

CONFORMING TO

210       POSIX.1-2001, POSIX.1-2008, SUSv2.
211
212       On POSIX systems on which these functions  are  available,  the  symbol
213       _POSIX_TIMERS  is defined in <unistd.h> to a value greater than 0.  The
214       symbols _POSIX_MONOTONIC_CLOCK,  _POSIX_CPUTIME,  _POSIX_THREAD_CPUTIME
215       indicate      that      CLOCK_MONOTONIC,      CLOCK_PROCESS_CPUTIME_ID,
216       CLOCK_THREAD_CPUTIME_ID are available.  (See also sysconf(3).)
217

NOTES

219       POSIX.1 specifies the following:
220
221              Setting the value of the  CLOCK_REALTIME  clock  via  clock_set‐
222              time()  shall have no effect on threads that are blocked waiting
223              for a relative time service based upon this clock, including the
224              nanosleep()  function;  nor on the expiration of relative timers
225              based upon this clock.  Consequently, these time services  shall
226              expire  when  the  requested relative interval elapses, indepen‐
227              dently of the new or old value of the clock.
228
229       According to POSIX.1-2001, a process with "appropriate privileges"  may
230       set the CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks us‐
231       ing clock_settime().  On Linux, these clocks are not settable (i.e., no
232       process has "appropriate privileges").
233
234   C library/kernel differences
235       On some architectures, an implementation of clock_gettime() is provided
236       in the vdso(7).
237
238   Historical note for SMP systems
239       Before Linux added  kernel  support  for  CLOCK_PROCESS_CPUTIME_ID  and
240       CLOCK_THREAD_CPUTIME_ID,  glibc  implemented these clocks on many plat‐
241       forms using timer registers from the CPUs (TSC on i386, AR.ITC on  Ita‐
242       nium).   These  registers  may differ between CPUs and as a consequence
243       these clocks may return bogus results if a process is migrated  to  an‐
244       other CPU.
245
246       If  the  CPUs in an SMP system have different clock sources, then there
247       is no way to maintain a correlation between the timer  registers  since
248       each  CPU  will  run at a slightly different frequency.  If that is the
249       case, then clock_getcpuclockid(0) will return ENOENT  to  signify  this
250       condition.   The  two  clocks will then be useful only if it can be en‐
251       sured that a process stays on a certain CPU.
252
253       The processors in an SMP system do not start all at  exactly  the  same
254       time and therefore the timer registers are typically running at an off‐
255       set.  Some architectures include code that attempts to limit these off‐
256       sets  on bootup.  However, the code cannot guarantee to accurately tune
257       the offsets.  Glibc contains no provisions to deal with  these  offsets
258       (unlike  the  Linux  Kernel).   Typically  these  offsets are small and
259       therefore the effects may be negligible in most cases.
260
261       Since glibc 2.4, the wrapper functions for the system  calls  described
262       in  this page avoid the abovementioned problems by employing the kernel
263       implementation of CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID,
264       on  systems that provide such an implementation (i.e., Linux 2.6.12 and
265       later).
266

EXAMPLES

268       The program below demonstrates the use of clock_gettime() and clock_ge‐
269       tres()  with  various  clocks.  This is an example of what we might see
270       when running the program:
271
272           $ ./clock_times x
273           CLOCK_REALTIME : 1585985459.446 (18356 days +  7h 30m 59s)
274                resolution:          0.000000001
275           CLOCK_TAI      : 1585985496.447 (18356 days +  7h 31m 36s)
276                resolution:          0.000000001
277           CLOCK_MONOTONIC:      52395.722 (14h 33m 15s)
278                resolution:          0.000000001
279           CLOCK_BOOTTIME :      72691.019 (20h 11m 31s)
280                resolution:          0.000000001
281
282   Program source
283
284       /* clock_times.c
285
286          Licensed under GNU General Public License v2 or later.
287       */
288       #define _XOPEN_SOURCE 600
289       #include <time.h>
290       #include <stdint.h>
291       #include <stdio.h>
292       #include <stdlib.h>
293       #include <stdbool.h>
294       #include <unistd.h>
295
296       #define SECS_IN_DAY (24 * 60 * 60)
297
298       static void
299       displayClock(clockid_t clock, const char *name, bool showRes)
300       {
301           struct timespec ts;
302
303           if (clock_gettime(clock, &ts) == -1) {
304               perror("clock_gettime");
305               exit(EXIT_FAILURE);
306           }
307
308           printf("%-15s: %10jd.%03ld (", name,
309                   (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
310
311           long days = ts.tv_sec / SECS_IN_DAY;
312           if (days > 0)
313               printf("%ld days + ", days);
314
315           printf("%2dh %2dm %2ds",
316                   (int) (ts.tv_sec % SECS_IN_DAY) / 3600,
317                   (int) (ts.tv_sec % 3600) / 60,
318                   (int) ts.tv_sec % 60);
319           printf(")\n");
320
321           if (clock_getres(clock, &ts) == -1) {
322               perror("clock_getres");
323               exit(EXIT_FAILURE);
324           }
325
326           if (showRes)
327               printf("     resolution: %10jd.%09ld\n",
328                       (intmax_t) ts.tv_sec, ts.tv_nsec);
329       }
330
331       int
332       main(int argc, char *argv[])
333       {
334           bool showRes = argc > 1;
335
336           displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
337       #ifdef CLOCK_TAI
338           displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
339       #endif
340           displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
341       #ifdef CLOCK_BOOTTIME
342           displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
343       #endif
344           exit(EXIT_SUCCESS);
345       }
346

SEE ALSO

348       date(1),   gettimeofday(2),   settimeofday(2),   time(2),   adjtime(3),
349       clock_getcpuclockid(3),  ctime(3),  ftime(3), pthread_getcpuclockid(3),
350       sysconf(3), time(7), time_namespaces(7), vdso(7), hwclock(8)
351

COLOPHON

353       This page is part of release 5.10 of the Linux  man-pages  project.   A
354       description  of  the project, information about reporting bugs, and the
355       latest    version    of    this    page,    can     be     found     at
356       https://www.kernel.org/doc/man-pages/.
357
358
359
360                                  2020-12-21                   CLOCK_GETRES(2)
Impressum