NAME

sigwait − wait until a signal is posted

SYNOPSIS

#include <signal.h>

int sigwait(sigset_t ∗set);

POSIX

cc [ flag... ] file... −D_POSIX_PTHREAD_SEMANTICS [ library... ]

#include <signal.h>

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

DESCRIPTION

The sigwait() function selects a signal in set that is pending on the calling thread (see thr_create(3T)) or LWP.  If no signal in set is pending, then sigwait() blocks until a signal in set becomes pending.  The selected signal is cleared from the set of signals pending on the calling thread or LWP and the number of the signal is returned, or in the POSIX version (see standards(5)) placed in sig. The selection of a signal in set is independent of the signal mask of the calling thread or LWP.  This means a thread or LWP can synchronously wait for signals that are being blocked by the signal mask of the calling thread or LWP.  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 sigwait() is called on an ignored signal, then the occurrence of the signal will be ignored, unless sigaction() changes the disposition.  If more than one thread or LWP waits for the same signal, only one is unblocked when the signal arrives. 

RETURN VALUES

Upon successful completion, sigwait() returns a signal number.  Otherwise, it returns a value of −1 and sets errno to indicate an error.  Upon successful completion, the POSIX version of sigwait() returns zero and stores the received signal number at the location pointed to by sig. Otherwise, it returns the error number.

ERRORS

If any of the following conditions are detected, sigwait() fails.  The Solaris version returns −1 and sets errno.  The POSIX version returns one of the following errors:

EINVAL set contains an unsupported signal number. 

EFAULT set points to an invalid address. 

EXAMPLES

The following sample C code creates a thread to handle the receipt of a signal. More specifically, it catches the asynchronously generated signal, SIGINT.

/∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗
∗
∗ compile with −D_POSIX_PTHREAD_SEMANTICS switch;
∗ required by sigwait()
∗
∗ 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_tsignalSet;
 void ∗
main(void)
{
pthread_tt;
pthread_tt2;
pthread_tt3;
 thr_setconcurrency(3);
sigfillset ( &signalSet );
/∗
∗ Block signals in initial thread. New threads will
∗ inherit this signal mask.
∗/
pthread_sigmask ( SIG_BLOCK, &signalSet, NULL );
 printf("Creating threads\n");
 /∗ POSIX thread create arguments:
∗ thr_id, attr, strt_func, arg
∗/
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");
 thr_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());
thr_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());
thr_exit((void ∗)0);
}
 void ∗
sigint(void ∗arg)
{
intsig;
interr;
 printf("thread sigint [tid: %d] awaiting SIGINT\n",
pthread_self());
 /∗ use POSIX sigwait() -- 2 args
∗ signal set, signum
∗/
 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());

thr_exit((void ∗)0);
}

SEE ALSO

sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2), thr_create(3T), thr_sigsetmask(3T), signal(5), standards(5)

NOTES

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. 

In Solaris 2.4 and earlier releases, the call to sigwait() from a multi-threaded process overrode the signal’s ignore disposition; even if a signal’s disposition was SIG_IGN, a call to sigwait() resulted in catching the signal, if generated.  This is unspecified behavior from the standpoint of the POSIX 1003.1c spec. 

In Solaris 2.5, the behavior of sigwait() was corrected, so that it does not override the signal’s ignore disposition.  This change can cause applications that rely on the old behavior to break.  Applications should employ sigwait() as follows: Install a dummy signal handler, thereby changing the disposition from SIG_IGN to having a handler.  Then, any calls to sigwait() for this signal would catch it upon generation. 

Solaris 2.4 and earlier releases provided a sigwait() facility as specified in POSIX.1c Draft 6.  The final POSIX.1c standard changed the interface as described above.  Support for the Draft 6 interface is provided for compatibility only and may not be supported in future releases.  New applications and libraries should use the POSIX standard interface. 

SunOS 5.6  —  Last change: 24 Jan 1997