1clock_getres(2)               System Calls Manual              clock_getres(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc), since glibc 2.17
10
11       Before glibc 2.17, Real-time library (librt, -lrt)
12

SYNOPSIS

14       #include <time.h>
15
16       int clock_getres(clockid_t clockid, struct timespec *_Nullable res);
17
18       int clock_gettime(clockid_t clockid, struct timespec *tp);
19       int clock_settime(clockid_t clockid, const struct timespec *tp);
20
21   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22
23       clock_getres(), clock_gettime(), clock_settime():
24           _POSIX_C_SOURCE >= 199309L
25

DESCRIPTION

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

RETURN VALUE

155       clock_gettime(), clock_settime(), and clock_getres() return 0 for  suc‐
156       cess.  On error, -1 is returned and errno is set to indicate the error.
157

ERRORS

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

ATTRIBUTES

192       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
193       tributes(7).
194
195       ┌────────────────────────────────────────────┬───────────────┬─────────┐
196Interface                                   Attribute     Value   
197       ├────────────────────────────────────────────┼───────────────┼─────────┤
198clock_getres(), clock_gettime(),            │ Thread safety │ MT-Safe │
199clock_settime()                             │               │         │
200       └────────────────────────────────────────────┴───────────────┴─────────┘
201

VERSIONS

203       POSIX.1 specifies the following:
204
205              Setting    the   value   of   the   CLOCK_REALTIME   clock   via
206              clock_settime() shall have no effect on threads that are blocked
207              waiting  for  a  relative  time  service  based upon this clock,
208              including the nanosleep() function; nor  on  the  expiration  of
209              relative timers based upon this clock.  Consequently, these time
210              services shall  expire  when  the  requested  relative  interval
211              elapses, independently of the new or old value of the clock.
212
213       According  to POSIX.1-2001, a process with "appropriate privileges" may
214       set the  CLOCK_PROCESS_CPUTIME_ID  and  CLOCK_THREAD_CPUTIME_ID  clocks
215       using  clock_settime().  On Linux, these clocks are not settable (i.e.,
216       no process has "appropriate privileges").
217
218   C library/kernel differences
219       On some architectures, an implementation of clock_gettime() is provided
220       in the vdso(7).
221

STANDARDS

223       POSIX.1-2008.
224

HISTORY

226       POSIX.1-2001, SUSv2.  Linux 2.6.
227
228       On  POSIX  systems  on  which these functions are available, the symbol
229       _POSIX_TIMERS is defined in <unistd.h> to a value greater than 0.   The
230       symbols  _POSIX_MONOTONIC_CLOCK,  _POSIX_CPUTIME, _POSIX_THREAD_CPUTIME
231       indicate      that      CLOCK_MONOTONIC,      CLOCK_PROCESS_CPUTIME_ID,
232       CLOCK_THREAD_CPUTIME_ID   are   available.    (See   also  sysconf(3).)
233       POSIX.1-2008 makes these APIs mandatory.
234
235   Historical note for SMP systems
236       Before Linux added  kernel  support  for  CLOCK_PROCESS_CPUTIME_ID  and
237       CLOCK_THREAD_CPUTIME_ID,   glibc   implemented  these  clocks  on  many
238       platforms using timer registers from the CPUs (TSC on i386,  AR.ITC  on
239       Itanium).  These registers may differ between CPUs and as a consequence
240       these clocks may return bogus results  if  a  process  is  migrated  to
241       another CPU.
242
243       If  the  CPUs in an SMP system have different clock sources, then there
244       is no way to maintain a correlation between the timer  registers  since
245       each  CPU  will  run at a slightly different frequency.  If that is the
246       case, then clock_getcpuclockid(0) will return ENOENT  to  signify  this
247       condition.   The  two  clocks  will  then  be  useful only if it can be
248       ensured that a process stays on a certain CPU.
249
250       The processors in an SMP system do not start all at  exactly  the  same
251       time  and  therefore  the  timer  registers are typically running at an
252       offset.  Some architectures include code that attempts to  limit  these
253       offsets  on  bootup.   However, the code cannot guarantee to accurately
254       tune the offsets.  glibc contains no  provisions  to  deal  with  these
255       offsets  (unlike  the Linux Kernel).  Typically these offsets are small
256       and therefore the effects may be negligible in most cases.
257
258       Since glibc 2.4, the wrapper functions for the system  calls  described
259       in  this page avoid the abovementioned problems by employing the kernel
260       implementation of CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID,
261       on  systems that provide such an implementation (i.e., Linux 2.6.12 and
262       later).
263

EXAMPLES

265       The  program  below  demonstrates  the  use  of   clock_gettime()   and
266       clock_getres()  with  various  clocks.   This  is an example of what we
267       might see when running the program:
268
269           $ ./clock_times x
270           CLOCK_REALTIME : 1585985459.446 (18356 days +  7h 30m 59s)
271                resolution:          0.000000001
272           CLOCK_TAI      : 1585985496.447 (18356 days +  7h 31m 36s)
273                resolution:          0.000000001
274           CLOCK_MONOTONIC:      52395.722 (14h 33m 15s)
275                resolution:          0.000000001
276           CLOCK_BOOTTIME :      72691.019 (20h 11m 31s)
277                resolution:          0.000000001
278
279   Program source
280
281       /* clock_times.c
282
283          Licensed under GNU General Public License v2 or later.
284       */
285       #define _XOPEN_SOURCE 600
286       #include <stdbool.h>
287       #include <stdint.h>
288       #include <stdio.h>
289       #include <stdlib.h>
290       #include <time.h>
291
292       #define SECS_IN_DAY (24 * 60 * 60)
293
294       static void
295       displayClock(clockid_t clock, const char *name, bool showRes)
296       {
297           long             days;
298           struct timespec  ts;
299
300           if (clock_gettime(clock, &ts) == -1) {
301               perror("clock_gettime");
302               exit(EXIT_FAILURE);
303           }
304
305           printf("%-15s: %10jd.%03ld (", name,
306                  (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
307
308           days = ts.tv_sec / SECS_IN_DAY;
309           if (days > 0)
310               printf("%ld days + ", days);
311
312           printf("%2dh %2dm %2ds",
313                  (int) (ts.tv_sec % SECS_IN_DAY) / 3600,
314                  (int) (ts.tv_sec % 3600) / 60,
315                  (int) 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: %10jd.%09ld\n",
325                      (intmax_t) 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),  timespec(3),  time(7),  time_namespaces(7),  vdso(7),  hw‐
348       clock(8)
349
350
351
352Linux man-pages 6.05              2023-07-20                   clock_getres(2)
Impressum