: Programming with POSIX Threads

6.6.4 sigwait and sigwaitinfo

6.6.4 sigwait and sigwaitinfo

int sigwait (const sigset_t *set, int *sig);


int sigwaitinfo (const sigset_t *set, siginfo_t *info);

int sigtimedwait (const sigset_t *set, siginfo_t *info, const struct timespec *timeout);


Always use sigwait to work with asynchronous signals within threaded code.

Pthreads adds a function to allow threaded programs to deal with "asynchronous" signals synchronously. That is, instead of allowing a signal to interrupt a thread at some arbitrary point, a thread can choose to receive a signal synchronously. It does this by calling sigwait, or one of sigwait's siblings.

The signals for which you sigwait must be masked in the sigwaiting thread,and should usually be masked in all threads.

The sigwait function takes a signal set as its argument, and returns a signal number when any signal in that set occurs. You can create a thread that waits for some signal, for example, SIGINT, and causes some application activity when it occurs. The non-obvious rule is that the signals for which you wait must be masked before calling sigwait. In fact, you should ideally mask these signals in main, at the start of the program. Because signal masks are inherited by threads you create, all threads will (by default) have the signal masked. This ensures that the signal will never be delivered to any thread except the one that calls sigwait.

Signals are delivered only once. If two threads are blocked in sigwait, only one of them will receive a signal that's sent to the process. This means you can't, for example, have two independent subsystems using sigwait that catch SIGINT. It also means that the signal will not be caught by sigwait in one thread and also delivered to some signal-catching function in another thread. That's not so bad, since you couldn't do that in the old nonthreaded model either only one signal action can be active at a time.

While sigwait, a Pthreads function, reports errors by returning an error number, its siblings, sigwaitinfo and sigtimedwait, were added to POSIX prior to Pthreads, and use the older errno mechanism. This is confusing and awkward, and that is unfortunate. The problem is that they deal with the additional information supplied by the POSIX realtime signals option (<unistd.h> defines the symbol _POSIX_REALTIME_SIGNALS), and the POSIX realtime amendment, POSIX.1b, was completed before the Pthreads amendment.

Both sigwaitinfo and sigtimedwait return the realtime signal information, siginfo_t, for signals received. In addition, sigtimedwait allows the caller to specify that sigtimedwait should return with the error EAGAIN in the event that none of the selected signals is received within the specified interval.

The sigwait.c program creates a "sigwait thread" that handles SIGINT.

23-41 The signal_waiter thread repeatedly calls sigwait, waiting for a SIGINT signal. It counts five occurrences of SIGINT (printing a message each time), and then signals a condition variable on which main is waiting. At that time, main will exit.

61-65 The main program begins by masking SIGINT. Because all threads inherit their initial signal mask from their creator, SIGINT will be masked in all threads. This prevents SIGINT from being delivered at any time except when the signal_ waiter thread is blocked in sigwait and ready to receive the signal.

? sigwait.c

1#include <sys/types.h>
2#include <unistd.h>
3#include <pthread.h>
4#include <signal.h>
5#include "errors.h"

7pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
8pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
9int interrupted = 0;

10sigset_t signal set;
13* Wait for the SIGINT signal. When it has occurred 5 times, set the
14* "interrupted" flag (the main thread's wait predicate) and signal a
15* condition variable. The main thread will exit.
17void *signal_waiter (void *arg)
19int sig_number;
20int signal_count = 0;
21int status;

23while (1) {
24 sigwait (&signal_set, &sig_number);
25 if (sig_number == SIGINT) {
26 printf ("Got SIGINT (%d of 5)n", signal_count+l);
27 if (++signal_count >= 5) {
28 status = pthread_mutex_lock (&mutex);
29 if (status != 0)
30 err_abort (status, "Lock mutex");
31 interrupted = 1;
32 status = pthread_cond_signal (&cond);
33 if (status != 0)
34 err_abort (status, "Signal condition");
35 status = pthread_mutex_unlock (&mutex);
36 if (status != 0)
37 err_abort (status, "Unlock mutex");
38 break;
39 }
42return NULL;
45int main (int argc, char *argv[])
47pthread_t signal_thread_id;
48int status;

51* Start by masking the "interesting" signal, SIGINT in the
52* initial thread. Because all threads inherit the signal mask
53* from their creator, all threads in the process will have
54* SIGINT masked unless one explicitly unmasks it. The
55* semantics of sigwait requires that all threads (including
56* the thread calling sigwait) have the signal masked, for
57* reliable operation. Otherwise, a signal that arrives
58* while the sigwaiter is not blocked in sigwait might be
59* delivered to another thread.
61sigemptyset (&signal_set);
62sigaddset (&signal_set, SIGINT);
63status = pthread_sigmask (SIG_BLOCK, &signal_set, NULL);
64if (status != 0)
65 err_abort (status, "Set signal mask"); 66
68* Create the sigwait thread.
70status = pthread_create (&signal_thread_id, NULL,
71 signal_waiter, NULL);
72if (status != 0)
73 err_abort (status, "Create sigwaiter");
76* Wait for the sigwait thread to receive SIGINT and signal
77* the condition variable.
79status = pthread_mutex_lock (&mutex);
80if (status != 0)
81 err_abort (status, "Lock mutex");
82while (!interrupted) {
83 status = pthread_cond_wait (&cond,&mutex);
84 if (status != 0)
85 err_abort (status, "Wait for interrupt");
87status = pthread_mutex_unlock (&mutex);
88if (status != 0)
89 err_abort (status, "Unlock mutex");
90printf ("Main terminating with SIGINTn");
91return 0;

: 0.125. /Cache: 5 / 0