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
11

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

154       None.
155

APPLICATION USAGE

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

RATIONALE

164       None.
165

FUTURE DIRECTIONS

167       None.
168

SEE ALSO

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