Debian Codegraph @

upstream/debian-trixie/man3/pthread_sigmask.3

raw
1 '\" t
2 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
3 .\" <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH pthread_sigmask 3 2024-06-15 "Linux man-pages 6.9.1"
8 .SH NAME
9 pthread_sigmask \- examine and change mask of blocked signals
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ", " \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .B #include <signal.h>
16 .P
17 .BI "int pthread_sigmask(int " how ", const sigset_t *" set \
18 ", sigset_t *" oldset );
19 .fi
20 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR pthread_sigmask ():
27 .nf
28 _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
29 .fi
30 .SH DESCRIPTION
31 The
32 .BR pthread_sigmask ()
33 function is just like
34 .BR sigprocmask (2),
35 with the difference that its use in multithreaded programs
36 is explicitly specified by POSIX.1.
37 Other differences are noted in this page.
38 .P
39 For a description of the arguments and operation of this function, see
40 .BR sigprocmask (2).
41 .SH RETURN VALUE
42 On success,
43 .BR pthread_sigmask ()
44 returns 0;
45 on error, it returns an error number.
46 .SH ERRORS
47 See
48 .BR sigprocmask (2).
49 .SH ATTRIBUTES
50 For an explanation of the terms used in this section, see
51 .BR attributes (7).
52 .TS
53 allbox;
54 lbx lb lb
55 l l l.
56 Interface Attribute Value
57 T{
58 .na
59 .nh
60 .BR pthread_sigmask ()
61 T} Thread safety MT-Safe
62 .TE
63 .SH STANDARDS
64 POSIX.1-2008.
65 .SH HISTORY
66 POSIX.1-2001.
67 .SH NOTES
68 A new thread inherits a copy of its creator's signal mask.
69 .P
70 The glibc
71 .BR pthread_sigmask ()
72 function silently ignores attempts to block the two real-time signals that
73 are used internally by the NPTL threading implementation.
74 See
75 .BR nptl (7)
76 for details.
77 .SH EXAMPLES
78 The program below blocks some signals in the main thread,
79 and then creates a dedicated thread to fetch those signals via
80 .BR sigwait (3).
81 The following shell session demonstrates its use:
82 .P
83 .in +4n
84 .EX
85 .RB "$" " ./a.out &"
86 [1] 5423
87 .RB "$" " kill \-QUIT %1"
88 Signal handling thread got signal 3
89 .RB "$" " kill \-USR1 %1"
90 Signal handling thread got signal 10
91 .RB "$" " kill \-TERM %1"
92 [1]+ Terminated ./a.out
93 .EE
94 .in
95 .SS Program source
96 \&
97 .\" SRC BEGIN (pthread_sigmask.c)
98 .EX
99 #include <errno.h>
100 #include <pthread.h>
101 #include <signal.h>
102 #include <stdio.h>
103 #include <stdlib.h>
104 #include <unistd.h>
105 \&
106 /* Simple error handling functions */
107 \&
108 #define handle_error_en(en, msg) \[rs]
109 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
110 \&
111 static void *
112 sig_thread(void *arg)
113 {
114 sigset_t *set = arg;
115 int s, sig;
116 \&
117 for (;;) {
118 s = sigwait(set, &sig);
119 if (s != 0)
120 handle_error_en(s, "sigwait");
121 printf("Signal handling thread got signal %d\[rs]n", sig);
122 }
123 }
124 \&
125 int
126 main(void)
127 {
128 pthread_t thread;
129 sigset_t set;
130 int s;
131 \&
132 /* Block SIGQUIT and SIGUSR1; other threads created by main()
133 will inherit a copy of the signal mask. */
134 \&
135 sigemptyset(&set);
136 sigaddset(&set, SIGQUIT);
137 sigaddset(&set, SIGUSR1);
138 s = pthread_sigmask(SIG_BLOCK, &set, NULL);
139 if (s != 0)
140 handle_error_en(s, "pthread_sigmask");
141 \&
142 s = pthread_create(&thread, NULL, &sig_thread, &set);
143 if (s != 0)
144 handle_error_en(s, "pthread_create");
145 \&
146 /* Main thread carries on to create other threads and/or do
147 other work. */
148 \&
149 pause(); /* Dummy pause so we can test program */
150 }
151 .EE
152 .\" SRC END
153 .SH SEE ALSO
154 .BR sigaction (2),
155 .BR sigpending (2),
156 .BR sigprocmask (2),
157 .BR pthread_attr_setsigmask_np (3),
158 .BR pthread_create (3),
159 .BR pthread_kill (3),
160 .BR sigsetops (3),
161 .BR pthreads (7),
162 .BR signal (7)