Revert "src.mk, All pages: Move man* to man/"

[thirdparty/man-pages.git] / man3 / pthread_sigmask.3

diff --git a/man3/pthread_sigmask.3 b/man3/pthread_sigmask.3
new file mode 100644 (file)
index 0000000..ffec8bc
--- /dev/null
+++ b/man3/pthread_sigmask.3
@@ -0,0 +1,160 @@
+.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH PTHREAD_SIGMASK 3 2021-03-22 "Linux man-pages (unreleased)"
+.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).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.BR pthread_sigmask ()
+T}     Thread safety   MT-Safe
+.TE
+.hy
+.ad
+.sp 1
+.SH STANDARDS
+POSIX.1-2001, POSIX.1-2008.
+.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
+\&
+.EX
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <signal.h>
+#include <errno.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(int argc, char *argv[])
+{
+    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
+.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)