| blob | 9dd4ff156e1bee5c230d0083816c6b63a6a41612 |
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 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1995 IEEE. All Rights Reserved.
45 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
46 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
47 .\"
48 .TH THR_SIGSETMASK 3C "Mar 13, 2016"
49 .SH NAME
50 thr_sigsetmask \- change or examine calling thread's signal mask
51 .SH SYNOPSIS
52 .LP
53 .nf
54 cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
55 #include <thread.h>
56 #include <signal.h>
58 \fBint\fR \fBthr_sigsetmask\fR(\fBint\fR \fIhow\fR, \fBconst sigset_t *\fR\fIset\fR, \fBsigset_t *\fR\fIoset\fR);
59 .fi
61 .SH DESCRIPTION
62 .LP
63 The \fBthr_sigsetmask()\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
70 a 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, \fBthr_sigsetmask()\fR can be used to
73 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 \fIset\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 .LP
114 Upon successful completion, the \fBthr_sigsetmask()\fR function returns
115 \fB0\fR. Otherwise, it returns a non-zero value.
116 .SH ERRORS
117 .LP
118 The \fBthr_sigsetmask()\fR function will fail if:
119 .sp
120 .ne 2
121 .na
122 \fB\fBEINVAL\fR\fR
123 .ad
124 .RS 10n
125 The value of \fIhow\fR is not defined and \fIoset\fR is \fINULL.\fR
126 .RE
128 .SH EXAMPLES
129 .LP
130 \fBExample 1 \fRCreate a default thread that can serve as a signal
131 catcher/handler with its own signal mask.
132 .sp
133 .LP
134 The following example shows how to create a default thread that can serve as a
135 signal catcher/handler with its own signal mask. \fBnew\fR will have a
136 different value from the creator's signal mask.
138 .sp
139 .LP
140 As POSIX threads and Solaris threads are fully compatible even within the same
141 process, this example uses \fBpthread_create\fR(3C) if you execute \fBa.out
142 0\fR, or \fBthr_create\fR(3C) if you execute \fBa.out 1\fR.
144 .sp
145 .LP
146 In this example:
148 .RS +4
149 .TP
150 .ie t \(bu
151 .el o
152 The \fBsigemptyset\fR(3C) function initializes a null signal set, \fBnew\fR.
153 The \fBsigaddset\fR(3C) function packs the signal, \fBSIGINT\fR, into that new
154 set.
155 .RE
156 .RS +4
157 .TP
158 .ie t \(bu
159 .el o
160 Either \fBpthread_sigmask()\fR or \fBthr_sigsetmask()\fR is used to mask the
161 signal, \fBSIGINT\fR (CTRL-C), from the calling thread, which is \fBmain()\fR.
162 The signal is masked to guarantee that only the new thread will receive this
163 signal.
164 .RE
165 .RS +4
166 .TP
167 .ie t \(bu
168 .el o
169 \fBpthread_create()\fR or \fBthr_create()\fR creates the signal-handling
170 thread.
171 .RE
172 .RS +4
173 .TP
174 .ie t \(bu
175 .el o
176 Using \fBpthread_join\fR(3C) or \fBthr_join\fR(3C), \fBmain()\fR then waits for
177 the termination of that signal-handling thread, whose \fBID\fR number is
178 \fBuser_threadID\fR. Then \fBmain()\fR will \fBsleep\fR(3C) for 2 seconds,
179 after which the program terminates.
180 .RE
181 .RS +4
182 .TP
183 .ie t \(bu
184 .el o
185 The signal-handling thread, \fBhandler\fR:
186 .RS +4
187 .TP
188 .ie t \(bu
189 .el o
190 Assigns the handler \fBinterrupt()\fR to handle the signal \fBSIGINT\fR by the
191 call to \fBsigaction\fR(2).
192 .RE
193 .RS +4
194 .TP
195 .ie t \(bu
196 .el o
197 Resets its own signal set to \fInot block\fR the signal, \fBSIGINT\fR.
198 .RE
199 .RS +4
200 .TP
201 .ie t \(bu
202 .el o
203 Sleeps for 8 seconds to allow time for the user to deliver the signal
204 \fBSIGINT\fR by pressing the \fBCTRL-C.\fR
205 .RE
206 .RE
207 .sp
208 .in +2
209 .nf
210 /* cc thisfile.c */
211 #include <pthread.h>
212 #include <thread.h>
214 thread_t user_threadID;
215 sigset_t new;
216 void *handler(\|), interrupt(\|);
218 int
219 main( int argc, char *argv[\|] ){
220 test_argv(argv[1]);
222 sigemptyset(&new);
223 sigaddset(&new, SIGINT);
224 switch(*argv[1]) {
226 case '0': /* POSIX */
227 pthread_sigmask(SIG_BLOCK, &new, NULL);
228 pthread_create(&user_threadID, NULL, handler, argv[1]);
229 pthread_join(user_threadID, NULL);
230 break;
232 case '1': /* Solaris */
233 thr_sigsetmask(SIG_BLOCK, &new, NULL);
234 thr_create(NULL, 0, handler, argv[1], 0, &user_threadID);
235 thr_join(user_threadID, NULL, NULL);
236 break;
237 } /* switch */
239 printf("thread handler, # %d, has exited\en",user_threadID);
240 sleep(2);
241 printf("main thread, # %d is done\en", thr_self(\|));
242 return (0)
243 } /* end main */
245 struct sigaction act;
247 void *
248 handler(char *argv1)
249 {
250 act.sa_handler = interrupt;
251 sigaction(SIGINT, &act, NULL);
252 switch(*argv1){
253 case '0': /* POSIX */
254 pthread_sigmask(SIG_UNBLOCK, &new, NULL);
255 break;
256 case '1': /* Solaris */
257 thr_sigsetmask(SIG_UNBLOCK, &new, NULL);
258 break;
259 }
260 printf("\en Press CTRL-C to deliver SIGINT signal to the process\en");
261 sleep(8); /* give user time to hit CTRL-C */
262 return (NULL)
263 }
265 void
266 interrupt(int sig)
267 {
268 printf("thread %d caught signal %d\en", thr_self(\|), sig);
269 }
271 void test_argv(char argv1[\|]) {
272 if(argv1 == NULL) {
273 printf("use 0 as arg1 to use thr_create(\|);\en \e
274 or use 1 as arg1 to use pthread_create(\|)\en");
275 exit(NULL);
276 }
277 }
278 .fi
279 .in -2
281 .sp
282 .LP
283 In the last example, the \fBhandler\fR thread served as a signal-handler while
284 also taking care of activity of its own (in this case, sleeping, although it
285 could have been some other activity). A thread could be completely dedicated to
286 signal-handling simply by waiting for the delivery of a selected signal by
287 blocking with \fBsigwait\fR(2). The two subroutines in the previous example,
288 \fBhandler()\fR and \fBinterrupt()\fR, could have been replaced with the
289 following routine:
291 .sp
292 .in +2
293 .nf
294 void *
295 handler(void *ignore)
296 { int signal;
297 printf("thread %d waiting for you to press the CTRL-C keys\en",
298 thr_self(\|));
299 sigwait(&new, &signal);
300 printf("thread %d has received the signal %d \en", thr_self(\|), signal);
301 }
302 /*pthread_create(\|) and thr_create(\|) would use NULL instead of
303 argv[1] for the arg passed to handler(\|) */
304 .fi
305 .in -2
307 .sp
308 .LP
309 In this routine, one thread is dedicated to catching and handling the signal
310 specified by the set \fBnew\fR, which allows \fBmain()\fR and all of its other
311 sub-threads, created \fIafter\fR \fBpthread_sigmask()\fR or
312 \fBthr_sigsetmask()\fR masked that signal, to continue uninterrupted. Any use
313 of \fBsigwait\fR(2) should be such that all threads block the signals passed
314 to \fBsigwait\fR(2) at all times. Only the thread that calls \fBsigwait()\fR
315 will get the signals. The call to \fBsigwait\fR(2) takes two arguments.
317 .sp
318 .LP
319 For this type of background dedicated signal-handling routine, a Solaris daemon
320 thread can be used by passing the argument \fBTHR_DAEMON\fR to
321 \fBthr_create()\fR.
323 .SH ATTRIBUTES
324 .LP
325 See \fBattributes\fR(5) for descriptions of the following attributes:
326 .sp
328 .sp
329 .TS
330 box;
331 c | c
332 l | l .
333 ATTRIBUTE TYPE ATTRIBUTE VALUE
334 _
335 MT-Level MT-Safe and Async-Signal-Safe
336 .TE
338 .SH SEE ALSO
339 .LP
340 \fBsigaction\fR(2), \fBsigprocmask\fR(2), \fBsigwait\fR(2),
341 \fBcond_wait\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C),
342 \fBpthread_join\fR(3C), \fBpthread_self\fR(3C), \fBsigaddset\fR(3C),
343 \fBsigemptyset\fR(3C), \fBsigsetops\fR(3C), \fBsleep\fR(3C),
344 \fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5)
345 .SH NOTES
346 .LP
347 It is not possible to block signals that cannot be caught or ignored (see
348 \fBsigaction\fR(2)). It is also not possible to block or unblock
349 \fBSIGCANCEL\fR, as \fBSIGCANCEL\fR is reserved for the implementation of POSIX
350 thread cancellation (see \fBpthread_cancel\fR(3C) and \fBcancellation\fR(5)).
351 This restriction is quietly enforced by the standard C library.
352 .sp
353 .LP
354 Using \fBsigwait\fR(2) in a dedicated thread allows asynchronously generated
355 signals to be managed synchronously; however, \fBsigwait\fR(2) should never be
356 used to manage synchronously generated signals.
357 .sp
358 .LP
359 Synchronously generated signals are exceptions that are generated by a thread
360 and are directed at the thread causing the exception. Since \fBsigwait()\fR
361 blocks waiting for signals, the blocking thread cannot receive a synchronously
362 generated signal.
363 .sp
364 .LP
365 Calling the \fBsigprocmask\fR(2) function will be the same as if
366 \fBthr_sigsetmask()\fR or \fBpthread_sigmask()\fR has been called. POSIX leaves
367 the semantics of the call to \fBsigprocmask\fR(2) unspecified in a
368 multi-threaded process, so programs that care about POSIX portability should
369 not depend on this semantic.
370 .sp
371 .LP
372 If a signal is delivered while a thread is waiting on a condition variable,
373 the \fBcond_wait\fR(3C) function will be interrupted and the handler will be
374 executed. The state of the lock protecting the condition variable is undefined
375 while the thread is executing the signal handler.
376 .sp
377 .LP
378 Signals that are generated synchronously should not be masked. If such a signal
379 is blocked and delivered, the receiving process is killed.