sigsuspend()--Wait for Signal

#include <signal.h>

int sigsuspend( const sigset_t *sigmask );

The sigsuspend() function replaces the current signal mask of a thread with the signal set given by *sigmask and then suspends processing of the calling process. The thread does not resume running until a signal is delivered whose action is to call a signal-catching function, to end the request, or to terminate the process. (Signal sets are described in more detail in sigemptyset()--Initialize and Empty Signal Set.)

The signal mask indicates a set of signals that should be blocked. Such signals do not "wake up" the suspended function. The signals SIGSTOP and SIGKILL cannot be blocked or ignored; they are delivered to the thread regardless of what the sigmask argument specifies.

If an incoming unblocked signal has an action of end the request of terminate the process, sigsuspend() never returns to the caller. If an incoming signal is handled by a signal-catching function, sigsuspend() returns after the signal-catching function returns. In this case, the signal mask of the thread is restored to whatever it was before sigsuspend() was called.

Parameters

*sigmask

(Input) A pointer to a set of signals to be used to replace the current signal mask of the process.

Return Value

-1

sigsuspend() was not successful. The errno variable is set to indicate the reason.

There is no return value to indicate successful completion.

Error Conditions

If sigsuspend() returns, errno indicates the following:

[EINTR]

Interrupted function call.

A signal was received and handled by a signal-catching function that returned.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

The signal set pointed to by sigmask contains a signal that is not within the valid range or a signal that is not supported.

[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.

[EWOULDBLOCK]

Operation would have caused the process to be suspended.

The current thread state would prevent the signal function from completing.

Usage Notes

The sigsuspend 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, sigsuspend() is not successful, and an [ENOTSIGINIT] error is returned.

Related Information

• The <signal.h> file (see Header Files for UNIX-Type Functions)

• alarm()--Set Schedule for Alarm Signal

• pause()--Suspend Process Until Signal Received

• Qp0sDisableSignals()--Disable Process for Signals

• Qp0sEnableSignals()--Enable Process for Signals

• sigaction()--Examine and Change Signal Action

• sigaddset()--Add Signal to Signal Set

• sigdelset()--Delete Signal from Signal Set

• sigemptyset()--Initialize and Empty Signal Set

• sigfillset()--Initialize and Fill Signal Set

• sigismember()--Test for Signal in Signal Set

• sigpending()--Examine Pending Signals

• sigprocmask()--Examine and Change Blocked Signals

• sigtimedwait()--Synchronously Accept a Signal for Interval of Time

• sigwait()--Synchronously Accept a Signal

• sigwaitinfo()--Synchronously Accept a Signal and Signal Data

• sleep()--Suspend Processing for Interval of Time

Example

The following example replaces the signal mask and then suspends processing:

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

void catcher( int sig ) {
    printf( "inside catcher() function\n" );
}

void timestamp( char *str ) {

    time_t t;

    time( &t );
    printf( "%s the time is %s\n", str, ctime(&t) );
}

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

    struct sigaction sigact;
    sigset_t block_set;

    sigfillset( &block_set );
    sigdelset( &block_set, SIGALRM );

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

    timestamp( "before sigsuspend()" );
    alarm( 10 );
    sigsuspend( &block_set );
    timestamp( "after sigsuspend()" );

    return( 0 );
}

Output:

    before sigsuspend() the time is Sun Jan 22 17:11:41 1995
    inside catcher() function
    after sigsuspend() the time is Sun Jan 22 17:11:51 1995