sigwait()--Synchronously Accept a Signal

 #include <signal.h>

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

The sigwait() function selects a pending signal from set, clears it from the set of pending signals for the thread or process, and returns that signal number in the location that is referenced by sig. If prior to the call to sigwait() there are multiple pending instances of a single signal number, upon successful return the number of remaining signals for that signal number is decremented by one.

If no signal in set is pending at the time of the call, the thread shall be suspended. The thread does not resume until one or more signals in set become pending.

The signals defined by set are required to be blocked at the time of the call to sigwait(); otherwise, sigwait() is not successful, and an [EINVAL] error is returned. The signals SIGKILL or SIGStop cannot be selected. Any attempt to use sigwait() to select these signals is simply ignored, and no error is returned.

The signal action for the signal in set that is returned in the location referenced by sig is not taken.

If more than one thread is using a sigwait function to wait for the same signal, only one of these threads will return from the sigwait function with the signal number. If more than one thread is waiting for the same signal, the first thread to wait on the signal will return from the sigwait function.

Authorities and Locks

None.

Parameters

*set

(Input) A pointer to a signal set to be waited upon.

*sig

(Output) A pointer to the storage location where sigwait() can store the signal number that completed the wait.

Return Value

Error Conditions

If sigwait() is not successful, errno usually indicates the following error. Under some conditions, errno could indicate an error other than that listed here.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

• The signal set pointed to by set contains a signal that is not within the valid range or a signal that is not supported.
• A signal in the signal set pointed to by set contains a signal that is not blocked.

[ENOTSIGINIT]

Process not enabled for signals.

An attempt was made to call a signal function under one of the following conditions:

• The signal function is being called for a process that is not enabled for asynchronous signals.
• The signal function is being called when the system signal controls have not been initialized.

Usage Notes

The sigwait() function enables a process for signals if the process is not already enabled for signals. For details, see Qp0sEnableSignals()--Enable Process for Signals. If the system has not been enabled for signals, sigwait() is not successful, and an [ENOTSIGINIT] error is returned.

Related Information

• The <signal.h> file (see Header Files for UNIX-Type Functions)
  
  
• Qp0sDisableSignals()--Disable Process for Signals
  
  
• Qp0sEnableSignals()--Enable Process for Signals
  
  
• sigaction()--Examine and Change Signal Action
  
  
• sigpending()--Examine Pending Signals
  
  
• sigprocmask()--Examine and Change Blocked Signals
  
  
• sigsuspend()--Wait for Signal
  
  
• sigtimedwait()--Synchronously Accept a Signal for Interval of Time
  
  
• sigwaitinfo()--Synchronously Accept a Signal and Signal Data

Example

See Code disclaimer information for information pertaining to code examples.

The following example suspends processing by using the sigwait() function and determines the current time:

Note: The signal catching function is not called.

#include <signal.h>
#include <unistd.h>
#include <stdio.h>
#include <time.h>

extern int errno;

void catcher( int sig ) {
    printf( "Signal catcher called for signal %d\n", sig );
}

void timestamp( char *str ) {
    time_t t;

    time( T );
    printf( "The time %s is %s\n", str, ctime(T) );
}

int main( int argc, char *argv[] ) {

    struct sigaction sigact;
    sigset_t waitset;
    int sig;
    int result = 0;

    sigemptyset( &sigact.sa_mask );
    sigact.sa_flags = 0;
    sigact.sa_handler = catcher;
    sigaction( SIGALRM, &sigact, NULL );

    sigemptyset( &waitset );
    sigaddset( &waitset, SIGALRM );

    sigprocmask( SIG_BLOCK, &waitset, NULL );

    alarm( 10 );

    timestamp( "before sigwait()" );

    result = sigwait( &waitset, &sig );
    if( result == 0 )
        printf( "sigwait() returned for signal %d\n", sig );
    else {
        printf( "sigwait() returned error number %d\n", errno );
        perror( "sigwait() function failed\n" );
    }

    timestamp( "after sigwait()" );

    return( result );
}

Output:

    The time before sigwait() is Tue Jul 15 11:15:43 1997
    sigwait() returned for signal 14
    The time after sigwait() is Tue Jul 15 11:15:54 1997