Re: [PATCH] manual: Document the System V sigpause function

[Michael Kerrisk via Libc-alpha <libc-alpha@sourceware.org>]

Hello Florian,

On Mon, Feb 24, 2020 at 8:07 PM Florian Weimer <fweimer@redhat.com> wrote:
>
> <signal.h> currently provides only the System V variant of sigpause.
> Update the documentation of the function and move it to its own node.
>
> -----
>  manual/signal.texi | 35 ++++++++++++++++++++---------------
>  1 file changed, 20 insertions(+), 15 deletions(-)
>
> diff --git a/manual/signal.texi b/manual/signal.texi
> index 33e6646975..62cec48450 100644
> --- a/manual/signal.texi
> +++ b/manual/signal.texi
> @@ -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 sytems.
>  @end menu
>
>  @node Concepts of Signals
> @@ -3295,19 +3297,22 @@ 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}
> -@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]
> -@c  __sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
> -@c   do_sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
> -@c    sigprocmask(0) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)]
> -@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.
> +@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}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
> +This deprecated function is a precursor to the @code{sigsuspend}
> +function (@pxref{Waiting for a Signal}): it removes @var{signal} from
> +the thread's signal mask, and waits for a signal to arrive.  On return
> +the previous set of blocked signals is restored.

s/previous set of blocked signals is restored/thread's previous signal
mask is restored/ ?

> +
> +New code should use the @code{sigsuspend} function directly.

s/directly/instead/ ?

> +
> +The @code{sigpause} function in @theglibc{} is the @w{System V}
> +variant.  The BSD variant is no longer provided by @theglibc{}.
>  @end deftypefun

Of course, this last sentence leaves the reader asking questions. Maybe:

The BSD variant ==>
The BSD variant (which takes an argument specifying mask of signals to
be temporarily unblocked)

?

Thanks,

Michael