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 13, 2016"
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);
28 The \fBthr_sigsetmask()\fR function changes or examines a calling thread's
29 signal mask. Each thread has its own signal mask. A new thread inherits the
30 calling thread's signal mask and priority; however, pending signals are not
31 inherited. Signals pending for a new thread will be empty.
34 If the value of the argument \fIset\fR is not \fINULL,\fR \fIset\fR points to
35 a set of signals that can modify the currently blocked set. If the value of
36 \fIset\fR is \fINULL\fR, the value of \fIhow\fR is insignificant and the
37 thread's signal mask is unmodified; thus, \fBthr_sigsetmask()\fR can be used to
38 inquire about the currently blocked signals.
41 The value of the argument \fIhow\fR specifies the method in which the set is
42 changed and takes one of the following values:
49 \fIset\fR corresponds to a set of signals to block. They are added to the
56 \fB\fBSIG_UNBLOCK\fR\fR
59 \fIset\fR corresponds to a set of signals to unblock. These signals are deleted
60 from the current signal mask.
66 \fB\fBSIG_SETMASK\fR\fR
69 \fIset\fR corresponds to the new signal mask. The current signal mask is
70 replaced by \fIset\fR.
75 If the value of \fIoset\fR is not \fINULL\fR, it points to the location where
76 the previous signal mask is stored.
79 Upon successful completion, the \fBthr_sigsetmask()\fR function returns
80 \fB0\fR. Otherwise, it returns a non-zero value.
83 The \fBthr_sigsetmask()\fR function will fail if:
90 The value of \fIhow\fR is not defined and \fIoset\fR is \fINULL.\fR
95 \fBExample 1 \fRCreate a default thread that can serve as a signal
96 catcher/handler with its own signal mask.
99 The following example shows how to create a default thread that can serve as a
100 signal catcher/handler with its own signal mask. \fBnew\fR will have a
101 different value from the creator's signal mask.
105 As POSIX threads and Solaris threads are fully compatible even within the same
106 process, this example uses \fBpthread_create\fR(3C) if you execute \fBa.out
107 0\fR, or \fBthr_create\fR(3C) if you execute \fBa.out 1\fR.
117 The \fBsigemptyset\fR(3C) function initializes a null signal set, \fBnew\fR.
118 The \fBsigaddset\fR(3C) function packs the signal, \fBSIGINT\fR, into that new
125 Either \fBpthread_sigmask()\fR or \fBthr_sigsetmask()\fR is used to mask the
126 signal, \fBSIGINT\fR (CTRL-C), from the calling thread, which is \fBmain()\fR.
127 The signal is masked to guarantee that only the new thread will receive this
134 \fBpthread_create()\fR or \fBthr_create()\fR creates the signal-handling
141 Using \fBpthread_join\fR(3C) or \fBthr_join\fR(3C), \fBmain()\fR then waits for
142 the termination of that signal-handling thread, whose \fBID\fR number is
143 \fBuser_threadID\fR. Then \fBmain()\fR will \fBsleep\fR(3C) for 2 seconds,
144 after which the program terminates.
150 The signal-handling thread, \fBhandler\fR:
155 Assigns the handler \fBinterrupt()\fR to handle the signal \fBSIGINT\fR by the
156 call to \fBsigaction\fR(2).
162 Resets its own signal set to \fInot block\fR the signal, \fBSIGINT\fR.
168 Sleeps for 8 seconds to allow time for the user to deliver the signal
169 \fBSIGINT\fR by pressing the \fBCTRL-C.\fR
179 thread_t user_threadID;
181 void *handler(\|), interrupt(\|);
184 main( int argc, char *argv[\|] ){
188 sigaddset(&new, SIGINT);
191 case '0': /* POSIX */
192 pthread_sigmask(SIG_BLOCK, &new, NULL);
193 pthread_create(&user_threadID, NULL, handler, argv[1]);
194 pthread_join(user_threadID, NULL);
197 case '1': /* Solaris */
198 thr_sigsetmask(SIG_BLOCK, &new, NULL);
199 thr_create(NULL, 0, handler, argv[1], 0, &user_threadID);
200 thr_join(user_threadID, NULL, NULL);
204 printf("thread handler, # %d, has exited\en",user_threadID);
206 printf("main thread, # %d is done\en", thr_self(\|));
210 struct sigaction act;
215 act.sa_handler = interrupt;
216 sigaction(SIGINT, &act, NULL);
218 case '0': /* POSIX */
219 pthread_sigmask(SIG_UNBLOCK, &new, NULL);
221 case '1': /* Solaris */
222 thr_sigsetmask(SIG_UNBLOCK, &new, NULL);
225 printf("\en Press CTRL-C to deliver SIGINT signal to the process\en");
226 sleep(8); /* give user time to hit CTRL-C */
233 printf("thread %d caught signal %d\en", thr_self(\|), sig);
236 void test_argv(char argv1[\|]) {
238 printf("use 0 as arg1 to use thr_create(\|);\en \e
239 or use 1 as arg1 to use pthread_create(\|)\en");
248 In the last example, the \fBhandler\fR thread served as a signal-handler while
249 also taking care of activity of its own (in this case, sleeping, although it
250 could have been some other activity). A thread could be completely dedicated to
251 signal-handling simply by waiting for the delivery of a selected signal by
252 blocking with \fBsigwait\fR(2). The two subroutines in the previous example,
253 \fBhandler()\fR and \fBinterrupt()\fR, could have been replaced with the
260 handler(void *ignore)
262 printf("thread %d waiting for you to press the CTRL-C keys\en",
264 sigwait(&new, &signal);
265 printf("thread %d has received the signal %d \en", thr_self(\|), signal);
267 /*pthread_create(\|) and thr_create(\|) would use NULL instead of
268 argv[1] for the arg passed to handler(\|) */
274 In this routine, one thread is dedicated to catching and handling the signal
275 specified by the set \fBnew\fR, which allows \fBmain()\fR and all of its other
276 sub-threads, created \fIafter\fR \fBpthread_sigmask()\fR or
277 \fBthr_sigsetmask()\fR masked that signal, to continue uninterrupted. Any use
278 of \fBsigwait\fR(2) should be such that all threads block the signals passed
279 to \fBsigwait\fR(2) at all times. Only the thread that calls \fBsigwait()\fR
280 will get the signals. The call to \fBsigwait\fR(2) takes two arguments.
284 For this type of background dedicated signal-handling routine, a Solaris daemon
285 thread can be used by passing the argument \fBTHR_DAEMON\fR to
290 See \fBattributes\fR(5) for descriptions of the following attributes:
298 ATTRIBUTE TYPE ATTRIBUTE VALUE
300 MT-Level MT-Safe and Async-Signal-Safe
305 \fBsigaction\fR(2), \fBsigprocmask\fR(2), \fBsigwait\fR(2),
306 \fBcond_wait\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C),
307 \fBpthread_join\fR(3C), \fBpthread_self\fR(3C), \fBsigaddset\fR(3C),
308 \fBsigemptyset\fR(3C), \fBsigsetops\fR(3C), \fBsleep\fR(3C),
309 \fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5)
312 It is not possible to block signals that cannot be caught or ignored (see
313 \fBsigaction\fR(2)). It is also not possible to block or unblock
314 \fBSIGCANCEL\fR, as \fBSIGCANCEL\fR is reserved for the implementation of POSIX
315 thread cancellation (see \fBpthread_cancel\fR(3C) and \fBcancellation\fR(5)).
316 This restriction is quietly enforced by the standard C library.
319 Using \fBsigwait\fR(2) in a dedicated thread allows asynchronously generated
320 signals to be managed synchronously; however, \fBsigwait\fR(2) should never be
321 used to manage synchronously generated signals.
324 Synchronously generated signals are exceptions that are generated by a thread
325 and are directed at the thread causing the exception. Since \fBsigwait()\fR
326 blocks waiting for signals, the blocking thread cannot receive a synchronously
330 Calling the \fBsigprocmask\fR(2) function will be the same as if
331 \fBthr_sigsetmask()\fR or \fBpthread_sigmask()\fR has been called. POSIX leaves
332 the semantics of the call to \fBsigprocmask\fR(2) unspecified in a
333 multi-threaded process, so programs that care about POSIX portability should
334 not depend on this semantic.
337 If a signal is delivered while a thread is waiting on a condition variable,
338 the \fBcond_wait\fR(3C) function will be interrupted and the handler will be
339 executed. The state of the lock protecting the condition variable is undefined
340 while the thread is executing the signal handler.
343 Signals that are generated synchronously should not be masked. If such a signal
344 is blocked and delivered, the receiving process is killed.