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       (REALTIME)
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
22

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

153       None.
154

APPLICATION USAGE

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

RATIONALE

166       None.
167

FUTURE DIRECTIONS

169       None.
170

SEE ALSO

172       clock_getcpuclockid(),  clock_nanosleep(),  ctime(), mq_timedreceive(),
173       mq_timedsend(),  nanosleep(),   pthread_mutex_timedlock(),   sem_timed‐
174       wait(),  time(),  timer_create(),  timer_getoverrun(), the Base Defini‐
175       tions volume of IEEE Std 1003.1-2001, <time.h>
176
178       Portions of this text are reprinted and reproduced in  electronic  form
179       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
180       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
181       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
182       Electrical and Electronics Engineers, Inc and The Open  Group.  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.opengroup.org/unix/online.html .
187
188
189
190IEEE/The Open Group                  2003                     CLOCK_GETRES(3P)
Impressum