sigwait - wait until a signal is posted
#include <signal.h> int sigwait(const sigset_t *set, int *sig);
POSIX.1c Draft 6 cc [ flag ... ] file ... –D__USE_DRAFT6_PROTOTYPES__ [ library...] int sigwait(sigset_t *set);
The sigwait() function selects a signal in set that is pending on the calling thread. If no signal in set is pending, sigwait() blocks until a signal in set becomes pending. The selected signal is cleared from the set of signals pending on the calling thread and the number of the signal is placed in sig. The selection of a signal in set is independent of the signal mask of the calling thread. This means a thread can synchronously wait for signals that are being blocked by the signal mask of the calling thread. To ensure that only the caller receives the signals defined in set, all threads should have signals in set masked including the calling thread.
If more than one thread is using sigwait() to wait for the same signal, no more than one of these threads returns from sigwait() with the signal number. If more than a single thread is blocked in sigwait() for a signal when that signal is generated for the process, it is unspecified which of the waiting threads returns from sigwait(). If the signal is generated for a specific thread, as by pthread_kill(3C), only that thread returns.
Should any of the multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected, it will be the lowest numbered one. The selection order between realtime and non-realtime signals, or between multiple pending non-realtime signals, is unspecified.
Upon successful completion, sigwait() returns 0 and stores the selected signal number at the location pointed to by sig. Otherwise, sigwait() returns an error number to indicate the error; it does not set errno.
The Draft 6 version of sigwait() returns the selected signal number on success. Otherwise, it returns -1 and sets errno to indicate the error.
The sigwait() function will fail if:
The set argument points to an invalid address.
The wait was interrupted by an unblocked, caught signal.
The set argument contains an unsupported signal number.
The following sample C code creates a thread to handle the receipt of a signal. More specifically, it catches the asynchronously generated signal, SIGINT.
/********************************************************************
* sigint thread handles delivery of signal. Uses sigwait( ) to wait
* for SIGINT signal.
********************************************************************/
#include <pthread.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <signal.h>
#include <synch.h>
static void *threadTwo(void *);
static void *threadThree(void *);
static void *sigint(void *);
sigset_t signalSet;
int
main(void)
{
pthread_t t;
pthread_t t2;
pthread_t t3;
sigfillset(&signalSet);
/*
* Block signals in initial thread. New threads will
* inherit this signal mask.
*/
pthread_sigmask(SIG_BLOCK, &signalSet, NULL);
printf("Creating threads\n");
pthread_create(&t, NULL, sigint, NULL);
pthread_create(&t2, NULL, threadTwo, NULL);
pthread_create(&t3, NULL, threadThree, NULL);
printf("##################\n");
printf("press CTRL-C to deliver SIGINT to sigint thread\n");
printf("##################\n");
pthread_exit((void *)0);
}
static void *
threadTwo(void *arg)
{
printf("hello world, from threadTwo [tid: %d]\n",
pthread_self());
printf("threadTwo [tid: %d] is now complete and exiting\n",
pthread_self());
pthread_exit((void *)0);
}
static void *
threadThree(void *arg)
{
printf("hello world, from threadThree [tid: %d]\n",
pthread_self());
printf("threadThree [tid: %d] is now complete and exiting\n",
pthread_self());
pthread_exit((void *)0);
}
void *
sigint(void *arg)
{
int sig;
int err;
printf("thread sigint [tid: %d] awaiting SIGINT\n",
pthread_self());
err = sigwait(&signalSet, &sig);
/* test for SIGINT; could catch other signals */
if (err || sig != SIGINT)
abort();
printf("\nSIGINT signal %d caught by sigint thread [tid: %d]\n",
sig, pthread_self());
pthread_exit((void *)0);
}
See attributes(7) for descriptions of the following attributes:
|
sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2), pthread_create(3C), pthread_kill(3C), pthread_sigmask(3C), signal.h(3HEAD), attributes(7), standards(7)
The sigwait() function cannot be used to wait for signals that cannot be caught (see sigaction(2)). This restriction is silently imposed by the system.
Prior to Oracle Solaris 11.4, the default compilation environment provided a definition of the sigwait() function as specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the interface for sigwait(). To allow applications that were written to use the obsolete Draft-6 interfaces to continue to be compiled and run, the __USE_DRAFT6_PROTOTYPES__ macro must be defined:
cc –D__USE_DRAFT6_PROTOTYPES__ ...
Support for the Draft-6 interfaces is provided for source compatibility only and might not be supported in future releases. Old applications should be converted to use the standard definitions.
Earlier implementations of these interfaces would not wake up on receiving a signal with a disposition of SIG_IGN.