execve.2: wfix

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

diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2
index 54eee024a274981050e6c5a1540af5df816a5efd..a032620a998eb69e8d58f15a7bf8ff63ae46274d 100644 (file)
--- a/man2/sigprocmask.2
+++ b/man2/sigprocmask.2
@@ -26,23 +26,33 @@
 .\"
 .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2
 .\"
-.TH SIGPROCMASK 2 2015-03-29 "Linux" "Linux Programmer's Manual"
+.TH SIGPROCMASK 2 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sigprocmask, rt_sigprocmask \- examine and change blocked signals
 .SH SYNOPSIS
 .B #include <signal.h>
-.sp
-.BI "int sigprocmask(int " how ", const sigset_t *" set ,
-.BI "sigset_t *" oldset );
-.sp
+.PP
+.nf
+/* Prototype for the glibc wrapper function */
+.BI "int sigprocmask(int " how ", const sigset_t *" set ", sigset_t *" oldset );
+.PP
+/* Prototype for the underlying system call */
+.BI "int rt_sigprocmask(int " how ", const kernel_sigset_t *" set ,
+.BI "                   kernel_sigset_t *" oldset ", size_t " sigsetsize );
+.PP
+/* Prototype for the legacy system call (deprecated) */
+.BI "int sigprocmask(int " how ", const old_kernel_sigset_t *" set ,
+.BI "                old_kernel_sigset_t *" oldset ); "
+.fi
+.PP
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
-.sp
+.PP
 .ad l
 .BR sigprocmask ():
-_POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
+_POSIX_C_SOURCE
 .ad b
 .SH DESCRIPTION
 .BR sigprocmask ()
@@ -52,7 +62,7 @@ blocked for the caller
 (see also
 .BR signal (7)
 for more details).
-
+.PP
 The behavior of the call is dependent on the value of
 .IR how ,
 as follows.
@@ -76,7 +86,7 @@ If
 .I oldset
 is non-NULL, the previous value of the signal mask is stored in
 .IR oldset .
-
+.PP
 If
 .I set
 is NULL, then the signal mask is unchanged (i.e.,
@@ -85,7 +95,12 @@ is ignored),
 but the current value of the signal mask is nevertheless returned in
 .I oldset
 (if it is not NULL).
-
+.PP
+A set of functions for modifying and inspecting variables of type
+.I sigset_t
+("signal sets") is described in
+.BR sigsetops (3).
+.PP
 The use of
 .BR sigprocmask ()
 is unspecified in a multithreaded process; see
@@ -106,24 +121,25 @@ or
 argument points outside the process's allocated address space.
 .TP
 .B EINVAL
-The value specified in
+Either the value specified in
 .I how
-was invalid.
+was invalid or the kernel does not support the size passed in
+.I sigsetsize.
 .SH CONFORMING TO
-POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008.
 .SH NOTES
 It is not possible to block
 .BR SIGKILL " or " SIGSTOP .
 Attempts to do so are silently ignored.
-
+.PP
 Each of the threads in a process has its own signal mask.
-
+.PP
 A child created via
 .BR fork (2)
 inherits a copy of its parent's signal mask;
 the signal mask is preserved across
 .BR execve (2).
-
+.PP
 If
 .BR SIGBUS ,
 .BR SIGFPE ,
@@ -141,8 +157,25 @@ or
 See
 .BR sigsetops (3)
 for details on manipulating signal sets.
+.PP
+Note that it is permissible (although not very useful) to specify both
+.I set
+and
+.I oldset
+as NULL.
 .\"
-.SS C library/kernel ABI differences
+.SS C library/kernel differences
+.PP
+The kernel's definition of
+.IR sigset_t
+differs in size from that used
+by the C library.
+In this manual page, the former is referred to as
+.I kernel_sigset_t
+(it is nevertheless named
+.I sigset_t
+in the kernel sources).
+.PP
 The glibc wrapper function for
 .BR sigprocmask ()
 silently ignores attempts to block the two real-time signals that
@@ -150,29 +183,36 @@ are used internally by the NPTL threading implementation.
 See
 .BR nptl (7)
 for details.
-
+.PP
 The original Linux system call was named
 .BR sigprocmask ().
 However, with the addition of real-time signals in Linux 2.2,
 the fixed-size, 32-bit
 .IR sigset_t
+(referred to as
+.IR old_kernel_sigset_t
+in this manual page)
 type supported by that system call was no longer fit for purpose.
 Consequently, a new system call,
 .BR rt_sigprocmask (),
 was added to support an enlarged
 .IR sigset_t
-type.
+type
+(referred to as
+.IR kernel_sigset_t
+in this manual page).
 The new system call takes a fourth argument,
 .IR "size_t sigsetsize" ,
 which specifies the size in bytes of the signal sets in
 .IR set
 and
 .IR oldset .
-This argument is currently required to have the value
-.IR sizeof(sigset_t)
-(or the error
-.B EINVAL
-results).
+This argument is currently required to have a fixed architecture specific value
+(equal to
+.IR sizeof(kernel_sigset_t) ).
+.\" sizeof(kernel_sigset_t) == _NSIG / 8,
+.\" which equals to 8 on most architectures, but e.g. on MIPS it's 16.
+.PP
 The glibc
 .BR sigprocmask ()
 wrapper function hides these details from us, transparently calling