[PATCH v2] manual: Add pthread_attr_setsigmask_np, pthread_attr_getsigmask_np

[Michael Kerrisk]

Hi Florian,

Actually, on rereading, I realize I didn't fully grok the structure of
the discussion. See below.

On Wed, Jun 3, 2020 at 12:27 PM Michael Kerrisk (man-pages) via
Libc-alpha <libc-alpha@sourceware.org> wrote:
>
> Hi Florian,
>
> On Wed, 3 Jun 2020 at 11:30, Florian Weimer <fweimer@redhat.com> wrote:
> >
> > And the PTHREAD_ATTR_NO_SIGMASK_NP constant.
> >
> > ---
> >  manual/threads.texi | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 72 insertions(+)
> >
> > diff --git a/manual/threads.texi b/manual/threads.texi
> > index a425635179..6d581a35c6 100644
> > --- a/manual/threads.texi
> > +++ b/manual/threads.texi
> > @@ -625,6 +625,7 @@ the standard.
> >  @menu
> >  * Default Thread Attributes::             Setting default attributes for
> >                                           threads in a process.
> > +* Initial Thread Signal Mask::            Setting the initial mask of threads.
> >  * Waiting with Explicit Clocks::          Functions for waiting with an
> >                                            explicit clock specification.
> >  @end menu
> > @@ -671,6 +672,77 @@ The system does not have sufficient memory.
> >  @end table
> >  @end deftypefun
> >
> > +@node Initial Thread Signal Mask
> > +@subsubsection Controlling the Initial Signal Mask of a New Thread
> > +
> > +@Theglibc{} provides a way to specify the initial signal mask of a
> > +thread created using @code{pthread_create}, passing a thread attribute
> > +object configured for this purpose.
> > +
> > +@deftypefun int pthread_attr_setsigmask_np (pthread_attr_t *@var{attr}, const sigset_t *@var{sigmask})
> > +@standards{GNU, pthread.h}
> > +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
> > +Change the initial signal mask specified by @var{attr}.  If
> > +@var{sigmask} is not @code{NULL}, the initial signal mask for new
> > +threads created with @var{attr} is set to @code{*@var{sigmask}}.  If
> > +@var{sigmask} is @code{NULL}, @var{attr} will no longer specify an
> > +explicit signal mask, so that the initial signal mask of the new
> > +thread is inherited from the thread that calls @code{pthread_create}.
> > +
> > +This function returns zero on success, and @code{ENOMEM} on memory
> > +allocation failure.
> > +@end deftypefun
> > +
> > +@deftypefun int pthread_attr_getsigmask_np (const pthread_attr_t *@var{attr}, sigset_t *@var{sigmask})
> > +@standards{GNU, pthread.h}
> > +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
> > +Retrieve the signal mask stored in @var{attr} and copy it to
> > +@code{*@var{sigmask}}.  If the signal mask has not been set, return
> > +the special constant @code{PTHREAD_ATTR_NO_SIGMASK_NP}, otherwise
> > +return zero.
> > +
> > +@c Move this to the documentation of pthread_getattr_np once it exists.
> > +Obtaining the signal mask only works if it has been previously stored
> > +by @code{pthread_attr_setsigmask_np}.  For example, the
> > +@code{pthread_getattr_np} function does not obtain the current signal
> > +mask of the specified thread, and @code{pthread_attr_getsigmask_np}
> > +will subsequently report the signal mask as unset.
> > +@end deftypefun
> > +
> > +@deftypevr Macro int PTHREAD_ATTR_NO_SIGMASK_NP
> > +The special value returned by @code{pthread_attr_setsigmask_np} to
> > +indicate that no signal mask has been set for the attribute.
> > +@end deftypevr
> > +
> > +It is possible to create a new thread with a specific signal mask
> > +without using these functions.  On the thread that calls

[I missed this piece, that the bullet list is *steps in the thread
that calls pthread_create()*. Sorry about the confusion.

> > +@code{pthread_create}, the required steps for the general case are:
> > +
> > +@enumerate 1
> > +@item
> > +Mask all signals, and save the old signal mask, using
> > +@code{pthread_sigmask}.  This ensures that the new thread will be
> > +created with all signals masked, so that signals can arrive on the
>
> s/signals/no signals/
>
> The word "arrive" seems a bit vague to me. How about:
>
> [[
> This ensures that the new thread will be created with all signals
> masked, so that no signals can be delivered until the desired signal
> mask is set.
> ]]
>
> > +thread until the desired signal mask is set.
> > +
> > +@item
> > +Call @code{pthread_create} to create the new thread, passing the
> > +desired signal mask to the thread start routine (which could be a
> > +wrapper function for the actual thread start routine).  It may be
> > +necessary to make a copy of the desired signal mask on the heap, so
> > +that the life-time of the copy extends to the point when the start
> > +routine needs to access the signal mask.
> > +
> > +@item
> > +Restore the thread's signal mask, to the set that was saved in the
> > +first step.
>
> By this point, some readers may be wondering: "which thread?". Maybe
> the last sentence is better as something like:
>
> In the thread that called @code{pthread_create}, restore the signal
> mask to the value that was saved in the first step.

[Okay -- maybe that last change isn't sensible]

> > +@end enumerate
>
> I think that this next piece could easily just be the fourth item in
> the enumeration, rather than sitting after it.

[And I think that last suggestion can likewise be ignored.]

Thanks,

Michael