summaryrefslogtreecommitdiffstats
path: root/man3/pthread_sigmask.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/pthread_sigmask.3163
1 files changed, 163 insertions, 0 deletions
diff --git a/man3/pthread_sigmask.3 b/man3/pthread_sigmask.3
new file mode 100644
index 0000000..724f1e9
--- /dev/null
+++ b/man3/pthread_sigmask.3
@@ -0,0 +1,163 @@
+'\" t
+.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
+.\" <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_sigmask 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+pthread_sigmask \- examine and change mask of blocked signals
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <signal.h>
+.PP
+.BI "int pthread_sigmask(int " how ", const sigset_t *" set \
+", sigset_t *" oldset );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR pthread_sigmask ():
+.nf
+ _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_sigmask ()
+function is just like
+.BR sigprocmask (2),
+with the difference that its use in multithreaded programs
+is explicitly specified by POSIX.1.
+Other differences are noted in this page.
+.PP
+For a description of the arguments and operation of this function, see
+.BR sigprocmask (2).
+.SH RETURN VALUE
+On success,
+.BR pthread_sigmask ()
+returns 0;
+on error, it returns an error number.
+.SH ERRORS
+See
+.BR sigprocmask (2).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR pthread_sigmask ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+A new thread inherits a copy of its creator's signal mask.
+.PP
+The glibc
+.BR pthread_sigmask ()
+function silently ignores attempts to block the two real-time signals that
+are used internally by the NPTL threading implementation.
+See
+.BR nptl (7)
+for details.
+.SH EXAMPLES
+The program below blocks some signals in the main thread,
+and then creates a dedicated thread to fetch those signals via
+.BR sigwait (3).
+The following shell session demonstrates its use:
+.PP
+.in +4n
+.EX
+.RB "$" " ./a.out &"
+[1] 5423
+.RB "$" " kill \-QUIT %1"
+Signal handling thread got signal 3
+.RB "$" " kill \-USR1 %1"
+Signal handling thread got signal 10
+.RB "$" " kill \-TERM %1"
+[1]+ Terminated ./a.out
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (pthread_sigmask.c)
+.EX
+#include <errno.h>
+#include <pthread.h>
+#include <signal.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+/* Simple error handling functions */
+\&
+#define handle_error_en(en, msg) \e
+ do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
+\&
+static void *
+sig_thread(void *arg)
+{
+ sigset_t *set = arg;
+ int s, sig;
+\&
+ for (;;) {
+ s = sigwait(set, &sig);
+ if (s != 0)
+ handle_error_en(s, "sigwait");
+ printf("Signal handling thread got signal %d\en", sig);
+ }
+}
+\&
+int
+main(void)
+{
+ pthread_t thread;
+ sigset_t set;
+ int s;
+\&
+ /* Block SIGQUIT and SIGUSR1; other threads created by main()
+ will inherit a copy of the signal mask. */
+\&
+ sigemptyset(&set);
+ sigaddset(&set, SIGQUIT);
+ sigaddset(&set, SIGUSR1);
+ s = pthread_sigmask(SIG_BLOCK, &set, NULL);
+ if (s != 0)
+ handle_error_en(s, "pthread_sigmask");
+\&
+ s = pthread_create(&thread, NULL, &sig_thread, &set);
+ if (s != 0)
+ handle_error_en(s, "pthread_create");
+\&
+ /* Main thread carries on to create other threads and/or do
+ other work. */
+\&
+ pause(); /* Dummy pause so we can test program */
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR sigaction (2),
+.BR sigpending (2),
+.BR sigprocmask (2),
+.BR pthread_attr_setsigmask_np (3),
+.BR pthread_create (3),
+.BR pthread_kill (3),
+.BR sigsetops (3),
+.BR pthreads (7),
+.BR signal (7)