'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SIGWAIT 2 "Apr 16, 2009"
.SH NAME
sigwait \- wait until a signal is posted
.SH SYNOPSIS
.LP
.nf
#include <signal.h>

\fBint\fR \fBsigwait\fR(\fBsigset_t *\fR\fIset\fR);
.fi

.SS "Standard conforming"
.LP
.nf
cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR...]
#include <signal.h>

\fBint\fR \fBsigwait\fR(\fBconst sigset_t *\fR\fIset\fR, \fBint *\fR\fIsig\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsigwait()\fR function selects a signal in \fIset\fR that is pending on
the calling thread. If no signal in \fIset\fR is pending, \fBsigwait()\fR
blocks until a signal in \fIset\fR 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
\fBstandards\fR(5)) placed in \fIsig\fR. The selection of a signal in \fIset\fR
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 \fIset\fR, all threads should have signals in \fIset\fR masked
including the calling thread.
.sp
.LP
If more than one thread is using \fBsigwait()\fR to wait for the same signal,
no more than one of these threads returns from \fBsigwait()\fR with the signal
number. If more than a single thread is blocked in \fBsigwait()\fR for a signal
when that signal is generated for the process, it is unspecified which of the
waiting threads returns from \fBsigwait()\fR. If the signal is generated for a
specific thread, as by \fBpthread_kill\fR(3C), only that thread returns.
.sp
.LP
Should any of the multiple pending signals in the range \fBSIGRTMIN\fR to
\fBSIGRTMAX\fR 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.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the default version of \fBsigwait()\fR returns a
signal number; the standard-conforming version returns \fB0\fR and stores the
received signal number at the location pointed to by \fIsig\fR. 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.
.SH ERRORS
.sp
.LP
The \fBsigwait()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
The \fIset\fR argument points to an invalid address.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
The wait was interrupted by an unblocked, caught signal.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIset\fR argument contains an unsupported signal number.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a thread to handle receipt of a signal
.sp
.LP
The following sample C code creates a thread to handle the receipt of a signal.
More specifically, it catches the asynchronously generated signal,
\fBSIGINT\fR.

.sp
.in +2
.nf
/********************************************************************
*
* 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\en");

    pthread_create(&t, NULL, sigint, NULL);
    pthread_create(&t2, NULL, threadTwo, NULL);
    pthread_create(&t3, NULL, threadThree, NULL);

    printf("##################\en");
    printf("press CTRL-C to deliver SIGINT to sigint thread\en");
    printf("##################\en");

    pthread_exit((void *)0);
}
static void *
threadTwo(void *arg)
{
    printf("hello world, from threadTwo [tid: %d]\en",
                            pthread_self());
    printf("threadTwo [tid: %d] is now complete and exiting\en",
                            pthread_self());
    pthread_exit((void *)0);
}

static void *
threadThree(void *arg)
{
    printf("hello world, from threadThree [tid: %d]\en",
                            pthread_self());
    printf("threadThree [tid: %d] is now complete and exiting\en",
                            pthread_self());
    pthread_exit((void *)0);
}

void *
sigint(void *arg)
{
    int    sig;
    int    err;

    printf("thread sigint [tid: %d] awaiting SIGINT\en",
                            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("\enSIGINT signal %d caught by sigint thread [tid: %d]\en",
                            sig, pthread_self());
    pthread_exit((void *)0);
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Async-Signal-Safe
_
Standard	See \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBsigaction\fR(2), \fBsigpending\fR(2), \fBsigprocmask\fR(2),
\fBsigsuspend\fR(2), \fBpthread_create\fR(3C), \fBpthread_kill\fR(3C),
\fBpthread_sigmask\fR(3C), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5),
\fBstandards\fR(5)
.SH NOTES
.sp
.LP
The \fBsigwait()\fR function cannot be used to wait for signals that cannot be
caught (see \fBsigaction\fR(2)). This restriction is silently imposed by the
system.
.sp
.LP
Solaris 2.4 and earlier releases provided a \fBsigwait()\fR 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.