mirror of https://github.com/mkerrisk/man-pages
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.
This commit is contained in:
parent
48bafe7c02
commit
86d5ed87d3
|
@ -32,8 +32,19 @@ sigprocmask, rt_sigprocmask \- examine and change blocked signals
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.B #include <signal.h>
|
.B #include <signal.h>
|
||||||
.sp
|
.sp
|
||||||
.BI "int sigprocmask(int " how ", const sigset_t *" set ,
|
.nf
|
||||||
.BI "sigset_t *" oldset );
|
/* 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
|
.sp
|
||||||
.in -4n
|
.in -4n
|
||||||
Feature Test Macro Requirements for glibc (see
|
Feature Test Macro Requirements for glibc (see
|
||||||
|
@ -111,9 +122,10 @@ or
|
||||||
argument points outside the process's allocated address space.
|
argument points outside the process's allocated address space.
|
||||||
.TP
|
.TP
|
||||||
.B EINVAL
|
.B EINVAL
|
||||||
The value specified in
|
Either the value specified in
|
||||||
.I how
|
.I how
|
||||||
was invalid.
|
was invalid or the kernel does not support the size passed in
|
||||||
|
.I sigsetsize.
|
||||||
.SH CONFORMING TO
|
.SH CONFORMING TO
|
||||||
POSIX.1-2001, POSIX.1-2008.
|
POSIX.1-2001, POSIX.1-2008.
|
||||||
.SH NOTES
|
.SH NOTES
|
||||||
|
@ -148,6 +160,16 @@ See
|
||||||
for details on manipulating signal sets.
|
for details on manipulating signal sets.
|
||||||
.\"
|
.\"
|
||||||
.SS C library/kernel differences
|
.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
|
The glibc wrapper function for
|
||||||
.BR sigprocmask ()
|
.BR sigprocmask ()
|
||||||
silently ignores attempts to block the two real-time signals that
|
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,
|
However, with the addition of real-time signals in Linux 2.2,
|
||||||
the fixed-size, 32-bit
|
the fixed-size, 32-bit
|
||||||
.IR sigset_t
|
.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.
|
type supported by that system call was no longer fit for purpose.
|
||||||
Consequently, a new system call,
|
Consequently, a new system call,
|
||||||
.BR rt_sigprocmask (),
|
.BR rt_sigprocmask (),
|
||||||
was added to support an enlarged
|
was added to support an enlarged
|
||||||
.IR sigset_t
|
.IR sigset_t
|
||||||
type.
|
type
|
||||||
|
(referred to as
|
||||||
|
.IR kernel_sigset_t
|
||||||
|
in this man page
|
||||||
|
).
|
||||||
The new system call takes a fourth argument,
|
The new system call takes a fourth argument,
|
||||||
.IR "size_t sigsetsize" ,
|
.IR "size_t sigsetsize" ,
|
||||||
which specifies the size in bytes of the signal sets in
|
which specifies the size in bytes of the signal sets in
|
||||||
.IR set
|
.IR set
|
||||||
and
|
and
|
||||||
.IR oldset .
|
.IR oldset .
|
||||||
This argument is currently required to have the value
|
This argument is currently required to have the value 8
|
||||||
.IR sizeof(sigset_t)
|
(
|
||||||
(or the error
|
.IR sizeof(kernel_sigset_t)
|
||||||
.B EINVAL
|
).
|
||||||
results).
|
|
||||||
The glibc
|
The glibc
|
||||||
.BR sigprocmask ()
|
.BR sigprocmask ()
|
||||||
wrapper function hides these details from us, transparently calling
|
wrapper function hides these details from us, transparently calling
|
||||||
|
|
Loading…
Reference in New Issue