1CLOCK_NANOSLEEP(3P)        POSIX Programmer's Manual       CLOCK_NANOSLEEP(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_nanosleep — high resolution sleep with specifiable clock
14

SYNOPSIS

16       #include <time.h>
17
18       int clock_nanosleep(clockid_t clock_id, int flags,
19           const struct timespec *rqtp, struct timespec *rmtp);
20

DESCRIPTION

22       If the flag TIMER_ABSTIME  is  not  set  in  the  flags  argument,  the
23       clock_nanosleep()  function  shall  cause the current thread to be sus‐
24       pended from execution until either the time interval specified  by  the
25       rqtp  argument  has  elapsed,  or  a signal is delivered to the calling
26       thread and its action is to invoke a signal-catching function,  or  the
27       process  is terminated. The clock used to measure the time shall be the
28       clock specified by clock_id.
29
30       If  the  flag  TIMER_ABSTIME  is  set  in  the  flags   argument,   the
31       clock_nanosleep()  function  shall  cause the current thread to be sus‐
32       pended from execution until either the time value of the  clock  speci‐
33       fied  by clock_id reaches the absolute time specified by the rqtp argu‐
34       ment, or a signal is delivered to the calling thread and its action  is
35       to  invoke  a  signal-catching  function, or the process is terminated.
36       If, at the time of the call, the time value specified by rqtp  is  less
37       than  or  equal  to  the  time  value  of  the  specified  clock,  then
38       clock_nanosleep() shall return  immediately  and  the  calling  process
39       shall not be suspended.
40
41       The  suspension  time  caused  by  this  function  may  be  longer than
42       requested because the argument value is rounded up to an integer multi‐
43       ple  of  the  sleep  resolution,  or because of the scheduling of other
44       activity by the system. But, except for the case of  being  interrupted
45       by  a  signal,  the  suspension time for the relative clock_nanosleep()
46       function (that is, with the TIMER_ABSTIME flag not set)  shall  not  be
47       less  than the time interval specified by rqtp, as measured by the cor‐
48       responding clock. The suspension  for  the  absolute  clock_nanosleep()
49       function  (that is, with the TIMER_ABSTIME flag set) shall be in effect
50       at least until the value of the corresponding clock reaches  the  abso‐
51       lute  time  specified by rqtp, except for the case of being interrupted
52       by a signal.
53
54       The use of the clock_nanosleep() function shall have no effect  on  the
55       action or blockage of any signal.
56
57       The  clock_nanosleep()  function  shall  fail  if the clock_id argument
58       refers to the CPU-time clock of the calling thread. It  is  unspecified
59       whether clock_id values of other CPU-time clocks are allowed.
60

RETURN VALUE

62       If  the  clock_nanosleep()  function returns because the requested time
63       has elapsed, its return value shall be zero.
64
65       If the clock_nanosleep() function returns because it  has  been  inter‐
66       rupted  by a signal, it shall return the corresponding error value. For
67       the relative clock_nanosleep() function, if the rmtp argument  is  non-
68       NULL,  the timespec structure referenced by it shall be updated to con‐
69       tain the amount of time remaining in the interval (the  requested  time
70       minus  the  time  actually  slept).  If  the rmtp argument is NULL, the
71       remaining time is not returned. The absolute clock_nanosleep() function
72       has no effect on the structure referenced by rmtp.
73
74       If  clock_nanosleep()  fails,  it  shall return the corresponding error
75       value.
76

ERRORS

78       The clock_nanosleep() function shall fail if:
79
80       EINTR  The clock_nanosleep() function was interrupted by a signal.
81
82       EINVAL The rqtp argument specified a nanosecond value less than zero or
83              greater than or equal to 1000 million; or the TIMER_ABSTIME flag
84              was specified in flags and the  rqtp  argument  is  outside  the
85              range for the clock specified by clock_id; or the clock_id argu‐
86              ment does not specify a known clock, or specifies  the  CPU-time
87              clock of the calling thread.
88
89       ENOTSUP
90              The    clock_id   argument   specifies   a   clock   for   which
91              clock_nanosleep() is not supported, such as a CPU-time clock.
92
93       The following sections are informative.
94

