pthread_attr_setsigmask_np.3: New page for pthread_attr_setsigmask_np() + pthread_attr_getsigmask_np()

Add a page documenting the pthread_attr_setsigmask_np(3) and
pthread_attr_getsigmask_np() functions added in glibc 2.32.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 147 insertions, 0 deletions

diff --git a/man3/pthread_attr_setsigmask_np.3 b/man3/pthread_attr_setsigmask_np.3
new file mode 100644
index 0000000000..418ef2dbac
--- /dev/null
+++ b/man3/pthread_attr_setsigmask_np.3
@@ -0,0 +1,147 @@
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.TH PTHREAD_ATTR_SETSIGMASK_NP 3 2020-11-01 "Linux" "Linux Programmer's Manual"
+.SH NAME
+pthread_attr_setsigmask_np, pthread_attr_getsigmask_np \- set/get
+signal mask attribute in thread attributes object
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
+.B #include <pthread.h>
+.PP
+.BI "int pthread_attr_setsigmask_np(pthread_attr_t *" attr ,
+.BI "                               const sigset_t *" sigmask );
+.BI "int pthread_attr_getsigmask_np(const pthread_attr_t *" attr ,
+.BI "                               sigset_t *" sigmask );
+.PP
+Compile and link with \fI\-pthread\fP.
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_attr_setsigmask_np ()
+function sets the signal mask attribute of the
+thread attributes object referred to by
+.I attr
+to the value specified in
+.IR *sigmask .
+If
+.I sigmask
+is specified as NULL, then any existing signal mask attribute in
+.I attr
+is unset.
+.PP
+The
+.BR pthread_attr_getsigmask_np ()
+function returns the signal mask attribute of the thread attributes object
+referred to by
+.IR attr
+in the buffer pointed to by
+.IR sigmask .
+If the signal mask attribute is currently unset,
+then this function returns the special value
+.B PTHREAD_ATTR_NO_SIGMASK_NP
+as its result.
+.SH RETURN VALUE
+The
+.BR pthread_attr_setsigmask_np ()
+function returns 0 on success, or a nonzero error number on failure.
+.PP
+the
+.BR pthread_attr_getsigmask_np ()
+function returns either 0 or
+.BR PTHREAD_ATTR_NO_SIGMASK_NP .
+When 0 is returned, the signal mask attribute is returned via
+.IR sigmask .
+A return value of
+.B PTHREAD_ATTR_NO_SIGMASK_NP
+indicates that the signal mask attribute is not set in
+.IR attr .
+.PP
+On error, these functions return a positive error number.
+.SH ERRORS
+.TP
+.B ENOMEM
+.RB ( pthread_attr_setsigmask_np ())
+Could not allocate memory.
+.SH VERSIONS
+These functions are provided by glibc since version 2.32.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw30 lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR pthread_attr_setsigmask_np (),
+.BR pthread_attr_getsigmask_np ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH CONFORMING TO
+These functions are nonstandard GNU extensions;
+hence the suffix "_np" (nonportable) in the names.
+.SH NOTES
+The signal mask attribute determines the signal mask that will be assigned to
+a thread created using the thread attributes object
+.IR attr .
+If this attribute is not set, then a thread created using
+.I attr
+will inherit a copy of the creating thread's signal mask.
+.PP
+For more details on signal masks, see
+.BR sigprocmask (2).
+For a description of a set of macros
+that can be used to manipulate and inspect signals sets, see
+.BR sigsetops (3).
+.PP
+In the absence of
+.BR pthread_attr_setsigmask_np ()
+it is possible to create a thread with a desired signal mask as follows:
+.IP \(bu 2
+The creating thread uses
+.BR pthread_sigmask (3)
+to save its current signal mask and set its mask to block all signals.
+.IP \(bu
+The new thread is then created using
+.BR pthread_create ();
+the new thread will inherit the creating thread's signal mask.
+.IP \(bu
+The new thread sets its signal mask to the desired value using
+.BR pthread_sigmask (3).
+.IP \(bu
+The creating thread restores its signal mask to the original value.
+.PP
+Following the above steps,
+there is no possibility for the new thread to receive a signal
+before it has adjusted its signal mask to the desired value.
+.SH SEE ALSO
+.BR sigprocmask (2),
+.BR pthread_attr_init (3),
+.BR pthread_sigmask (3),
+.BR pthreads (7),
+.BR signals (7)