manual: Document the System V sigpause function

  <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(-)
  

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
>
  

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
  

* Michael Kerrisk:

>> +@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/ ?

“Set of blocked signals” is the term preferred by the rest of the
manual.

>> +
>> +New code should use the @code{sigsuspend} function directly.
>
> s/directly/instead/ ?

Applied.

>> +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)
>
> ?

I'm going to post a new version with this addition:

+(The difference is that the BSD variant has a bitmask argument,
+while the @w{System V} expects a single signal number.)

Thanks,
Florian
  

Hi Florian,

On Sat, 16 May 2020 at 11:25, Florian Weimer <fweimer@redhat.com> wrote:
>
> * Michael Kerrisk:
>
> >> +@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/ ?
>
> “Set of blocked signals” is the term preferred by the rest of the
> manual.

Maybe so, but:
* "set of blocked signals" is clunky and a bit imprecise (POSIX uses
the term mask)
* In the very preceding line, you yourself wrote "thread's signal mask"...

Maybe the rest of the manual should be fixed?

Thanks,

Michael
  

* Michael Kerrisk:

> Hi Florian,
>
> On Sat, 16 May 2020 at 11:25, Florian Weimer <fweimer@redhat.com> wrote:
>>
>> * Michael Kerrisk:
>>
>> >> +@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/ ?
>>
>> “Set of blocked signals” is the term preferred by the rest of the
>> manual.
>
> Maybe so, but:
> * "set of blocked signals" is clunky and a bit imprecise (POSIX uses
> the term mask)

Yes, using non-standard terms has its problems.

> * In the very preceding line, you yourself wrote "thread's signal mask"...

That's a good point.  Let me change that as well.

> Maybe the rest of the manual should be fixed?

Maybe, but I was explictly told not to use “pathname” not too long ago.
The other issue is that it is not clear that the term “process signal
mask” (which is already used in a few places) does not reflect the
situatio non Linux.

Thanks,
Florian
  

Hi Florian,

On Sat, 16 May 2020 at 12:03, Florian Weimer <fweimer@redhat.com> wrote:
>
> * Michael Kerrisk:
>
> > Hi Florian,
> >
> > On Sat, 16 May 2020 at 11:25, Florian Weimer <fweimer@redhat.com> wrote:
> >>
> >> * Michael Kerrisk:
> >>
> >> >> +@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/ ?
> >>
> >> “Set of blocked signals” is the term preferred by the rest of the
> >> manual.
> >
> > Maybe so, but:
> > * "set of blocked signals" is clunky and a bit imprecise (POSIX uses
> > the term mask)
>
> Yes, using non-standard terms has its problems.

So, maybe best fix it. Currently the manual uses a mixture of the
terms "signal mask" and "set of blocked signals". I think the fix
should be to uniformly use the POSIX terminology. But I won't say more
on this, beyond this mail; of course it's good that you document these
interfaces, even if not exactly they way I would do it :-).

> > * In the very preceding line, you yourself wrote "thread's signal mask"...
>
> That's a good point.  Let me change that as well.

Yes, but now your text is less precise:

+the set of blocked signals, and waits for a signal to arrive.  On
+return the previous set of blocked signals is restored.

The reader is perhaps left puzzled because you've now removed all
mention of "trhead" or "process". Whose/what set of blocked signals?

> > Maybe the rest of the manual should be fixed?
>
> Maybe, but I was explictly told not to use “pathname” not too long ago.

Yes, but apparently there's a specific GNU guideline about the term.
I'm guessing that there is not a specific guideline pertaining to the
current discussion.

> The other issue is that it is not clear that the term “process signal
> mask” (which is already used in a few places) does not reflect the
> situatio non Linux.

The double negative there makes it hard for me to deduce your point.

Thanks,

Michael