[v2] manual: Add pthread_attr_setsigmask_np, pthread_attr_getsigmask_np

  And the PTHREAD_ATTR_NO_SIGMASK_NP constant.

---
 manual/threads.texi | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
  

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
> +@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.

> +@end enumerate

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

> +The start routine for the created thread needs to locate the desired

Maybe: s/created/new/ ?

> +signal mask and use @code{pthread_sigmask} to apply it to the thread.
> +If the signal mask was copied to a heap allocation, the copy should be
> +freed.
> +
>  @node Waiting with Explicit Clocks
>  @subsubsection Functions for Waiting According to a Specific Clock

Thanks,

Michael
  

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
  

* Michael Kerrisk:

>> > +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.

In the HTML version, it's quite visible: the macro description is
indented.  Likewise in the Info version.  So I think we are good.

>> > +@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.
>> ]]

Thanks for keeping my terminology straight.  Yes, “delivered” is indeed
the term I was looking for.

Florian