1CLOCK_NANOSLEEP(3P) POSIX Programmer's Manual CLOCK_NANOSLEEP(3P)
2
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
12 clock_nanosleep — high resolution sleep with specifiable clock
13
15 #include <time.h>
16 int clock_nanosleep(clockid_t clock_id, int flags,
18 const struct timespec *rqtp, struct timespec *rmtp);
19
21 If the flag TIMER_ABSTIME is not set in the flags argument, the
22 clock_nanosleep() function shall cause the current thread to be sus‐
23 pended from execution until either the time interval specified by the
24 rqtp argument has elapsed, or a signal is delivered to the calling
25 thread and its action is to invoke a signal-catching function, or the
26 process is terminated. The clock used to measure the time shall be the
27 clock specified by clock_id.
28 If the flag TIMER_ABSTIME is set in the flags argument, the
30 clock_nanosleep() function shall cause the current thread to be sus‐
31 pended from execution until either the time value of the clock speci‐
32 fied by clock_id reaches the absolute time specified by the rqtp argu‐
33 ment, or a signal is delivered to the calling thread and its action is
34 to invoke a signal-catching function, or the process is terminated.
35 If, at the time of the call, the time value specified by rqtp is less
36 than or equal to the time value of the specified clock, then
37 clock_nanosleep() shall return immediately and the calling process
38 shall not be suspended.
39 The suspension time caused by this function may be longer than
41 requested because the argument value is rounded up to an integer multi‐
42 ple of the sleep resolution, or because of the scheduling of other
43 activity by the system. But, except for the case of being interrupted
44 by a signal, the suspension time for the relative clock_nanosleep()
45 function (that is, with the TIMER_ABSTIME flag not set) shall not be
46 less than the time interval specified by rqtp, as measured by the cor‐
47 responding clock. The suspension for the absolute clock_nanosleep()
48 function (that is, with the TIMER_ABSTIME flag set) shall be in effect
49 at least until the value of the corresponding clock reaches the abso‐
50 lute time specified by rqtp, except for the case of being interrupted
51 by a signal.
52 The use of the clock_nanosleep() function shall have no effect on the
54 action or blockage of any signal.
55 The clock_nanosleep() function shall fail if the clock_id argument
57 refers to the CPU-time clock of the calling thread. It is unspecified
58 whether clock_id values of other CPU-time clocks are allowed.
59
61 If the clock_nanosleep() function returns because the requested time
62 has elapsed, its return value shall be zero.
63 If the clock_nanosleep() function returns because it has been inter‐
65 rupted by a signal, it shall return the corresponding error value. For
66 the relative clock_nanosleep() function, if the rmtp argument is non-
67 NULL, the timespec structure referenced by it shall be updated to con‐
68 tain the amount of time remaining in the interval (the requested time
69 minus the time actually slept). The rqtp and rmtp arguments can point
70 to the same object. If the rmtp argument is NULL, the remaining time is
71 not returned. The absolute clock_nanosleep() function has no effect on
72 the structure referenced by rmtp.
73 If clock_nanosleep() fails, it shall return the corresponding error
75 value.
76
78 The clock_nanosleep() function shall fail if:
79 EINTR The clock_nanosleep() function was interrupted by a signal.
81 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 ENOTSUP
90 The clock_id argument specifies a clock for which
91 clock_nanosleep() is not supported, such as a CPU-time clock.
92 The following sections are informative.
94
96 None.
97
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
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 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 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 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 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
154 None.
155
157 clock_getres(), nanosleep(), pthread_cond_timedwait(), sleep()
158 The Base Definitions volume of POSIX.1‐2017, <time.h>
160
162 Portions of this text are reprinted and reproduced in electronic form
163 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
164 table Operating System Interface (POSIX), The Open Group Base Specifi‐
165 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
166 Electrical and Electronics Engineers, Inc and The Open Group. In the
167 event of any discrepancy between this version and the original IEEE and
168 The Open Group Standard, the original IEEE and The Open Group Standard
169 is the referee document. The original Standard can be obtained online
170 at http://www.opengroup.org/unix/online.html .
171 Any typographical or formatting errors that appear in this page are
173 most likely to have been introduced during the conversion of the source
174 files to man page format. To report such errors, see https://www.ker‐
175 nel.org/doc/man-pages/reporting_bugs.html .
176IEEE/The Open Group 2017 CLOCK_NANOSLEEP(3P)