.\" NOTES: describe case where clock_nanosleep() can be preferable.
.\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP
.\" Replace crufty discussion of HZ with a pointer to time(7).
-.TH NANOSLEEP 2 2013-07-30 "Linux" "Linux Programmer's Manual"
+.TH NANOSLEEP 2 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
nanosleep \- high-resolution sleep
.SH SYNOPSIS
.B #include <time.h>
-.sp
+.PP
.BI "int nanosleep(const struct timespec *" req ", struct timespec *" rem );
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.BR nanosleep ():
_POSIX_C_SOURCE\ >=\ 199309L
.SH DESCRIPTION
has elapsed, or the delivery of a signal
that triggers the invocation of a handler in the calling thread or
that terminates the process.
-
+.PP
If the call is interrupted by a signal handler,
.BR nanosleep ()
returns \-1, sets
can then be used to call
.BR nanosleep ()
again and complete the specified pause (but see NOTES).
-
+.PP
The structure
.I timespec
is used to specify intervals of time with nanosecond precision.
It is defined as follows:
-.sp
+.PP
.in +4n
-.nf
+.EX
struct timespec {
time_t tv_sec; /* seconds */
long tv_nsec; /* nanoseconds */
};
-.fi
+.EE
.in
.PP
The value of the nanoseconds field must be in the range 0 to 999999999.
-
+.PP
Compared to
.BR sleep (3)
and
.TP
.B EINTR
The pause has been interrupted by a signal that was
-delivered to the thread.
+delivered to the thread (see
+.BR signal (7)).
The remaining sleep time has been written
into
.I *rem
then the interval will be rounded up to the next multiple.
Furthermore, after the sleep completes, there may still be a delay before
the CPU becomes free to once again execute the calling thread.
-
+.PP
The fact that
.BR nanosleep ()
sleeps for a relative interval can be problematic if the call
This problem can be avoided by using
.BR clock_nanosleep (2)
with an absolute time value.
-
+.PP
POSIX.1 specifies that
.BR nanosleep ()
should measure time against the
In order to support applications requiring much more precise pauses
(e.g., in order to control some time-critical hardware),
.BR nanosleep ()
-would handle pauses of up to 2\ ms by busy waiting with microsecond
+would handle pauses of up to 2 milliseconds by busy waiting with microsecond
precision when called from a thread scheduled under a real-time policy
like
.B SCHED_FIFO
or
.BR SCHED_RR .
This special extension was removed in kernel 2.5.39,
-hence is still present in
-current 2.4 kernels, but not in 2.6 kernels.
+and is thus not available in Linux 2.6.0 and later kernels.
.SH BUGS
+If a program that catches signals and uses
+.BR nanosleep ()
+receives signals at a very high rate,
+then scheduling delays and rounding errors in the kernel's
+calculation of the sleep interval and the returned
+.IR remain
+value mean that the
+.IR remain
+value may steadily
+.IR increase
+on successive restarts of the
+.BR nanosleep ()
+call.
+To avoid such problems, use
+.BR clock_nanosleep (2)
+with the
+.BR TIMER_ABSTIME
+flag to sleep to an absolute deadline.
+.PP
In Linux 2.4, if
.BR nanosleep ()
is stopped by a signal (e.g.,
then the time that the thread spent in the stopped state is
.I not
counted against the sleep interval.
+This problem is fixed in Linux 2.6.0 and later kernels.
.SH SEE ALSO
.BR clock_nanosleep (2),
.BR restart_syscall (2),