| blob | 1826b1623f48f0ef016d133ab6c6acb12f1d330b |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH PTHREAD_SIGMASK 3C "Mar 23, 2005"
48 .SH NAME
49 pthread_sigmask \- change or examine calling thread's signal mask
50 .SH SYNOPSIS
51 .LP
52 .nf
53 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
54 #include <pthread.h>
55 #include <signal.h>
57 \fBint\fR \fBpthread_sigmask\fR(\fBint\fR \fIhow\fR, \fBconst sigset_t *\fR\fIset\fR, \fBsigset_t *\fR\fIoset\fR);
58 .fi
60 .SH DESCRIPTION
61 .sp
62 .LP
63 The \fBpthread_sigmask()\fR function changes or examines a calling thread's
64 signal mask. Each thread has its own signal mask. A new thread inherits the
65 calling thread's signal mask and priority; however, pending signals are not
66 inherited. Signals pending for a new thread will be empty.
67 .sp
68 .LP
69 If the value of the argument \fIset\fR is not \fINULL\fR, \fIset\fR points to a
70 set of signals that can modify the currently blocked set. If the value of
71 \fIset\fR is \fINULL\fR, the value of \fIhow\fR is insignificant and the
72 thread's signal mask is unmodified; thus, \fBpthread_sigmask()\fR can be used
73 to inquire about the currently blocked signals.
74 .sp
75 .LP
76 The value of the argument \fIhow\fR specifies the method in which the set is
77 changed and takes one of the following values:
78 .sp
79 .ne 2
80 .na
81 \fB\fBSIG_BLOCK\fR\fR
82 .ad
83 .RS 15n
84 \fIset\fR corresponds to a set of signals to block. They are added to the
85 current signal mask.
86 .RE
88 .sp
89 .ne 2
90 .na
91 \fB\fBSIG_UNBLOCK\fR\fR
92 .ad
93 .RS 15n
94 \fIset\fR corresponds to a set of signals to unblock. These signals are deleted
95 from the current signal mask.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fBSIG_SETMASK\fR\fR
102 .ad
103 .RS 15n
104 \fIset\fR corresponds to the new signal mask. The current signal mask is
105 replaced by \fBset\fR.
106 .RE
108 .sp
109 .LP
110 If the value of \fIoset\fR is not \fINULL\fR, it points to the location where
111 the previous signal mask is stored.
112 .SH RETURN VALUES
113 .sp
114 .LP
115 Upon successful completion, the \fBpthread_sigmask()\fR function returns
116 \fB0\fR. Otherwise, it returns a non-zero value.
117 .SH ERRORS
118 .sp
119 .LP
120 The \fBpthread_sigmask()\fR function will fail if:
121 .sp
122 .ne 2
123 .na
124 \fB\fBEINVAL\fR\fR
125 .ad
126 .RS 10n
127 The value of \fIhow\fR is not defined and \fIoset\fR is \fINULL\fR.
128 .RE
130 .SH EXAMPLES
131 .LP
132 \fBExample 1 \fRCreate a default thread that can serve as a signal
133 catcher/handler with its own signal mask.
134 .sp
135 .LP
136 The following example shows how to create a default thread that can serve as a
137 signal catcher/handler with its own signal mask. \fBnew\fR will have a
138 different value from the creator's signal mask.
140 .sp
141 .LP
142 As POSIX threads and Solaris threads are fully compatible even within the same
143 process, this example uses \fBpthread_create\fR(3C) if you execute \fBa.out
144 0\fR, or \fBthr_create\fR(3C) if you execute \fBa.out 1\fR.
146 .sp
147 .LP
148 In this example:
150 .RS +4
151 .TP
152 .ie t \(bu
153 .el o
154 The \fBsigemptyset\fR(3C) function initializes a null signal set, \fBnew\fR.
155 The \fBsigaddset\fR(3C) function packs the signal, \fBSIGINT\fR, into that new
156 set.
157 .RE
158 .RS +4
159 .TP
160 .ie t \(bu
161 .el o
162 Either \fBpthread_sigmask()\fR or \fBthr_sigsetmask()\fR is used to mask the
163 signal, \fBSIGINT\fR (CTRL-C), from the calling thread, which is \fBmain()\fR.
164 The signal is masked to guarantee that only the new thread will receive this
165 signal.
166 .RE
167 .RS +4
168 .TP
169 .ie t \(bu
170 .el o
171 \fBpthread_create()\fR or \fBthr_create()\fR creates the signal-handling
172 thread.
173 .RE
174 .RS +4
175 .TP
176 .ie t \(bu
177 .el o
178 Using \fBpthread_join\fR(3C) or \fBthr_join\fR(3C), \fBmain()\fR then waits for
179 the termination of that signal-handling thread, whose \fBID\fR number is
180 \fBuser_threadID\fR; \fBmain()\fR will then \fBsleep\fR(3C) for 2 seconds,
181 after which the program terminates.
182 .RE
183 .RS +4
184 .TP
185 .ie t \(bu
186 .el o
187 The signal-handling thread, \fBhandler\fR:
188 .RS +4
189 .TP
190 .ie t \(bu
191 .el o
192 Assigns the handler \fBinterrupt()\fR to handle the signal \fBSIGINT\fR, by the
193 call to \fBsigaction\fR(2).
194 .RE
195 .RS +4
196 .TP
197 .ie t \(bu
198 .el o
199 Resets its own signal set to \fInot block\fR the signal, \fBSIGINT\fR.
200 .RE
201 .RS +4
202 .TP
203 .ie t \(bu
204 .el o
205 Sleeps for 8 seconds to allow time for the user to deliver the signal,
206 \fBSIGINT\fR, by pressing the \fBCTRL-C\fR.
207 .RE
208 .RE
209 .sp
210 .in +2
211 .nf
212 /* cc thisfile.c -lthread -lpthread */
213 #define _REENTRANT /* basic first 3-lines for threads */
214 #include <pthread.h>
215 #include <thread.h>
216 thread_t user_threadID;
217 sigset_t new;
218 void *handler(\|), interrupt(\|);
220 int
221 main( int argc, char *argv[\|] ) {
222 test_argv(argv[1]);
224 sigemptyset(&new);
225 sigaddset(&new, SIGINT);
226 switch(*argv[1]) {
228 case '0': /* POSIX */
229 pthread_sigmask(SIG_BLOCK, &new, NULL);
230 pthread_create(&user_threadID, NULL, handler,
231 argv[1]);
232 pthread_join(user_threadID, NULL);
233 break;
235 case '1': /* Solaris */
236 thr_sigsetmask(SIG_BLOCK, &new, NULL);
237 thr_create(NULL, 0, handler, argv[1], 0,
238 &user_threadID);
239 thr_join(user_threadID, NULL, NULL);
240 break;
241 } /* switch */
243 printf("thread handler, # %d, has exited\en",user_threadID);
244 sleep(2);
245 printf("main thread, # %d is done\en", thr_self(\|));
246 return (0)
247 } /* end main */
249 struct sigaction act;
251 void *
252 handler(char *argv1)
253 {
254 act.sa_handler = interrupt;
255 sigaction(SIGINT, &act, NULL);
256 switch(*argv1) {
257 case '0': /* POSIX */
258 pthread_sigmask(SIG_UNBLOCK, &new, NULL);
259 break;
260 case '1': /* Solaris */
261 thr_sigsetmask(SIG_UNBLOCK, &new, NULL);
262 break;
263 }
264 printf("\en Press CTRL-C to deliver SIGINT signal to the
265 process\en");
266 sleep(8); /* give user time to hit CTRL-C */
267 return (NULL)
268 }
270 void
271 interrupt(int sig)
272 {
273 printf("thread %d caught signal %d\en", thr_self(\|), sig);
274 }
276 void test_argv(char argv1[\|]) {
277 if(argv1 == NULL) {
278 printf("use 0 as arg1 to use thr_create(\|);\en \e
279 or use 1 as arg1 to use pthread_create(\|)\en");
280 exit(NULL);
281 }
282 }
283 .fi
284 .in -2
286 .sp
287 .LP
288 In the last example, the \fBhandler\fR thread served as a signal-handler while
289 also taking care of activity of its own (in this case, sleeping, although it
290 could have been some other activity). A thread could be completely dedicated to
291 signal-handling simply by waiting for the delivery of a selected signal by
292 blocking with \fBsigwait\fR(2). The two subroutines in the previous example,
293 \fBhandler()\fR and \fBinterrupt()\fR, could have been replaced with the
294 following routine:
296 .sp
297 .in +2
298 .nf
299 void *
300 handler(void *unused)
301 {
302 int signal;
303 printf("thread %d is waiting for you to press the CTRL-C keys\en",
304 thr_self(\|));
305 sigwait(&new, &signal);
306 printf("thread %d has received the signal %d \en", thr_self(\|),
307 signal);
308 return (NULL);
309 }
310 /* pthread_create(\|) and thr_create(\|) would use NULL instead
311 of argv[1] for the arg passed to handler(\|) */
312 .fi
313 .in -2
315 .sp
316 .LP
317 In this routine, one thread is dedicated to catching and handling the signal
318 specified by the set \fBnew\fR, which allows \fBmain()\fR and all of its other
319 sub-threads, created \fIafter\fR \fBpthread_sigmask()\fR or
320 \fBthr_sigsetmask()\fR masked that signal, to continue uninterrupted. Any use
321 of \fBsigwait\fR(2) should be such that all threads block the signals passed
322 to \fBsigwait\fR(2) at all times. Only the thread that calls \fBsigwait()\fR
323 will get the signals. The call to \fBsigwait\fR(2) takes two arguments.
325 .sp
326 .LP
327 For this type of background dedicated signal-handling routine, a Solaris daemon
328 thread can be used by passing the argument \fBTHR_DAEMON\fR to
329 \fBthr_create\fR(3C).
331 .SH ATTRIBUTES
332 .sp
333 .LP
334 See \fBattributes\fR(5) for descriptions of the following attributes:
335 .sp
337 .sp
338 .TS
339 box;
340 c | c
341 l | l .
342 ATTRIBUTE TYPE ATTRIBUTE VALUE
343 _
344 Interface Stability Standard
345 _
346 MT-Level MT-Safe and Async-Signal-Safe
347 .TE
349 .SH SEE ALSO
350 .sp
351 .LP
352 \fBsigaction\fR(2), \fBsigprocmask\fR(2), \fBsigwait\fR(2),
353 \fBcond_wait\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C),
354 \fBpthread_join\fR(3C), \fBpthread_self\fR(3C), \fBsigaddset\fR(3C),
355 \fBsigemptyset\fR(3C), \fBsigsetops\fR(3C), \fBsleep\fR(3C),
356 \fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5)
357 .SH NOTES
358 .sp
359 .LP
360 It is not possible to block signals that cannot be caught or ignored (see
361 \fBsigaction\fR(2)). It is also not possible to block or unblock
362 \fBSIGCANCEL\fR, as \fBSIGCANCEL\fR is reserved for the implementation of POSIX
363 thread cancellation (see \fBpthread_cancel\fR(3C) and \fBcancellation\fR(5)).
364 This restriction is quietly enforced by the standard C library.
365 .sp
366 .LP
367 Using \fBsigwait\fR(2) in a dedicated thread allows asynchronously generated
368 signals to be managed synchronously; however, \fBsigwait\fR(2) should never be
369 used to manage synchronously generated signals.
370 .sp
371 .LP
372 Synchronously generated signals are exceptions that are generated by a thread
373 and are directed at the thread causing the exception. Since \fBsigwait()\fR
374 blocks waiting for signals, the blocking thread cannot receive a synchronously
375 generated signal.
376 .sp
377 .LP
378 The \fBsigprocmask\fR(2) function behaves the same as if
379 \fBpthread_sigmask()\fR has been called. POSIX leaves the semantics of the call
380 to \fBsigprocmask\fR(2) unspecified in a multi-threaded process, so programs
381 that care about POSIX portability should not depend on this semantic.
382 .sp
383 .LP
384 If a signal is delivered while a thread is waiting on a condition variable, the
385 \fBcond_wait\fR(3C) function will be interrupted and the handler will be
386 executed. The state of the lock protecting the condition variable is undefined
387 while the thread is executing the signal handler.
388 .sp
389 .LP
390 Although \fBpthread_sigmask()\fR is Async-Signal-Safe with respect to the
391 Solaris environment, this safeness is not guaranteed to be portable to other
392 POSIX domains.
393 .sp
394 .LP
395 Signals that are generated synchronously should not be masked. If such a signal
396 is blocked and delivered, the receiving process is killed.