From 340f4f9e7c97de5c7cbba18675ecd50514a723a5 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sun, 1 Nov 2020 18:09:54 +0100 Subject: [PATCH] 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 --- man3/pthread_attr_setsigmask_np.3 | 147 ++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 man3/pthread_attr_setsigmask_np.3 diff --git a/man3/pthread_attr_setsigmask_np.3 b/man3/pthread_attr_setsigmask_np.3 new file mode 100644 index 000000000..418ef2dba --- /dev/null +++ b/man3/pthread_attr_setsigmask_np.3 @@ -0,0 +1,147 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" %%%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 +.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)