1sigwait(2) System Calls sigwait(2)
2
6 sigwait - wait until a signal is posted
7
9 #include <signal.h>
10 int sigwait(sigset_t *set);
12 Standard conforming
15 cc [ flag ... ] file ... -D_POSIX_PTHREAD_SEMANTICS [ library...]
16 #include <signal.h>
17 int sigwait(const sigset_t *set, int *sig);
19
22 The sigwait() function selects a signal in set that is pending on the
23 calling thread. If no signal in set is pending, sigwait() blocks until
24 a signal in set becomes pending. The selected signal is cleared from
25 the set of signals pending on the calling thread and the number of the
26 signal is returned, or in the standard-conforming version (see stan‐
27 dards(5)) placed in sig. The selection of a signal in set is indepen‐
28 dent of the signal mask of the calling thread. This means a thread can
29 synchronously wait for signals that are being blocked by the signal
30 mask of the calling thread . To ensure that only the caller receives
31 the signals defined in set, all threads should have signals in set
32 masked including the calling thread.
33 If more than one thread is using sigwait() to wait for the same signal,
36 no more than one of these threads returns from sigwait() with the sig‐
37 nal number. If more than a single thread is blocked in sigwait() for a
38 signal when that signal is generated for the process, it is unspecified
39 which of the waiting threads returns from sigwait(). If the signal is
40 generated for a specific thread, as by pthread_kill(3C), only that
41 thread returns.
42 Should any of the multiple pending signals in the range SIGRTMIN to
45 SIGRTMAX be selected, it will be the lowest numbered one. The selection
46 order between realtime and non-realtime signals, or between multiple
47 pending non-realtime signals, is unspecified.
48
50 Upon successful completion, the default version of sigwait() returns a
51 signal number; the standard-conforming version returns 0 and stores the
52 received signal number at the location pointed to by sig. Otherwise,
53 the default version returns -1 and sets errno to indicate an error; the
54 standard-conforming version returns an error number to indicate the
55 error.
56
58 The sigwait() function will fail if:
59 EFAULT The set argument points to an invalid address.
61 EINTR The wait was interrupted by an unblocked, caught signal.
64 EINVAL The set argument contains an unsupported signal number.
67
70 Example 1 Creating a thread to handle receipt of a signal
71 The following sample C code creates a thread to handle the receipt of a
74 signal. More specifically, it catches the asynchronously generated sig‐
75 nal, SIGINT.
76 /********************************************************************
79 *
80 * compile with -D_POSIX_PTHREAD_SEMANTICS switch;
81 * required by sigwait()
82 *
83 * sigint thread handles delivery of signal. uses sigwait() to wait
84 * for SIGINT signal.
85 *
86 ********************************************************************/
87 #include <pthread.h>
88 #include <stdlib.h>
89 #include <stdio.h>
90 #include <string.h>
91 #include <unistd.h>
92 #include <signal.h>
93 #include <synch.h>
94 static void *threadTwo(void *);
96 static void *threadThree(void *);
97 static void *sigint(void *);
98 sigset_t signalSet;
100 void *
102 main(void)
103 {
104 pthread_t t;
105 pthread_t t2;
106 pthread_t t3;
107 sigfillset ( &signalSet );
109 /*
110 * Block signals in initial thread. New threads will
111 * inherit this signal mask.
112 */
113 pthread_sigmask ( SIG_BLOCK, &signalSet, NULL );
114 printf("Creating threads\n");
116 pthread_create(&t, NULL, sigint, NULL);
118 pthread_create(&t2, NULL, threadTwo, NULL);
119 pthread_create(&t3, NULL, threadThree, NULL);
120 printf("##################\n");
122 printf("press CTRL-C to deliver SIGINT to sigint thread\n");
123 printf("##################\n");
124 pthread_exit((void *)0);
126 }
127 static void *
128 threadTwo(void *arg)
129 {
130 printf("hello world, from threadTwo [tid: %d]\n",
131 pthread_self());
132 printf("threadTwo [tid: %d] is now complete and exiting\n",
133 pthread_self());
134 pthread_exit((void *)0);
135 }
136 static void *
138 threadThree(void *arg)
139 {
140 printf("hello world, from threadThree [tid: %d]\n",
141 pthread_self());
142 printf("threadThree [tid: %d] is now complete and exiting\n",
143 pthread_self());
144 pthread_exit((void *)0);
145 }
146 void *
148 sigint(void *arg)
149 {
150 int sig;
151 int err;
152 printf("thread sigint [tid: %d] awaiting SIGINT\n",
154 pthread_self());
155 /*
157 /* use standard-conforming sigwait() -- 2 args: signal set, signum
158 */
159 err = sigwait ( &signalSet, &sig );
160 /* test for SIGINT; could catch other signals */
162 if (err || sig != SIGINT)
163 abort();
164 printf("\nSIGINT signal %d caught by sigint thread [tid: %d]\n",
166 sig, pthread_self());
167 pthread_exit((void *)0);
168 }
169
172 See attributes(5) for descriptions of the following attributes:
173 ┌─────────────────────────────┬─────────────────────────────┐
178 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
179 ├─────────────────────────────┼─────────────────────────────┤
180 │Interface Stability │Committed │
181 ├─────────────────────────────┼─────────────────────────────┤
182 │MT-Level │Async-Signal-Safe │
183 ├─────────────────────────────┼─────────────────────────────┤
184 │Standard │See standards(5). │
185 └─────────────────────────────┴─────────────────────────────┘
186
188 sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2),
189 pthread_create(3C), pthread_kill(3C), pthread_sigmask(3C), sig‐
190 nal.h(3HEAD), attributes(5), standards(5)
191
193 The sigwait() function cannot be used to wait for signals that cannot
194 be caught (see sigaction(2)). This restriction is silently imposed by
195 the system.
196 Solaris 2.4 and earlier releases provided a sigwait() facility as spec‐
199 ified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
200 interface as described above. Support for the Draft 6 interface is pro‐
201 vided for compatibility only and may not be supported in future
202 releases. New applications and libraries should use the standard-con‐
203 forming interface.
204SunOS 5.11 16 Apr 2009 sigwait(2)