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 clk_id, struct timespec *res);
12
13       int clock_gettime(clockid_t clk_id, struct timespec *tp);
14
15       int clock_settime(clockid_t clk_id, 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 clk_id, 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 clk_id.
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 clk_id 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              System-wide  clock  that  measures real (i.e., wall-clock) time.
62              Setting this clock requires appropriate privileges.  This  clock
63              is  affected by discontinuous jumps in the system time (e.g., if
64              the system administrator manually changes the clock), and by the
65              incremental adjustments performed by adjtime(3) and NTP.
66
67       CLOCK_REALTIME_COARSE (since Linux 2.6.32; Linux-specific)
68              A  faster  but less precise version of CLOCK_REALTIME.  Use when
69              you need very fast, but not fine-grained  timestamps.   Requires
70              per-architecture support, and probably also architecture support
71              for this flag in the vdso(7).
72
73       CLOCK_MONOTONIC
74              Clock that cannot be set and represents monotonic time  since—as
75              described  by  POSIX—"some  unspecified  point in the past".  On
76              Linux, that point corresponds to the number of seconds that  the
77              system has been running since it was booted.
78
79              The CLOCK_MONOTONIC clock is not affected by discontinuous jumps
80              in the system time (e.g., if the system  administrator  manually
81              changes  the  clock), but is affected by the incremental adjust‐
82              ments performed by adjtime(3) and  NTP.   This  clock  does  not
83              count time that the system is suspended.
84
85       CLOCK_MONOTONIC_COARSE (since Linux 2.6.32; Linux-specific)
86              A  faster but less precise version of CLOCK_MONOTONIC.  Use when
87              you need very fast, but not fine-grained  timestamps.   Requires
88              per-architecture support, and probably also architecture support
89              for this flag in the vdso(7).
90
91       CLOCK_MONOTONIC_RAW (since Linux 2.6.28; Linux-specific)
92              Similar to CLOCK_MONOTONIC, but provides access to a  raw  hard‐
93              ware-based  time  that  is not subject to NTP adjustments or the
94              incremental adjustments performed  by  adjtime(3).   This  clock
95              does not count time that the system is suspended.
96
97       CLOCK_BOOTTIME (since Linux 2.6.39; Linux-specific)
98              Identical  to  CLOCK_MONOTONIC, except it also includes any time
99              that the system is suspended.  This allows applications to get a
100              suspend-aware  monotonic  clock  without having to deal with the
101              complications of CLOCK_REALTIME, which may have  discontinuities
102              if the time is changed using settimeofday(2) or similar.
103
104       CLOCK_PROCESS_CPUTIME_ID (since Linux 2.6.12)
105              Per-process  CPU-time  clock  (measures CPU time consumed by all
106              threads in the process).
107
108       CLOCK_THREAD_CPUTIME_ID (since Linux 2.6.12)
109              Thread-specific CPU-time clock.
110

RETURN VALUE

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

ERRORS

116       EFAULT tp points outside the accessible address space.
117
118       EINVAL The clk_id specified is not supported on this system.
119
120       EINVAL (clock_settime()):  tp.tv_sec  is negative or tp.tv_nsec is out‐
121              side the range [0..999,999,999].
122
123       EINVAL (since Linux 4.3)
124              A call  to  clock_settime()  with  a  clk_id  of  CLOCK_REALTIME
125              attempted to set the time to a value less than the current value
126              of the CLOCK_MONOTONIC clock.
127
128       EPERM  clock_settime() does not have permission to set the clock  indi‐
129              cated.
130

VERSIONS

132       These system calls first appeared in Linux 2.6.
133

ATTRIBUTES

135       For   an   explanation   of   the  terms  used  in  this  section,  see
136       attributes(7).
137
138       ┌─────────────────────────────────┬───────────────┬─────────┐
139Interface                        Attribute     Value   
140       ├─────────────────────────────────┼───────────────┼─────────┤
141clock_getres(), clock_gettime(), │ Thread safety │ MT-Safe │
142clock_settime()                  │               │         │
143       └─────────────────────────────────┴───────────────┴─────────┘
144

CONFORMING TO

146       POSIX.1-2001, POSIX.1-2008, SUSv2.
147

AVAILABILITY

149       On  POSIX  systems  on  which these functions are available, the symbol
150       _POSIX_TIMERS is defined in <unistd.h> to a value greater than 0.   The
151       symbols  _POSIX_MONOTONIC_CLOCK,  _POSIX_CPUTIME, _POSIX_THREAD_CPUTIME
152       indicate      that      CLOCK_MONOTONIC,      CLOCK_PROCESS_CPUTIME_ID,
153       CLOCK_THREAD_CPUTIME_ID are available.  (See also sysconf(3).)
154

NOTES

156       POSIX.1 specifies the following:
157
158              Setting  the  value  of  the CLOCK_REALTIME clock via clock_set‐
159              time() shall have no effect on threads that are blocked  waiting
160              for a relative time service based upon this clock, including the
161              nanosleep() function; nor on the expiration of  relative  timers
162              based  upon this clock.  Consequently, these time services shall
163              expire when the requested relative  interval  elapses,  indepen‐
164              dently of the new or old value of the clock.
165
166   C library/kernel differences
167       On some architectures, an implementation of clock_gettime() is provided
168       in the vdso(7).
169
170   Historical note for SMP systems
171       Before Linux added  kernel  support  for  CLOCK_PROCESS_CPUTIME_ID  and
172       CLOCK_THREAD_CPUTIME_ID,  glibc  implemented these clocks on many plat‐
173       forms using timer registers from the CPUs (TSC on i386, AR.ITC on  Ita‐
174       nium).   These  registers  may differ between CPUs and as a consequence
175       these clocks may return bogus results  if  a  process  is  migrated  to
176       another CPU.
177
178       If  the  CPUs in an SMP system have different clock sources, then there
179       is no way to maintain a correlation between the timer  registers  since
180       each  CPU  will  run at a slightly different frequency.  If that is the
181       case, then clock_getcpuclockid(0) will return ENOENT  to  signify  this
182       condition.   The  two  clocks  will  then  be  useful only if it can be
183       ensured that a process stays on a certain CPU.
184
185       The processors in an SMP system do not start all at  exactly  the  same
186       time and therefore the timer registers are typically running at an off‐
187       set.  Some architectures include code that attempts to limit these off‐
188       sets  on bootup.  However, the code cannot guarantee to accurately tune
189       the offsets.  Glibc contains no provisions to deal with  these  offsets
190       (unlike  the  Linux  Kernel).   Typically  these  offsets are small and
191       therefore the effects may be negligible in most cases.
192
193       Since glibc 2.4, the wrapper functions for the system  calls  described
194       in  this page avoid the abovementioned problems by employing the kernel
195       implementation of CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID,
196       on  systems that provide such an implementation (i.e., Linux 2.6.12 and
197       later).
198

BUGS

200       According to POSIX.1-2001, a process with "appropriate privileges"  may
201       set  the  CLOCK_PROCESS_CPUTIME_ID  and  CLOCK_THREAD_CPUTIME_ID clocks
202       using clock_settime().  On Linux, these clocks are not settable  (i.e.,
203       no process has "appropriate privileges").
204

SEE ALSO

206       date(1),   gettimeofday(2),   settimeofday(2),   time(2),   adjtime(3),
207       clock_getcpuclockid(3), ctime(3),  ftime(3),  pthread_getcpuclockid(3),
208       sysconf(3), time(7), vdso(7), hwclock(8)
209

COLOPHON

211       This  page  is  part of release 5.02 of the Linux man-pages project.  A
212       description of the project, information about reporting bugs,  and  the
213       latest     version     of     this    page,    can    be    found    at
214       https://www.kernel.org/doc/man-pages/.
215
216
217
218                                  2019-03-06                   CLOCK_GETRES(2)
Impressum