Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 220 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man2/nanosleep.2 b/upstream/debian-unstable/man2/nanosleep.2
new file mode 100644
index 00000000..4693dc80
--- /dev/null
+++ b/upstream/debian-unstable/man2/nanosleep.2
@@ -0,0 +1,220 @@
+.\" Copyright (C) Markus Kuhn, 1996
+.\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" 1996-04-10  Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
+.\"             First version written
+.\" Modified, 2004-10-24, aeb
+.\" 2008-06-24, mtk
+.\"     Minor rewrites of some parts.
+.\"     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 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+nanosleep \- high-resolution sleep
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <time.h>
+.PP
+.BI "int nanosleep(const struct timespec *" req ,
+.BI "              struct timespec *_Nullable " rem );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR nanosleep ():
+.nf
+    _POSIX_C_SOURCE >= 199309L
+.fi
+.SH DESCRIPTION
+.BR nanosleep ()
+suspends the execution of the calling thread
+until either at least the time specified in
+.I *req
+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
+.I errno
+to
+.BR EINTR ,
+and writes the remaining time into the structure pointed to by
+.I rem
+unless
+.I rem
+is NULL.
+The value of
+.I *rem
+can then be used to call
+.BR nanosleep ()
+again and complete the specified pause (but see NOTES).
+.PP
+The
+.BR timespec (3)
+structure
+is used to specify intervals of time with nanosecond precision.
+.PP
+The value of the nanoseconds field must be in the range [0, 999999999].
+.PP
+Compared to
+.BR sleep (3)
+and
+.BR usleep (3),
+.BR nanosleep ()
+has the following advantages:
+it provides a higher resolution for specifying the sleep interval;
+POSIX.1 explicitly specifies that it
+does not interact with signals;
+and it makes the task of resuming a sleep that has been
+interrupted by a signal handler easier.
+.SH RETURN VALUE
+On successfully sleeping for the requested interval,
+.BR nanosleep ()
+returns 0.
+If the call is interrupted by a signal handler or encounters an error,
+then it returns \-1, with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+Problem with copying information from user space.
+.TP
+.B EINTR
+The pause has been interrupted by a signal that was
+delivered to the thread (see
+.BR signal (7)).
+The remaining sleep time has been written
+into
+.I *rem
+so that the thread can easily call
+.BR nanosleep ()
+again and continue with the pause.
+.TP
+.B EINVAL
+The value in the
+.I tv_nsec
+field was not in the range [0, 999999999] or
+.I tv_sec
+was negative.
+.SH VERSIONS
+POSIX.1 specifies that
+.BR nanosleep ()
+should measure time against the
+.B CLOCK_REALTIME
+clock.
+However, Linux measures the time using the
+.B CLOCK_MONOTONIC
+clock.
+.\" See also http://thread.gmane.org/gmane.linux.kernel/696854/
+.\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME?
+.\" Date: 2008-06-22 07:35:41 GMT
+This probably does not matter, since the POSIX.1 specification for
+.BR clock_settime (2)
+says that discontinuous changes in
+.B CLOCK_REALTIME
+should not affect
+.BR nanosleep ():
+.RS
+.PP
+Setting the value of the
+.B CLOCK_REALTIME
+clock via
+.BR clock_settime (2)
+shall
+have no effect on threads that are blocked waiting for a relative time
+service based upon this clock, including the
+.BR nanosleep ()
+function; ...
+Consequently, these time services shall expire when the requested relative
+interval elapses, independently of the new or old value of the clock.
+.RE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.PP
+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 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 Linux 2.5.39,
+and is thus not available in Linux 2.6.0 and later kernels.
+.SH NOTES
+If the interval specified in
+.I req
+is not an exact multiple of the granularity underlying clock (see
+.BR time (7)),
+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
+is repeatedly restarted after being interrupted by signals,
+since the time between the interruptions and restarts of the call
+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.
+.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
+.I remain
+value mean that the
+.I remain
+value may steadily
+.I increase
+on successive restarts of the
+.BR nanosleep ()
+call.
+To avoid such problems, use
+.BR clock_nanosleep (2)
+with the
+.B TIMER_ABSTIME
+flag to sleep to an absolute deadline.
+.PP
+In Linux 2.4, if
+.BR nanosleep ()
+is stopped by a signal (e.g.,
+.BR SIGTSTP ),
+then the call fails with the error
+.B EINTR
+after the thread is resumed by a
+.B SIGCONT
+signal.
+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),
+.BR sched_setscheduler (2),
+.BR timer_create (2),
+.BR sleep (3),
+.BR timespec (3),
+.BR usleep (3),
+.BR time (7)