1 files changed, 131 insertions, 0 deletions
diff --git a/man/man2/sigsuspend.2 b/man/man2/sigsuspend.2
new file mode 100644
index 000000000..01f9c9dcc
--- /dev/null
+++ b/man/man2/sigsuspend.2
@@ -0,0 +1,131 @@
+.\" Copyright (c) 2005 Michael Kerrisk
+.\" based on earlier work by faith@cs.unc.edu and
+.\" Mike Battersby <mib@deakin.edu.au>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2
+.\"
+.TH sigsuspend 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+sigsuspend, rt_sigsuspend \- wait for a signal
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <signal.h>
+.P
+.BI "int sigsuspend(const sigset_t *" mask );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR sigsuspend ():
+.nf
+    _POSIX_C_SOURCE
+.fi
+.SH DESCRIPTION
+.BR sigsuspend ()
+temporarily replaces the signal mask of the calling thread with the
+mask given by
+.I mask
+and then suspends the thread until delivery of a signal whose
+action is to invoke a signal handler or to terminate a process.
+.P
+If the signal terminates the process, then
+.BR sigsuspend ()
+does not return.
+If the signal is caught, then
+.BR sigsuspend ()
+returns after the signal handler returns,
+and the signal mask is restored to the state before the call to
+.BR sigsuspend ().
+.P
+It is not possible to block
+.B SIGKILL
+or
+.BR SIGSTOP ;
+specifying these signals in
+.IR mask ,
+has no effect on the thread's signal mask.
+.SH RETURN VALUE
+.BR sigsuspend ()
+always returns \-1, with
+.I errno
+set to indicate the error (normally,
+.BR EINTR ).
+.SH ERRORS
+.TP
+.B EFAULT
+.I mask
+points to memory which is not a valid part of the process address space.
+.TP
+.B EINTR
+The call was interrupted by a signal;
+.BR signal (7).
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SS C library/kernel differences
+The original Linux system call was named
+.BR sigsuspend ().
+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_sigsuspend (),
+was added to support an enlarged
+.I sigset_t
+type.
+The new system call takes a second argument,
+.IR "size_t sigsetsize" ,
+which specifies the size in bytes of the signal set in
+.IR mask .
+This argument is currently required to have the value
+.I sizeof(sigset_t)
+(or the error
+.B EINVAL
+results).
+The glibc
+.BR sigsuspend ()
+wrapper function hides these details from us, transparently calling
+.BR rt_sigsuspend ()
+when the kernel provides it.
+.\"
+.SH NOTES
+Normally,
+.BR sigsuspend ()
+is used in conjunction with
+.BR sigprocmask (2)
+in order to prevent delivery of a signal during the execution of a
+critical code section.
+The caller first blocks the signals with
+.BR sigprocmask (2).
+When the critical code has completed, the caller then waits for the
+signals by calling
+.BR sigsuspend ()
+with the signal mask that was returned by
+.BR sigprocmask (2)
+(in the
+.I oldset
+argument).
+.P
+See
+.BR sigsetops (3)
+for details on manipulating signal sets.
+.SH SEE ALSO
+.BR kill (2),
+.BR pause (2),
+.BR sigaction (2),
+.BR signal (2),
+.BR sigprocmask (2),
+.BR sigwaitinfo (2),
+.BR sigsetops (3),
+.BR sigwait (3),
+.BR signal (7)