'\" et
.TH CLOCK_NANOSLEEP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
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.
.\"
.SH NAME
clock_nanosleep
\(em high resolution sleep with specifiable clock
.SH SYNOPSIS
.LP
.nf
#include <time.h>
.P
int clock_nanosleep(clockid_t \fIclock_id\fP, int \fIflags\fP,
    const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP);
.fi
.SH DESCRIPTION
If the flag TIMER_ABSTIME
is not set in the
.IR flags
argument, the
\fIclock_nanosleep\fR()
function shall cause the current thread to be suspended from execution
until either the time interval specified by the
.IR 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
.IR clock_id .
.P
If the flag TIMER_ABSTIME is set in the
.IR flags
argument, the
\fIclock_nanosleep\fR()
function shall cause the current thread to be suspended from execution
until either the time value of the clock specified by
.IR clock_id
reaches the absolute time specified by the
.IR 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
.IR rqtp
is less than or equal to the time value of the specified clock, then
\fIclock_nanosleep\fR()
shall return immediately and the calling process shall not be
suspended.
.P
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
\fIclock_nanosleep\fR()
function (that is, with the TIMER_ABSTIME flag not set) shall not be
less than the time interval specified by
.IR rqtp ,
as measured by the corresponding clock. The suspension for the absolute
\fIclock_nanosleep\fR()
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
.IR rqtp ,
except for the case of being interrupted by a signal.
.P
The use of the
\fIclock_nanosleep\fR()
function shall have no effect on the action or blockage of any signal.
.P
The
\fIclock_nanosleep\fR()
function shall fail if the
.IR clock_id
argument refers to the CPU-time clock of the calling thread. It is
unspecified whether
.IR clock_id
values of other CPU-time clocks are allowed.
.SH "RETURN VALUE"
If the
\fIclock_nanosleep\fR()
function returns because the requested time has elapsed, its return
value shall be zero.
.P
If the
\fIclock_nanosleep\fR()
function returns because it has been interrupted by a signal, it shall
return the corresponding error value. For the relative
\fIclock_nanosleep\fR()
function, if the
.IR rmtp
argument is non-NULL, the
.BR 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
.IR rqtp
and
.IR rmtp
arguments can point to the same object. If the
.IR rmtp
argument is NULL, the remaining time is not returned. The absolute
\fIclock_nanosleep\fR()
function has no effect on the structure referenced by
.IR rmtp .
.P
If
\fIclock_nanosleep\fR()
fails, it shall return the corresponding error value.
.SH ERRORS
The
\fIclock_nanosleep\fR()
function shall fail if:
.TP
.BR EINTR
The
\fIclock_nanosleep\fR()
function was interrupted by a signal.
.TP
.BR EINVAL
The
.IR rqtp
argument specified a nanosecond value less than zero or greater than or
equal to 1\|000 million; or the TIMER_ABSTIME flag was specified in
flags and the
.IR rqtp
argument is outside the range for the clock specified by
.IR clock_id ;
or the
.IR clock_id
argument does not specify a known clock, or specifies the CPU-time
clock of the calling thread.
.TP
.BR ENOTSUP
The
.IR clock_id
argument specifies a clock for which
\fIclock_nanosleep\fR()
is not supported, such as a CPU-time clock.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
Calling
\fIclock_nanosleep\fR()
with the value TIMER_ABSTIME not set in the
.IR flags
argument and with a
.IR clock_id
of CLOCK_REALTIME is equivalent to calling
\fInanosleep\fR()
with the same
.IR rqtp
and
.IR rmtp
arguments.
.SH RATIONALE
The
\fInanosleep\fR()
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.
.P
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
\fIsleep\fR()
or
\fInanosleep\fR()
function call. Suppose, for example, a periodic process that is
activated at time
.IR T 0,
executes for a while, and then wants to suspend itself until time
.IR T 0+\c
.IR T ,
the period being
.IR T .
If this process wants to use the
\fInanosleep\fR()
function, it must first call
\fIclock_gettime\fR()
to get the current time, then calculate the difference between the
current time and
.IR T 0+\c
.IR T
and, finally, call
\fInanosleep\fR()
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
\fIclock_nanosleep\fR()
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.
.P
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
\fIclock_nanosleep\fR()
function in POSIX.1\(hy2008 are the same as for the inclusion of the relative
\fInanosleep\fR().
.P
It is also possible to implement precise periodic processes using
\fIpthread_cond_timedwait\fR(),
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,
\fIpthread_cond_timedwait\fR()
is not available in implementations that do not support threads.
.P
Although the interface of the relative and absolute versions of the new
high resolution sleep service is the same
\fIclock_nanosleep\fR()
function, the
.IR rmtp
argument is only used in the relative sleep. This argument is needed in
the relative
\fIclock_nanosleep\fR()
function to reissue the function call if it is interrupted by a signal,
but it is not needed in the absolute
\fIclock_nanosleep\fR()
function call; if the call is interrupted by a signal, the absolute
\fIclock_nanosleep\fR()
function can be invoked again with the same
.IR rqtp
argument used in the interrupted call.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIclock_getres\fR\^(\|)",
.IR "\fInanosleep\fR\^(\|)",
.IR "\fIpthread_cond_timedwait\fR\^(\|)",
.IR "\fIsleep\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<time.h>\fP"
.\"
.SH COPYRIGHT
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 .
.PP
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 .