2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
5 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
7 .\" http://www.opengroup.org/bookstore/.
8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH THR_SIGSETMASK 3C "Mar 23, 2005"
15 thr_sigsetmask \- change or examine calling thread's signal mask
19 cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
23 \fBint\fR \fBthr_sigsetmask\fR(\fBint\fR \fIhow\fR, \fBconst sigset_t *\fR\fIset\fR, \fBsigset_t *\fR\fIoset\fR);
29 The \fBthr_sigsetmask()\fR function changes or examines a calling thread's
30 signal mask. Each thread has its own signal mask. A new thread inherits the
31 calling thread's signal mask and priority; however, pending signals are not
32 inherited. Signals pending for a new thread will be empty.
35 If the value of the argument \fIset\fR is not \fINULL,\fR \fBset\fR points to
36 a set of signals that can modify the currently blocked set. If the value of
37 \fIset\fR is \fINULL\fR, the value of \fIhow\fR is insignificant and the
38 thread's signal mask is unmodified; thus, \fBthr_sigsetmask()\fR can be used to
39 inquire about the currently blocked signals.
42 The value of the argument \fIhow\fR specifies the method in which the set is
43 changed and takes one of the following values:
50 \fIset\fR corresponds to a set of signals to block. They are added to the
57 \fB\fBSIG_UNBLOCK\fR\fR
60 \fIset\fR corresponds to a set of signals to unblock. These signals are deleted
61 from the current signal mask.
67 \fB\fBSIG_SETMASK\fR\fR
70 \fIset\fR corresponds to the new signal mask. The current signal mask is
71 replaced by \fBset\fR.
76 If the value of \fIoset\fR is not \fINULL\fR, it points to the location where
77 the previous signal mask is stored.
81 Upon successful completion, the \fBthr_sigsetmask()\fR function returns
82 \fB0\fR. Otherwise, it returns a non-zero value.
86 The \fBthr_sigsetmask()\fR function will fail if:
93 The value of \fIhow\fR is not defined and \fIoset\fR is \fINULL.\fR
98 \fBExample 1 \fRCreate a default thread that can serve as a signal
99 catcher/handler with its own signal mask.
102 The following example shows how to create a default thread that can serve as a
103 signal catcher/handler with its own signal mask. \fBnew\fR will have a
104 different value from the creator's signal mask.
108 As POSIX threads and Solaris threads are fully compatible even within the same
109 process, this example uses \fBpthread_create\fR(3C) if you execute \fBa.out
110 0\fR, or \fBthr_create\fR(3C) if you execute \fBa.out 1\fR.
120 The \fBsigemptyset\fR(3C) function initializes a null signal set, \fBnew\fR.
121 The \fBsigaddset\fR(3C) function packs the signal, \fBSIGINT\fR, into that new
128 Either \fBpthread_sigmask()\fR or \fBthr_sigsetmask()\fR is used to mask the
129 signal, \fBSIGINT\fR (CTRL-C), from the calling thread, which is \fBmain()\fR.
130 The signal is masked to guarantee that only the new thread will receive this
137 \fBpthread_create()\fR or \fBthr_create()\fR creates the signal-handling
144 Using \fBpthread_join\fR(3C) or \fBthr_join\fR(3C), \fBmain()\fR then waits for
145 the termination of that signal-handling thread, whose \fBID\fR number is
146 \fBuser_threadID\fR. Then \fBmain()\fR will \fBsleep\fR(3C) for 2 seconds,
147 after which the program terminates.
153 The signal-handling thread, \fBhandler\fR:
158 Assigns the handler \fBinterrupt()\fR to handle the signal \fBSIGINT\fR by the
159 call to \fBsigaction\fR(2).
165 Resets its own signal set to \fInot block\fR the signal, \fBSIGINT\fR.
171 Sleeps for 8 seconds to allow time for the user to deliver the signal
172 \fBSIGINT\fR by pressing the \fBCTRL-C.\fR
178 /* cc thisfile.c -lthread -lpthread */
179 #define _REENTRANT /* basic first 3-lines for threads */
183 thread_t user_threadID;
185 void *handler(\|), interrupt(\|);
188 main( int argc, char *argv[\|] ){
192 sigaddset(&new, SIGINT);
195 case '0': /* POSIX */
196 pthread_sigmask(SIG_BLOCK, &new, NULL);
197 pthread_create(&user_threadID, NULL, handler, argv[1]);
198 pthread_join(user_threadID, NULL);
201 case '1': /* Solaris */
202 thr_sigsetmask(SIG_BLOCK, &new, NULL);
203 thr_create(NULL, 0, handler, argv[1], 0, &user_threadID);
204 thr_join(user_threadID, NULL, NULL);
208 printf("thread handler, # %d, has exited\en",user_threadID);
210 printf("main thread, # %d is done\en", thr_self(\|));
214 struct sigaction act;
219 act.sa_handler = interrupt;
220 sigaction(SIGINT, &act, NULL);
222 case '0': /* POSIX */
223 pthread_sigmask(SIG_UNBLOCK, &new, NULL);
225 case '1': /* Solaris */
226 thr_sigsetmask(SIG_UNBLOCK, &new, NULL);
229 printf("\en Press CTRL-C to deliver SIGINT signal to the process\en");
230 sleep(8); /* give user time to hit CTRL-C */
237 printf("thread %d caught signal %d\en", thr_self(\|), sig);
240 void test_argv(char argv1[\|]) {
242 printf("use 0 as arg1 to use thr_create(\|);\en \e
243 or use 1 as arg1 to use pthread_create(\|)\en");
252 In the last example, the \fBhandler\fR thread served as a signal-handler while
253 also taking care of activity of its own (in this case, sleeping, although it
254 could have been some other activity). A thread could be completely dedicated to
255 signal-handling simply by waiting for the delivery of a selected signal by
256 blocking with \fBsigwait\fR(2). The two subroutines in the previous example,
257 \fBhandler()\fR and \fBinterrupt()\fR, could have been replaced with the
264 handler(void *ignore)
266 printf("thread %d waiting for you to press the CTRL-C keys\en",
268 sigwait(&new, &signal);
269 printf("thread %d has received the signal %d \en", thr_self(\|), signal);
271 /*pthread_create(\|) and thr_create(\|) would use NULL instead of
272 argv[1] for the arg passed to handler(\|) */
278 In this routine, one thread is dedicated to catching and handling the signal
279 specified by the set \fBnew\fR, which allows \fBmain()\fR and all of its other
280 sub-threads, created \fIafter\fR \fBpthread_sigmask()\fR or
281 \fBthr_sigsetmask()\fR masked that signal, to continue uninterrupted. Any use
282 of \fBsigwait\fR(2) should be such that all threads block the signals passed
283 to \fBsigwait\fR(2) at all times. Only the thread that calls \fBsigwait()\fR
284 will get the signals. The call to \fBsigwait\fR(2) takes two arguments.
288 For this type of background dedicated signal-handling routine, a Solaris daemon
289 thread can be used by passing the argument \fBTHR_DAEMON\fR to
295 See \fBattributes\fR(5) for descriptions of the following attributes:
303 ATTRIBUTE TYPE ATTRIBUTE VALUE
305 MT-Level MT-Safe and Async-Signal-Safe
311 \fBsigaction\fR(2), \fBsigprocmask\fR(2), \fBsigwait\fR(2),
312 \fBcond_wait\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C),
313 \fBpthread_join\fR(3C), \fBpthread_self\fR(3C), \fBsigaddset\fR(3C),
314 \fBsigemptyset\fR(3C), \fBsigsetops\fR(3C), \fBsleep\fR(3C),
315 \fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5)
319 It is not possible to block signals that cannot be caught or ignored (see
320 \fBsigaction\fR(2)). It is also not possible to block or unblock
321 \fBSIGCANCEL\fR, as \fBSIGCANCEL\fR is reserved for the implementation of POSIX
322 thread cancellation (see \fBpthread_cancel\fR(3C) and \fBcancellation\fR(5)).
323 This restriction is quietly enforced by the standard C library.
326 Using \fBsigwait\fR(2) in a dedicated thread allows asynchronously generated
327 signals to be managed synchronously; however, \fBsigwait\fR(2) should never be
328 used to manage synchronously generated signals.
331 Synchronously generated signals are exceptions that are generated by a thread
332 and are directed at the thread causing the exception. Since \fBsigwait()\fR
333 blocks waiting for signals, the blocking thread cannot receive a synchronously
337 Calling the\fBsigprocmask\fR(2) function will be the same as if
338 \fBthr_sigsetmask()\fR or \fBpthread_sigmask()\fR has been called. POSIX leaves
339 the semantics of the call to \fBsigprocmask\fR(2) unspecified in a
340 multi-threaded process, so programs that care about POSIX portability should
341 not depend on this semantic.
344 If a signal is delivered while a thread is waiting on a condition variable,
345 the \fBcond_wait\fR(3C) function will be interrupted and the handler will be
346 executed. The state of the lock protecting the condition variable is undefined
347 while the thread is executing the signal handler.
350 Signals that are generated synchronously should not be masked. If such a signal
351 is blocked and delivered, the receiving process is killed.