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

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

[Florian Weimer via Libc-alpha]

<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 in v2:
 Fixed typo
 Kept safety comments

 manual/signal.texi | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/manual/signal.texi b/manual/signal.texi
index 911b422a18..4249eba20b 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 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,13 @@ 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 thread's signal mask, 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 directly.
+
+The @code{sigpause} function in @theglibc{} is the @w{System V}
+variant.  The BSD variant is no longer provided by @theglibc{}.
 @end deftypefun

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

[Michael Kerrisk via Libc-alpha]

Hi Florian,

Did you see my comments on the previous iteration of this patch? I got
no reply, and I think none of the points I mentioned has resulted in
change.

Thanks,

Michael

On Thu, May 14, 2020 at 10:11 PM Florian Weimer via Libc-alpha
<libc-alpha@sourceware.org> 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.
>
> ---
> Changes in v2:
>  Fixed typo
>  Kept safety comments
>
>  manual/signal.texi | 25 +++++++++++++++++++------
>  1 file changed, 19 insertions(+), 6 deletions(-)
>
> diff --git a/manual/signal.texi b/manual/signal.texi
> index 911b422a18..4249eba20b 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 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,13 @@ 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 thread's signal mask, 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 directly.
> +
> +The @code{sigpause} function in @theglibc{} is the @w{System V}
> +variant.  The BSD variant is no longer provided by @theglibc{}.
>  @end deftypefun
>

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

[Florian Weimer via Libc-alpha]

* Michael Kerrisk:

> Hi Florian,
>
> Did you see my comments on the previous iteration of this patch? I got
> no reply, and I think none of the points I mentioned has resulted in
> change.

Yes, indeed, it was still tagged in my inbox, but I didn't consult it
before posting v2.  Now working on v3.

Thanks,
Florian