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
138       devices.   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 timeval tv;
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, &tv);
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       EFAULT tp points outside the accessible address space.
164
165       EINVAL The clockid specified is invalid for one of two reasons.  Either
166              the System-V style hard coded positive value is out of range, or
167              the dynamic clock ID does not refer to a  valid  instance  of  a
168              clock object.
169
170       EINVAL (clock_settime()):  tp.tv_sec  is negative or tp.tv_nsec is out‐
171              side the range [0..999,999,999].
172
173       EINVAL The clockid specified in a call to clock_settime() is not a set‐
174              table clock.
175
176       ENOTSUP
177              The operation is not supported by the dynamic POSIX clock device
178              specified.
179
180       EINVAL (since Linux 4.3)
181              A call to  clock_settime()  with  a  clockid  of  CLOCK_REALTIME
182              attempted to set the time to a value less than the current value
183              of the CLOCK_MONOTONIC clock.
184
185       ENODEV The hot-pluggable device (like USB for example) represented by a
186              dynamic  clk_id  has  disappeared after its character device was
187              opened.
188
189       EPERM  clock_settime() does not have permission to set the clock  indi‐
190              cated.
191
192       EACCES clock_settime()  does  not have write permission for the dynamic
193              POSIX clock device indicated.
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
200       attributes(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
231       using clock_settime().  On Linux, these clocks are not settable  (i.e.,
232       no 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
244       another 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
251       ensured 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
269       clock_getres()  with  various  clocks.   This  is an example of what we
270       might see 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 <stdio.h>
291       #include <stdlib.h>
292       #include <stdbool.h>
293       #include <unistd.h>
294
295       #define SECS_IN_DAY (24 * 60 * 60)
296
297       static void
298       displayClock(clockid_t clock, char *name, bool showRes)
299       {
300           struct timespec ts;
301
302           if (clock_gettime(clock, &ts) == -1) {
303               perror("clock_gettime");
304               exit(EXIT_FAILURE);
305           }
306
307           printf("%-15s: %10ld.%03ld (", name,
308                   (long) ts.tv_sec, ts.tv_nsec / 1000000);
309
310           long days = ts.tv_sec / SECS_IN_DAY;
311           if (days > 0)
312               printf("%ld days + ", days);
313
314           printf("%2ldh %2ldm %2lds", (ts.tv_sec % SECS_IN_DAY) / 3600,
315                   (ts.tv_sec % 3600) / 60, ts.tv_sec % 60);
316           printf(")\n");
317
318           if (clock_getres(clock, &ts) == -1) {
319               perror("clock_getres");
320               exit(EXIT_FAILURE);
321           }
322
323           if (showRes)
324               printf("     resolution: %10ld.%09ld\n",
325                       (long) ts.tv_sec, ts.tv_nsec);
326       }
327
328       int
329       main(int argc, char *argv[])
330       {
331           bool showRes = argc > 1;
332
333           displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
334       #ifdef CLOCK_TAI
335           displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
336       #endif
337           displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
338       #ifdef CLOCK_BOOTTIME
339           displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
340       #endif
341           exit(EXIT_SUCCESS);
342       }
343

SEE ALSO

345       date(1),   gettimeofday(2),   settimeofday(2),   time(2),   adjtime(3),
346       clock_getcpuclockid(3),  ctime(3),  ftime(3), pthread_getcpuclockid(3),
347       sysconf(3), time(7), time_namespaces(7), vdso(7), hwclock(8)
348

COLOPHON

350       This page is part of release 5.07 of the Linux  man-pages  project.   A
351       description  of  the project, information about reporting bugs, and the
352       latest    version    of    this    page,    can     be     found     at
353       https://www.kernel.org/doc/man-pages/.
354
355
356
357                                  2020-04-11                   CLOCK_GETRES(2)
Impressum