* [PATCH] sigprocmask.2: Expand/Clarify libc/kernel sigset_t difference
@ 2016-08-25 3:24 Keno Fischer
[not found] ` <20160825032456.GA15347-nTuEee01erudBw3G0RLmbfBZMHv189dXZkel5v8DVj8@public.gmane.org>
0 siblings, 1 reply; 2+ messages in thread
From: Keno Fischer @ 2016-08-25 3:24 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
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 51f7933..907061f 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
--
2.8.1
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] sigprocmask.2: Expand/Clarify libc/kernel sigset_t difference
[not found] ` <20160825032456.GA15347-nTuEee01erudBw3G0RLmbfBZMHv189dXZkel5v8DVj8@public.gmane.org>
@ 2016-08-28 5:48 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 2+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-08-28 5:48 UTC (permalink / raw)
To: Keno Fischer
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
Hello Keno,
On 08/25/2016 03:24 PM, Keno Fischer wrote:
> 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.
Nice work! Patch applied. Thank you.
Cheers,
Michael
> ---
> man2/sigprocmask.2 | 49 +++++++++++++++++++++++++++++++++++++++----------
> 1 file changed, 39 insertions(+), 10 deletions(-)
>
> diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2
> index 51f7933..907061f 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
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2016-08-28 5:48 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-08-25 3:24 [PATCH] sigprocmask.2: Expand/Clarify libc/kernel sigset_t difference Keno Fischer
[not found] ` <20160825032456.GA15347-nTuEee01erudBw3G0RLmbfBZMHv189dXZkel5v8DVj8@public.gmane.org>
2016-08-28 5:48 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.