[PATCH] manual: Document the System V sigpause function

[Michael Kerrisk (man-pages)]

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

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/