SIGWAIT(2) System Calls SIGWAIT(2)
NAME
sigwait - wait until a signal is posted
SYNOPSIS
#include <signal.h>
int sigwait(
sigset_t *set);
Standard conforming
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. 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 returned, or in the standard-conforming version (see
standards(7))
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.
RETURN VALUES
Upon successful completion, the default version of
sigwait() returns a
signal number; the standard-conforming version returns
0 and stores the
received signal number at the location pointed to by
sig. Otherwise, the
default version returns -1 and sets errno to indicate an error; the
standard-conforming version returns an error number to indicate the
error.
ERRORS
The
sigwait() function will fail if:
EFAULT The
set argument points to an invalid address.
EINTR The wait was interrupted by an unblocked, caught signal.
EINVAL The
set argument contains an unsupported signal number.
EXAMPLES
Example 1: Creating a thread to handle receipt of a signal
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_t signalSet;
void *
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());
/*
/* use standard-conforming 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());
pthread_exit((void *)0);
}
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Interface Stability | Committed |
+--------------------+-------------------+
|MT-Level | Async-Signal-Safe |
+--------------------+-------------------+
|Standard | See
standards(7). |
+--------------------+-------------------+
SEE ALSO
sigaction(2),
sigpending(2),
sigprocmask(2),
sigsuspend(2),
pthread_create(3C),
pthread_kill(3C),
pthread_sigmask(3C),
signal.h(3HEAD),
attributes(7),
standards(7)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.
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 standard-
conforming interface.
April 16, 2009
SIGWAIT(2)