1 files changed, 229 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/sigwaitinfo.2 b/upstream/debian-bookworm/man2/sigwaitinfo.2
new file mode 100644
index 00000000..9324eda3
--- /dev/null
+++ b/upstream/debian-bookworm/man2/sigwaitinfo.2
@@ -0,0 +1,229 @@
+.\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH sigwaitinfo 2 2022-12-03 "Linux man-pages 6.03"
+.SH NAME
+sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait
+for queued signals
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <signal.h>
+.PP
+.BI "int sigwaitinfo(const sigset_t *restrict " set ,
+.BI "                siginfo_t *_Nullable restrict " info );
+.BI "int sigtimedwait(const sigset_t *restrict " set ,
+.BI "                siginfo_t *_Nullable restrict " info ,
+.BI "                const struct timespec *restrict " timeout );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR sigwaitinfo (),
+.BR sigtimedwait ():
+.nf
+    _POSIX_C_SOURCE >= 199309L
+.fi
+.SH DESCRIPTION
+.BR sigwaitinfo ()
+suspends execution of the calling thread until one of the signals in
+.I set
+is pending
+(If one of the signals in
+.I set
+is already pending for the calling thread,
+.BR sigwaitinfo ()
+will return immediately.)
+.PP
+.BR sigwaitinfo ()
+removes the signal from the set of pending
+signals and returns the signal number as its function result.
+If the
+.I info
+argument is not NULL,
+then the buffer that it points to is used to return a structure of type
+.I siginfo_t
+(see
+.BR sigaction (2))
+containing information about the signal.
+.PP
+If multiple signals in
+.I set
+are pending for the caller, the signal that is retrieved by
+.BR sigwaitinfo ()
+is determined according to the usual ordering rules; see
+.BR signal (7)
+for further details.
+.PP
+.BR sigtimedwait ()
+operates in exactly the same way as
+.BR sigwaitinfo ()
+except that it has an additional argument,
+.IR timeout ,
+which specifies the interval for which
+the thread is suspended waiting for a signal.
+(This interval will be rounded up to the system clock granularity,
+and kernel scheduling delays mean that the interval
+may overrun by a small amount.)
+This argument is a
+.BR timespec (3)
+structure.
+.PP
+If both fields of this structure are specified as 0, a poll is performed:
+.BR sigtimedwait ()
+returns immediately, either with information about a signal that
+was pending for the caller, or with an error
+if none of the signals in
+.I set
+was pending.
+.SH RETURN VALUE
+On success, both
+.BR sigwaitinfo ()
+and
+.BR sigtimedwait ()
+return a signal number (i.e., a value greater than zero).
+On failure both calls return \-1, with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+No signal in
+.I set
+became pending within the
+.I timeout
+period specified to
+.BR sigtimedwait ().
+.TP
+.B EINTR
+The wait was interrupted by a signal handler; see
+.BR signal (7).
+(This handler was for a signal other than one of those in
+.IR set .)
+.TP
+.B EINVAL
+.I timeout
+was invalid.
+.SH STANDARDS
+POSIX.1-2001, POSIX.1-2008.
+.SH NOTES
+In normal usage, the calling program blocks the signals in
+.I set
+via a prior call to
+.BR sigprocmask (2)
+(so that the default disposition for these signals does not occur if they
+become pending between successive calls to
+.BR sigwaitinfo ()
+or
+.BR sigtimedwait ())
+and does not establish handlers for these signals.
+In a multithreaded program,
+the signal should be blocked in all threads, in order to prevent
+the signal being treated according to its default disposition in
+a thread other than the one calling
+.BR sigwaitinfo ()
+or
+.BR sigtimedwait ()).
+.PP
+The set of signals that is pending for a given thread is the
+union of the set of signals that is pending specifically for that thread
+and the set of signals that is pending for the process as a whole (see
+.BR signal (7)).
+.PP
+Attempts to wait for
+.B SIGKILL
+and
+.B SIGSTOP
+are silently ignored.
+.PP
+If multiple threads of a process are blocked
+waiting for the same signal(s) in
+.BR sigwaitinfo ()
+or
+.BR sigtimedwait (),
+then exactly one of the threads will actually receive the
+signal if it becomes pending for the process as a whole;
+which of the threads receives the signal is indeterminate.
+.PP
+.BR sigwaitinfo ()
+or
+.BR sigtimedwait (),
+can't be used to receive signals that
+are synchronously generated, such as the
+.B SIGSEGV
+signal that results from accessing an invalid memory address
+or the
+.B SIGFPE
+signal that results from an arithmetic error.
+Such signals can be caught only via signal handler.
+.PP
+POSIX leaves the meaning of a NULL value for the
+.I timeout
+argument of
+.BR sigtimedwait ()
+unspecified, permitting the possibility that this has the same meaning
+as a call to
+.BR sigwaitinfo (),
+and indeed this is what is done on Linux.
+.\"
+.SS C library/kernel differences
+On Linux,
+.BR sigwaitinfo ()
+is a library function implemented on top of
+.BR sigtimedwait ().
+.PP
+The glibc wrapper functions for
+.BR sigwaitinfo ()
+and
+.BR sigtimedwait ()
+silently ignore attempts to wait for the two real-time signals that
+are used internally by the NPTL threading implementation.
+See
+.BR nptl (7)
+for details.
+.PP
+The original Linux system call was named
+.BR sigtimedwait ().
+However, with the addition of real-time signals in Linux 2.2,
+the fixed-size, 32-bit
+.I sigset_t
+type supported by that system call was no longer fit for purpose.
+Consequently, a new system call,
+.BR rt_sigtimedwait (),
+was added to support an enlarged
+.I sigset_t
+type.
+The new system call takes a fourth argument,
+.IR "size_t sigsetsize" ,
+which specifies the size in bytes of the signal set in
+.IR set .
+This argument is currently required to have the value
+.I sizeof(sigset_t)
+(or the error
+.B EINVAL
+results).
+The glibc
+.BR sigtimedwait ()
+wrapper function hides these details from us, transparently calling
+.BR rt_sigtimedwait ()
+when the kernel provides it.
+.\"
+.SH SEE ALSO
+.BR kill (2),
+.BR sigaction (2),
+.BR signal (2),
+.BR signalfd (2),
+.BR sigpending (2),
+.BR sigprocmask (2),
+.BR sigqueue (3),
+.BR sigsetops (3),
+.BR sigwait (3),
+.BR timespec (3),
+.BR signal (7),
+.BR time (7)