1CLOCK_GETRES(3P)           POSIX Programmer's Manual          CLOCK_GETRES(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       clock_getres, clock_gettime, clock_settime — clock and timer functions
13

SYNOPSIS

15       #include <time.h>
16
17       int clock_getres(clockid_t clock_id, struct timespec *res);
18       int clock_gettime(clockid_t clock_id, struct timespec *tp);
19       int clock_settime(clockid_t clock_id, const struct timespec *tp);
20

DESCRIPTION

22       The clock_getres() function shall return the resolution of  any  clock.
23       Clock  resolutions  are  implementation-defined  and cannot be set by a
24       process. If the argument res is not NULL, the resolution of the  speci‐
25       fied  clock  shall be stored in the location pointed to by res.  If res
26       is NULL, the clock resolution is not returned. If the time argument  of
27       clock_settime()  is  not a multiple of res, then the value is truncated
28       to a multiple of res.
29
30       The clock_gettime() function shall return the current value tp for  the
31       specified clock, clock_id.
32
33       The  clock_settime()  function shall set the specified clock, clock_id,
34       to the value specified by tp.  Time values that are between two consec‐
35       utive non-negative integer multiples of the resolution of the specified
36       clock shall be truncated down to the smaller multiple  of  the  resolu‐
37       tion.
38
39       A  clock may be system-wide (that is, visible to all processes) or per-
40       process (measuring time that is meaningful only within a process).  All
41       implementations  shall  support a clock_id of CLOCK_REALTIME as defined
42       in <time.h>.  This clock represents the clock measuring real  time  for
43       the system.  For this clock, the values returned by clock_gettime() and
44       specified by clock_settime() represent the amount of time  (in  seconds
45       and  nanoseconds)  since  the Epoch. An implementation may also support
46       additional clocks. The interpretation of time values for  these  clocks
47       is unspecified.
48
49       If  the  value  of the CLOCK_REALTIME clock is set via clock_settime(),
50       the new value of the clock shall be used to determine the time of expi‐
51       ration  for absolute time services based upon the CLOCK_REALTIME clock.
52       This applies to the time at which armed absolute timers expire.  If the
53       absolute  time  requested  at  the invocation of such a time service is
54       before the new value of the clock, the time service shall expire  imme‐
55       diately as if the clock had reached the requested time normally.
56
57       Setting the value of the CLOCK_REALTIME clock via clock_settime() shall
58       have no effect on threads that are blocked waiting for a relative  time
59       service  based upon this clock, including the nanosleep() function; nor
60       on the expiration of relative timers  based  upon  this  clock.  Conse‐
61       quently,  these  time services shall expire when the requested relative
62       interval elapses, independently of the new or old value of the clock.
63
64       If the Monotonic Clock option is supported, all  implementations  shall
65       support  a clock_id of CLOCK_MONOTONIC defined in <time.h>.  This clock
66       represents the monotonic clock for the  system.  For  this  clock,  the
67       value  returned  by  clock_gettime()  represents the amount of time (in
68       seconds and nanoseconds) since an unspecified point in  the  past  (for
69       example,  system  start-up  time,  or  the  Epoch). This point does not
70       change after system start-up time. The  value  of  the  CLOCK_MONOTONIC
71       clock  cannot  be set via clock_settime().  This function shall fail if
72       it is invoked with a clock_id argument of CLOCK_MONOTONIC.
73
74       The effect of setting a clock via clock_settime() on armed  per-process
75       timers associated with a clock other than CLOCK_REALTIME is implementa‐
76       tion-defined.
77
78       If the value of the CLOCK_REALTIME clock is  set  via  clock_settime(),
79       the new value of the clock shall be used to determine the time at which
80       the  system  shall   awaken   a   thread   blocked   on   an   absolute
81       clock_nanosleep()  call  based  upon  the  CLOCK_REALTIME clock. If the
82       absolute time requested at the invocation of such  a  time  service  is
83       before the new value of the clock, the call shall return immediately as
84       if the clock had reached the requested time normally.
85
86       Setting the value of the CLOCK_REALTIME clock via clock_settime() shall
87       have   no   effect  on  any  thread  that  is  blocked  on  a  relative
88       clock_nanosleep() call. Consequently, the call shall  return  when  the
89       requested  relative  interval  elapses, independently of the new or old
90       value of the clock.
91
92       Appropriate privileges to set a particular  clock  are  implementation-
93       defined.
94
95       If  _POSIX_CPUTIME  is  defined, implementations shall support clock ID
96       values obtained by invoking clock_getcpuclockid(), which represent  the
97       CPU-time  clock  of a given process. Implementations shall also support
98       the special clockid_t value CLOCK_PROCESS_CPUTIME_ID, which  represents
99       the  CPU-time  clock  of  the  calling process when invoking one of the
100       clock_*() or timer_*() functions.  For  these  clock  IDs,  the  values
101       returned  by clock_gettime() and specified by clock_settime() represent
102       the amount of execution time of the process associated with the  clock.
103       Changing  the  value of a CPU-time clock via clock_settime() shall have
104       no effect on the behavior of the sporadic server scheduling policy (see
105       Scheduling Policies).
106
107       If  _POSIX_THREAD_CPUTIME  is  defined,  implementations  shall support
108       clock ID values obtained  by  invoking  pthread_getcpuclockid(),  which
109       represent  the  CPU-time clock of a given thread. Implementations shall
110       also support the special clockid_t value CLOCK_THREAD_CPUTIME_ID, which
111       represents  the  CPU-time clock of the calling thread when invoking one
112       of the clock_*() or timer_*() functions. For these clock IDs, the  val‐
113       ues  returned by clock_gettime() and specified by clock_settime() shall
114       represent the amount of execution time of the  thread  associated  with
115       the  clock.  Changing the value of a CPU-time clock via clock_settime()
116       shall have no effect on the behavior of the sporadic server  scheduling
117       policy (see Scheduling Policies).
118