EXAMPLES

96       None.
97

APPLICATION USAGE

99       Calling clock_nanosleep() with the value TIMER_ABSTIME not set  in  the
100       flags  argument  and with a clock_id of CLOCK_REALTIME is equivalent to
101       calling nanosleep() with the same rqtp and rmtp arguments.
102

RATIONALE

104       The  nanosleep()  function  specifies  that   the   system-wide   clock
105       CLOCK_REALTIME  is  used to measure the elapsed time for this time ser‐
106       vice. However, with the introduction of the monotonic clock CLOCK_MONO‐
107       TONIC  a  new relative sleep function is needed to allow an application
108       to take advantage of the special characteristics of this clock.
109
110       There are many applications in which a process needs  to  be  suspended
111       and  then  activated  multiple times in a periodic way; for example, to
112       poll the status of a non-interrupting device or to  refresh  a  display
113       device.  For  these cases, it is known that precise periodic activation
114       cannot be achieved with a  relative  sleep()  or  nanosleep()  function
115       call.  Suppose,  for  example,  a periodic process that is activated at
116       time T0, executes for a while, and then wants to suspend  itself  until
117       time  T0+T,  the  period  being  T.   If  this process wants to use the
118       nanosleep() function, it must first call  clock_gettime()  to  get  the
119       current  time,  then  calculate the difference between the current time
120       and T0+T and, finally, call nanosleep() using  the  computed  interval.
121       However,  the process could be preempted by a different process between
122       the two function calls, and in this case the interval computed would be
123       wrong; the process would wake up later than desired. This problem would
124       not occur with the absolute clock_nanosleep() function, since only  one
125       function  call  would  be  necessary  to  suspend the process until the
126       desired time. In other cases, however, a relative sleep is needed,  and
127       that is why both functionalities are required.
128
129       Although  it  is  possible  to  implement  periodic processes using the
130       timers interface, this implementation would require the use of signals,
131       and the reservation of some signal numbers. In this regard, the reasons
132       for including an absolute version of the clock_nanosleep() function  in
133       POSIX.1‐2008  are  the  same  as  for  the  inclusion  of  the relative
134       nanosleep().
135
136       It is also possible  to  implement  precise  periodic  processes  using
137       pthread_cond_timedwait(),  in  which  an  absolute timeout is specified
138       that takes effect if the condition variable involved is never signaled.
139       However,  the use of this interface is unnatural, and involves perform‐
140       ing other operations on mutexes and condition variables that  imply  an
141       unnecessary  overhead.   Furthermore,  pthread_cond_timedwait()  is not
142       available in implementations that do not support threads.
143
144       Although the interface of the relative and absolute versions of the new
145       high  resolution  sleep service is the same clock_nanosleep() function,
146       the rmtp argument is only used in the relative sleep. This argument  is
147       needed  in the relative clock_nanosleep() function to reissue the func‐
148       tion call if it is interrupted by a signal, but it is not needed in the
149       absolute clock_nanosleep() function call; if the call is interrupted by
150       a signal, the absolute clock_nanosleep() function can be invoked  again
151       with the same rqtp argument used in the interrupted call.
152

FUTURE DIRECTIONS

154       None.
155

SEE ALSO

157       clock_getres(), nanosleep(), pthread_cond_timedwait(), sleep()
158
159       The Base Definitions volume of POSIX.1‐2008, <time.h>
160
162       Portions  of  this text are reprinted and reproduced in electronic form
163       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
164       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
165       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
166       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
167       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
168       event of any discrepancy between this version and the original IEEE and
169       The Open Group Standard, the original IEEE and The Open Group  Standard
170       is  the  referee document. The original Standard can be obtained online
171       at http://www.unix.org/online.html .
172
173       Any typographical or formatting errors that appear  in  this  page  are
174       most likely to have been introduced during the conversion of the source
175       files to man page format. To report such errors,  see  https://www.ker
176       nel.org/doc/man-pages/reporting_bugs.html .
177
178
179
180IEEE/The Open Group                  2013                  CLOCK_NANOSLEEP(3P)
Impressum