Start of man-pages-5.03: renaming .Announce and .lsm files

[thirdparty/man-pages.git] / man2 / nanosleep.2

diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
index 05fcce1fac9215566581ea3ed536c2055d8b5279..0de7116431f9eff1a7380249e82488b7b61f55fd 100644 (file)
--- a/man2/nanosleep.2
+++ b/man2/nanosleep.2
@@ -31,19 +31,19 @@
 .\"     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 2015-08-08 "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
@@ -54,7 +54,7 @@ until either at least the time specified in
 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
@@ -71,23 +71,23 @@ The value of
 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
@@ -114,7 +114,7 @@ Problem with copying information from user space.
 .TP
 .B EINTR
 The pause has been interrupted by a signal that was
-delivered to the threadi (see
+delivered to the thread (see
 .BR signal (7)).
 The remaining sleep time has been written
 into
@@ -139,7 +139,7 @@ is not an exact multiple of the granularity underlying clock (see
 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
@@ -149,7 +149,7 @@ will lead to drift in the time when the sleep finally completes.
 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
@@ -185,16 +185,34 @@ interval elapses, independently of the new or old value of the clock.
 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.,
@@ -208,6 +226,7 @@ If the system call is subsequently restarted,
 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),