From: "Michael Kerrisk \(man-pages\) via Libc-alpha" <libc-alpha@sourceware.org>
To: Florian Weimer <fweimer@redhat.com>
Cc: libc-alpha <libc-alpha@sourceware.org>
Subject: Re: [PATCH] manual: Document the System V sigpause function
Date: Sat, 16 May 2020 12:18:27 +0200 [thread overview]
Message-ID: <CAKgNAkhCT4yo6nn0oa1HYpX6Eci+pbGaCHtHYWJHH+XpC5XMxw@mail.gmail.com> (raw)
In-Reply-To: <87a728jiww.fsf@oldenburg2.str.redhat.com>
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/
prev parent reply other threads:[~2020-05-16 10:18 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-24 19:07 [PATCH] manual: Document the System V sigpause function Florian Weimer
2020-05-12 4:01 ` Carlos O'Donell via Libc-alpha
2020-05-12 4:59 ` Michael Kerrisk via Libc-alpha
2020-05-16 9:25 ` Florian Weimer via Libc-alpha
2020-05-16 9:56 ` Michael Kerrisk (man-pages) via Libc-alpha
2020-05-16 10:03 ` Florian Weimer via Libc-alpha
2020-05-16 10:18 ` Michael Kerrisk (man-pages) via Libc-alpha [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/libc/involved.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAKgNAkhCT4yo6nn0oa1HYpX6Eci+pbGaCHtHYWJHH+XpC5XMxw@mail.gmail.com \
--to=libc-alpha@sourceware.org \
--cc=fweimer@redhat.com \
--cc=mtk.manpages@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).