Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
System Callssigwait(2)


NAME

 sigwait - wait until a signal is posted

SYNOPSIS

Default

 
 
#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(3THR) and pthread_create(3THR).) 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 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. 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 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 waits for the same signal, only one is unblocked when the signal arrives.

RETURN VALUES

 

Upon successful completion, the default version of sigwait() returns a signal number; the POSIX version returns 0 and stores the received signal number at the location pointed to by sig. Otherwise, -1 is returned and errno is set to indicate an 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 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());
    pthread_exit((void *)0);
}

ATTRIBUTES

 

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
MT-LevelAsync-Signal-Safe

SEE ALSO

 

sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2), pthread_create(3THR), pthread_sigmask(3THR), signal(3HEAD), thr_create(3THR), thr_sigsetmask(3THR), 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.

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.9Go To TopLast Changed 23 Jul 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.