[PATCH v2] manual: Add pthread_attr_setsigmask_np, pthread_attr_getsigmask_np

[Michael Kerrisk (man-pages)]

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

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