RETURN VALUE

120       A  return  value  of 0 shall indicate that the call succeeded. A return
121       value of -1 shall indicate that an error occurred, and errno  shall  be
122       set to indicate the error.
123

ERRORS

125       The  clock_getres(),  clock_gettime(),  and  clock_settime()  functions
126       shall fail if:
127
128       EINVAL The clock_id argument does not specify a known clock.
129
130       The clock_gettime() function shall fail if:
131
132       EOVERFLOW
133              The number of seconds will not fit in an object of type time_t.
134
135       The clock_settime() function shall fail if:
136
137       EINVAL The tp argument to clock_settime() is outside the range for  the
138              given clock ID.
139
140       EINVAL The  tp  argument specified a nanosecond value less than zero or
141              greater than or equal to 1000 million.
142
143       EINVAL The value of the clock_id argument is CLOCK_MONOTONIC.
144
145       The clock_settime() function may fail if:
146
147       EPERM  The requesting process does not have appropriate  privileges  to
148              set the specified clock.
149
150       The following sections are informative.
151

EXAMPLES

153       None.
154

APPLICATION USAGE

156       Note  that  the  absolute  value  of the monotonic clock is meaningless
157       (because its origin is arbitrary), and thus there is no need to set it.
158       Furthermore,  realtime applications can rely on the fact that the value
159       of this clock is never set and, therefore, that time intervals measured
160       with this clock will not be affected by calls to clock_settime().
161

RATIONALE

163       None.
164

FUTURE DIRECTIONS

166       None.
167

SEE ALSO

169       Scheduling Policies, clock_getcpuclockid(), clock_nanosleep(), ctime(),
170       mq_receive(), mq_send(), nanosleep(), pthread_mutex_timedlock(),
171       sem_timedwait(), time(), timer_create(), timer_getoverrun()
172
173       The Base Definitions volume of POSIX.1‐2017, <time.h>
174
176       Portions  of  this text are reprinted and reproduced in electronic form
177       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
178       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
179       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
180       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
181       event of any discrepancy between this version and the original IEEE and
182       The  Open Group Standard, the original IEEE and The Open Group Standard
183       is the referee document. The original Standard can be  obtained  online
184       at http://www.opengroup.org/unix/online.html .
185
186       Any  typographical  or  formatting  errors that appear in this page are
187       most likely to have been introduced during the conversion of the source
188       files  to  man page format. To report such errors, see https://www.ker
189       nel.org/doc/man-pages/reporting_bugs.html .
190
191
192
193IEEE/The Open Group                  2017                     CLOCK_GETRES(3P)
Impressum