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

NAME

6       clock_getres,  clock_gettime, clock_settime - clock and timer functions
7       (REALTIME)
8

SYNOPSIS

10       #include <time.h>
11
12       int clock_getres(clockid_t clock_id, struct timespec *res);
13       int clock_gettime(clockid_t clock_id, struct timespec *tp);
14       int clock_settime(clockid_t clock_id, const struct timespec *tp);
15
16

DESCRIPTION

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

RETURN VALUE

116       A  return  value  of 0 shall indicate that the call succeeded. A return
117       value of -1 shall indicate that an error occurred, and errno  shall  be
118       set to indicate the error.
119

ERRORS

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

EXAMPLES

147       None.
148

APPLICATION USAGE

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

RATIONALE

160       None.
161

FUTURE DIRECTIONS

163       None.
164

SEE ALSO

166       clock_getcpuclockid() , clock_nanosleep() , ctime() , mq_timedreceive()
167       , mq_timedsend() , nanosleep() , pthread_mutex_timedlock() , sem_timed‐
168       wait() , time() , timer_create() , timer_getoverrun() , the Base  Defi‐
169       nitions volume of IEEE Std 1003.1-2001, <time.h>
170
172       Portions  of  this text are reprinted and reproduced in electronic form
173       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
174       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
175       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
176       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
177       event of any discrepancy between this version and the original IEEE and
178       The  Open Group Standard, the original IEEE and The Open Group Standard
179       is the referee document. The original Standard can be  obtained  online
180       at http://www.opengroup.org/unix/online.html .
181
182
183
184IEEE/The Open Group                  2003                      CLOCK_GETRES(P)
Impressum