Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 237 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3p/sleep.3p b/upstream/mageia-cauldron/man3p/sleep.3p
new file mode 100644
index 00000000..26b5b3ed
--- /dev/null
+++ b/upstream/mageia-cauldron/man3p/sleep.3p
@@ -0,0 +1,237 @@
+'\" et
+.TH SLEEP "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
+sleep
+\(em suspend execution for an interval of time
+.SH SYNOPSIS
+.LP
+.nf
+#include <unistd.h>
+.P
+unsigned sleep(unsigned \fIseconds\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIsleep\fR()
+function shall cause the calling thread to be suspended from execution
+until either the number of realtime seconds specified by the argument
+.IR seconds
+has elapsed or a signal is delivered to the calling thread and its
+action is to invoke a signal-catching function or to terminate the
+process. The suspension time may be longer than requested due to the
+scheduling of other activity by the system.
+.P
+In single-threaded programs,
+\fIsleep\fR()
+may make use of SIGALRM. In multi-threaded programs,
+\fIsleep\fR()
+shall not make use of SIGALRM and the remainder of this DESCRIPTION
+does not apply.
+.P
+If a SIGALRM signal is generated for the calling process during
+execution of
+\fIsleep\fR()
+and if the SIGALRM signal is being ignored or blocked from delivery, it
+is unspecified whether
+\fIsleep\fR()
+returns when the SIGALRM signal is scheduled. If the signal is being
+blocked, it is also unspecified whether it remains pending after
+\fIsleep\fR()
+returns or it is discarded.
+.P
+If a SIGALRM signal is generated for the calling process during
+execution of
+\fIsleep\fR(),
+except as a result of a prior call to
+\fIalarm\fR(),
+and if the SIGALRM signal is not being ignored or blocked from
+delivery, it is unspecified whether that signal has any effect other
+than causing
+\fIsleep\fR()
+to return.
+.P
+If a signal-catching function interrupts
+\fIsleep\fR()
+and examines or changes either the time a SIGALRM is scheduled to be
+generated, the action associated with the SIGALRM signal, or whether
+the SIGALRM signal is blocked from delivery, the results are
+unspecified.
+.P
+If a signal-catching function interrupts
+\fIsleep\fR()
+and calls
+\fIsiglongjmp\fR()
+or
+\fIlongjmp\fR()
+to restore an environment saved prior to the
+\fIsleep\fR()
+call, the action associated with the SIGALRM signal and the time at
+which a SIGALRM signal is scheduled to be generated are unspecified.
+It is also unspecified whether the SIGALRM signal is blocked, unless
+the signal mask of the process is restored as part of the environment.
+.P
+Interactions between
+\fIsleep\fR()
+and
+\fIsetitimer\fR()
+are unspecified.
+.SH "RETURN VALUE"
+If
+\fIsleep\fR()
+returns because the requested time has elapsed, the value returned
+shall be 0. If
+\fIsleep\fR()
+returns due to delivery of a signal, the return value shall be
+the ``unslept'' amount (the requested time minus the time actually
+slept) in seconds.
+.SH ERRORS
+No errors are defined.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+None.
+.SH RATIONALE
+There are two general approaches to the implementation of the
+\fIsleep\fR()
+function. One is to use the
+\fIalarm\fR()
+function to schedule a SIGALRM
+signal and then suspend the calling thread waiting for that signal. The
+other is to implement an independent facility. This volume of POSIX.1\(hy2017 permits either
+approach in single-threaded programs, but the simple alarm/suspend
+implementation is not appropriate for multi-threaded programs.
+.P
+In order to comply with the requirement that no primitive shall change
+a process attribute unless explicitly described by this volume of POSIX.1\(hy2017, an
+implementation using SIGALRM must carefully take into account any
+SIGALRM signal scheduled by previous
+\fIalarm\fR()
+calls, the action previously established for SIGALRM, and whether
+SIGALRM was blocked. If a SIGALRM has been scheduled before the
+\fIsleep\fR()
+would ordinarily complete, the
+\fIsleep\fR()
+must be shortened to that time and a SIGALRM generated (possibly
+simulated by direct invocation of the signal-catching function) before
+\fIsleep\fR()
+returns. If a SIGALRM has been scheduled after the
+\fIsleep\fR()
+would ordinarily complete, it must be rescheduled for the same time
+before
+\fIsleep\fR()
+returns. The action and blocking for SIGALRM must be saved and
+restored.
+.P
+Historical implementations often implement the SIGALRM-based version
+using
+\fIalarm\fR()
+and
+\fIpause\fR().
+One such implementation is prone to infinite hangups, as described in
+.IR "\fIpause\fR\^(\|)".
+Another such implementation uses the C-language
+\fIsetjmp\fR()
+and
+\fIlongjmp\fR()
+functions to avoid that window. That implementation introduces a
+different problem: when the SIGALRM signal interrupts a signal-catching
+function installed by the user to catch a different signal, the
+\fIlongjmp\fR()
+aborts that signal-catching function. An implementation based on
+\fIsigprocmask\fR(),
+\fIalarm\fR(),
+and
+\fIsigsuspend\fR()
+can avoid these problems.
+.P
+Despite all reasonable care, there are several very subtle, but
+detectable and unavoidable, differences between the two types of
+implementations. These are the cases mentioned in this volume of POSIX.1\(hy2017 where
+some other activity relating to SIGALRM takes place, and the results
+are stated to be unspecified. All of these cases are sufficiently
+unusual as not to be of concern to most applications.
+.P
+See also the discussion of the term
+.IR realtime
+in
+.IR "\fIalarm\fR\^(\|)".
+.P
+Since
+\fIsleep\fR()
+can be implemented using
+\fIalarm\fR(),
+the discussion about alarms occurring early under
+\fIalarm\fR()
+applies to
+\fIsleep\fR()
+as well.
+.P
+Application developers should note that the type of the argument
+.IR seconds
+and the return value of
+\fIsleep\fR()
+is
+.BR unsigned .
+That means that a Strictly Conforming POSIX System Interfaces
+Application
+cannot pass a value greater than the minimum guaranteed value for
+{UINT_MAX},
+which the ISO\ C standard sets as 65\|535, and any application passing a larger
+value is restricting its portability. A different type was considered,
+but historical implementations, including those with a 16-bit
+.BR int
+type, consistently use either
+.BR unsigned
+or
+.BR int .
+.P
+Scheduling delays may cause the process to return from the
+\fIsleep\fR()
+function significantly after the requested time. In such cases, the
+return value should be set to zero, since the formula (requested time
+minus the time actually spent) yields a negative number and
+\fIsleep\fR()
+returns an
+.BR unsigned .
+.SH "FUTURE DIRECTIONS"
+A future version of this standard may require that
+\fIsleep\fR()
+does not make use of SIGALRM in all programs, not just multi-threaded
+programs.
+.SH "SEE ALSO"
+.IR "\fIalarm\fR\^(\|)",
+.IR "\fIgetitimer\fR\^(\|)",
+.IR "\fInanosleep\fR\^(\|)",
+.IR "\fIpause\fR\^(\|)",
+.IR "\fIsigaction\fR\^(\|)",
+.IR "\fIsigsetjmp\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<unistd.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 .