|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
|
|
|
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
#include <time.h>
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 interval 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 terminated. 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 argument, 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 suspended.
The suspension time caused by this function may be longer than
requested because the argument 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). The
rqtp and rmtp arguments can point to the same object. 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.
ENOTSUP
The clock_id argument specifies a clock for which
clock_nanosleep() is not supported, such as a CPU-time
clock.
The following sections are informative.
None.
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 application 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. Suppose, 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 current
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
necessary 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 numbers. In this
regard, the reasons for including an absolute version of the
clock_nanosleep() function in POSIX.1‐2008 are the same as for the
inclusion of the relative nanosleep().
It is also possible to implement precise periodic processes using
pthread_cond_timedwait(), in which an absolute timeout is
specified that takes effect if the condition variable 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 implementations 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.
None.
clock_getres(3p), nanosleep(3p), pthread_cond_timedwait(3p),
sleep(3p)
The Base Definitions volume of POSIX.1‐2017, time.h(0p)
Portions of this text are reprinted and reproduced in electronic
form from IEEE Std 1003.1-2017, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The
Open Group Base Specifications Issue 7, 2018 Edition, Copyright
(C) 2018 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 original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
Any typographical or formatting errors that appear in this page
are most likely to have been introduced during the conversion of
the source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2017 CLOCK_NANOSLEEP(3P)
Pages that refer to this page: time.h(0p), clock_getres(3p), nanosleep(3p)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|