[v4] manual: Document the System V sigpause function
Commit Message
<signal.h> currently provides only the System V variant of sigpause.
Update the documentation of the function and move it to its own node.
---
Changes from v3:
- Add missing “variant”
- Do not use the term “thread's signal mask”
manual/signal.texi | 27 +++++++++++++++++++++------
1 file changed, 21 insertions(+), 6 deletions(-)
@@ -39,6 +39,8 @@ and synchronize.
* Signal Stack:: Using a Separate Signal Stack.
* BSD Signal Handling:: Additional functions for backward
compatibility with BSD.
+* Obsolete Signal Handling:: Deprecated functions for compatibility with
+ other systems.
@end menu
@node Concepts of Signals
@@ -3301,8 +3303,14 @@ the calling process's signal mask to @var{mask}. The return value is
the previous set of blocked signals.
@end deftypefun
-@deftypefun int sigpause (int @var{mask})
-@standards{BSD, signal.h}
+@node Obsolete Signal Handling
+@section Obsolete Signal Handling
+
+This section describes deprecated signal handling functions which are
+provided for compatibility with other systems.
+
+@deftypefun int sigpause (int @var{signal})
+@standards{XOPEN, signal.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
@c sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
@c [posix]
@@ -3312,8 +3320,15 @@ the previous set of blocked signals.
@c sigdelset dup ok
@c sigset_set_old_mask dup ok
@c sigsuspend dup @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
-This function is the equivalent of @code{sigsuspend} (@pxref{Waiting
-for a Signal}): it sets the calling process's signal mask to @var{mask},
-and waits for a signal to arrive. On return the previous set of blocked
-signals is restored.
+This deprecated function is a precursor to the @code{sigsuspend}
+function (@pxref{Waiting for a Signal}): it removes @var{signal} from
+the set of blocked signals, and waits for a signal to arrive. On
+return the previous set of blocked signals is restored.
+
+New code should use the @code{sigsuspend} function instead.
+
+The @code{sigpause} function in @theglibc{} is the @w{System V}
+variant. The BSD variant is no longer provided by @theglibc{}. (The
+difference is that the BSD variant has a bitmask argument, while the
+@w{System V} variant expects a single signal number.)
@end deftypefun