aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKeno Fischer <keno@juliacomputing.com>2016-08-24 23:24:56 -0400
committerMichael Kerrisk <mtk.manpages@gmail.com>2016-08-28 17:42:52 +1200
commit86d5ed87d30af381c806a1729574d009b40c5e7b (patch)
tree9688863a446e46a27e8e6fb000a8fda9aff8d9b0
parent48bafe7c025547e58d72a913395c1c66e1434cd7 (diff)
downloadman-pages-86d5ed87d30af381c806a1729574d009b40c5e7b.tar.gz
sigprocmask.2: Expand/clarify libc/kernel sigset_t difference
Expand and clarify libc/kernel sigset_t differences. Also move up the signature for rt_sigprocmask, similar to the way this is done in clone.2. Due to the history of sigprocmask, there are various notions of what sigset_t refers to. This attempts to clarify the man page, by giving the major instances different names: - sigset_t is the glibc sigset_t (1024 bits) - kernel_sigset_t is the kernel's sigset_t (64 bits) - old_kernel_sigset_t is the pre-rt kernel's sigset_t (32 bits) and explaining their difference in the NOTES. Even though the sources do not refer to the various sigset_t's by these names, I think it is important to be explicit, esp since sizeof(sigset_t) would give an incorrect value for `sigsetsize` if written in a source file that includes the libc headers. Lastly, move the note on an incorrect `sigsetsize` causing EINVAL up to the ERRORS section, so everything is in one place.
-rw-r--r--man2/sigprocmask.249
1 files changed, 39 insertions, 10 deletions
diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2
index 51f79330d3..907061f0d2 100644
--- a/man2/sigprocmask.2
+++ b/man2/sigprocmask.2
@@ -32,8 +32,19 @@ 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 );
+.nf
+/* Prototype for the glibc wrapper function */
+.BI "int sigprocmask(int " how ", const sigset_t *" set ", sigset_t *" oldset );
+
+/* 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 );
+
+/* 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
+
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
@@ -111,9 +122,10 @@ 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-2008.
.SH NOTES
@@ -148,6 +160,16 @@ See
for details on manipulating signal sets.
.\"
.SS C library/kernel differences
+
+The kernel's definition of
+.IR sigset_t
+differs in size from that used
+by the C library. In this man page the former is referred to as
+.I kernel_sigset_t
+(it is still named
+.I sigset_t
+in the kernel sources).
+
The glibc wrapper function for
.BR sigprocmask ()
silently ignores attempts to block the two real-time signals that
@@ -161,23 +183,30 @@ The original Linux system call was named
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 man 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 man 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 the value 8
+(
+.IR sizeof(kernel_sigset_t)
+).
+
The glibc
.BR sigprocmask ()
wrapper function hides these details from us, transparently calling