From 86d5ed87d30af381c806a1729574d009b40c5e7b Mon Sep 17 00:00:00 2001
From: Keno Fischer <keno@juliacomputing.com>
Date: Wed, 24 Aug 2016 23:24:56 -0400
Subject: [PATCH] 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.
---
 man2/sigprocmask.2 | 49 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2
index 51f79330d..907061f0d 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