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

[Carlos O'Donell via Libc-alpha <libc-alpha@sourceware.org>]

On 2/24/20 2:07 PM, Florian Weimer 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.
> 
> -----

Use 3-dash.

>  manual/signal.texi | 35 ++++++++++++++++++++---------------
>  1 file changed, 20 insertions(+), 15 deletions(-)

See comments.

Please post v2.

> 
> 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.

s/sytems/systems/g

>  @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

OK.

> +
> +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}

OK.

Can we leave the safety comments with the old function? They should be correct,
the code is libc_hidden_def, but it's still there.

> +@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.

OK.

> +
> +New code should use the @code{sigsuspend} function directly.
> +
> +The @code{sigpause} function in @theglibc{} is the @w{System V}
> +variant.  The BSD variant is no longer provided by @theglibc{}.

OK. Correct.

>  @end deftypefun
> 


-- 
Cheers,
Carlos.