CLOCK_NANOSLEEP(3P) POSIX Programmer's Manual CLOCK_NANOSLEEP(3P)
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of
this interface may differ (consult the corresponding Linux manual page for details of
Linux behavior), or the interface may not be implemented on Linux.
clock_nanosleep - high resolution sleep with specifiable clock (ADVANCED REALTIME)
int clock_nanosleep(clockid_t clock_id, int flags,
const struct timespec *rqtp, struct timespec *rmtp);
If the flag TIMER_ABSTIME is not set in the flags argument, the clock_nanosleep() function
shall cause the current thread to be suspended from execution until either the time inter-
val specified by the rqtp argument has elapsed, or a signal is delivered to the calling
thread and its action is to invoke a signal-catching function, or the process is termi-
nated. The clock used to measure the time shall be the clock specified by clock_id.
If the flag TIMER_ABSTIME is set in the flags argument, the clock_nanosleep() function
shall cause the current thread to be suspended from execution until either the time value
of the clock specified by clock_id reaches the absolute time specified by the rqtp argu-
ment, or a signal is delivered to the calling thread and its action is to invoke a signal-
catching function, or the process is terminated. If, at the time of the call, the time
value specified by rqtp is less than or equal to the time value of the specified clock,
then clock_nanosleep() shall return immediately and the calling process shall not be sus-
The suspension time caused by this function may be longer than requested because the argu-
ment value is rounded up to an integer multiple of the sleep resolution, or because of the
scheduling of other activity by the system. But, except for the case of being interrupted
by a signal, the suspension time for the relative clock_nanosleep() function (that is,
with the TIMER_ABSTIME flag not set) shall not be less than the time interval specified by
rqtp, as measured by the corresponding clock. The suspension for the absolute
clock_nanosleep() function (that is, with the TIMER_ABSTIME flag set) shall be in effect
at least until the value of the corresponding clock reaches the absolute time specified by
rqtp, except for the case of being interrupted by a signal.
The use of the clock_nanosleep() function shall have no effect on the action or blockage
of any signal.
The clock_nanosleep() function shall fail if the clock_id argument refers to the CPU-time
clock of the calling thread. It is unspecified whether clock_id values of other CPU-time
clocks are allowed.
If the clock_nanosleep() function returns because the requested time has elapsed, its
return value shall be zero.
If the clock_nanosleep() function returns because it has been interrupted by a signal, it
shall return the corresponding error value. For the relative clock_nanosleep() function,
if the rmtp argument is non-NULL, the timespec structure referenced by it shall be updated
to contain the amount of time remaining in the interval (the requested time minus the time
actually slept). If the rmtp argument is NULL, the remaining time is not returned. The
absolute clock_nanosleep() function has no effect on the structure referenced by rmtp.
If clock_nanosleep() fails, it shall return the corresponding error value.
The clock_nanosleep() function shall fail if:
EINTR The clock_nanosleep() function was interrupted by a signal.
EINVAL The rqtp argument specified a nanosecond value less than zero or greater than or
equal to 1000 million; or the TIMER_ABSTIME flag was specified in flags and the
rqtp argument is outside the range for the clock specified by clock_id; or the
clock_id argument does not specify a known clock, or specifies the CPU-time clock
of the calling thread.
The clock_id argument specifies a clock for which clock_nanosleep() is not sup-
ported, such as a CPU-time clock.
The following sections are informative.
Calling clock_nanosleep() with the value TIMER_ABSTIME not set in the flags argument and
with a clock_id of CLOCK_REALTIME is equivalent to calling nanosleep() with the same rqtp
and rmtp arguments.
The nanosleep() function specifies that the system-wide clock CLOCK_REALTIME is used to
measure the elapsed time for this time service. However, with the introduction of the
monotonic clock CLOCK_MONOTONIC a new relative sleep function is needed to allow an appli-
cation to take advantage of the special characteristics of this clock.
There are many applications in which a process needs to be suspended and then activated
multiple times in a periodic way; for example, to poll the status of a non-interrupting
device or to refresh a display device. For these cases, it is known that precise periodic
activation cannot be achieved with a relative sleep() or nanosleep() function call. Sup-
pose, for example, a periodic process that is activated at time T0, executes for a while,
and then wants to suspend itself until time T0+ T, the period being T. If this process
wants to use the nanosleep() function, it must first call clock_gettime() to get the cur-
rent time, then calculate the difference between the current time and T0+ T and, finally,
call nanosleep() using the computed interval. However, the process could be preempted by a
different process between the two function calls, and in this case the interval computed
would be wrong; the process would wake up later than desired. This problem would not occur
with the absolute clock_nanosleep() function, since only one function call would be neces-
sary to suspend the process until the desired time. In other cases, however, a relative
sleep is needed, and that is why both functionalities are required.
Although it is possible to implement periodic processes using the timers interface, this
implementation would require the use of signals, and the reservation of some signal num-
bers. In this regard, the reasons for including an absolute version of the
clock_nanosleep() function in IEEE Std 1003.1-2001 are the same as for the inclusion of
the relative nanosleep().
It is also possible to implement precise periodic processes using pthread_cond_timed-
wait(), in which an absolute timeout is specified that takes effect if the condition vari-
able involved is never signaled. However, the use of this interface is unnatural, and
involves performing other operations on mutexes and condition variables that imply an
unnecessary overhead. Furthermore, pthread_cond_timedwait() is not available in implemen-
tations that do not support threads.
Although the interface of the relative and absolute versions of the new high resolution
sleep service is the same clock_nanosleep() function, the rmtp argument is only used in
the relative sleep. This argument is needed in the relative clock_nanosleep() function to
reissue the function call if it is interrupted by a signal, but it is not needed in the
absolute clock_nanosleep() function call; if the call is interrupted by a signal, the
absolute clock_nanosleep() function can be invoked again with the same rqtp argument used
in the interrupted call.
clock_getres(), nanosleep(), pthread_cond_timedwait(), sleep(), the Base Definitions vol-
ume of IEEE Std 1003.1-2001, <time.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 CLOCK_NANOSLEEP(3P)