sigprocmask()--Examine and Change Blocked Signals

#include <signal.h>

int sigprocmask( int how, const sigset_t *set,
                 sigset_t *oset );

The sigprocmask() function examines, or changes, or both examines and changes the signal mask of the calling thread.

The signals SIGKILL or SIGSTOP cannot be blocked. Any attempt to use sigprocmask() to block these signals is simply ignored, and no error is returned.

SIGFPE, SIGILL, and SIGSEGV signals that are not artificially generated by kill() or raise() (that is, were generated by the system as a result of a hardware or software exception) are not blocked.

If there are any pending unblocked signals after sigprocmask() has changed the signal mask, at least one of those signals is delivered to the thread before sigprocmask() returns.

If sigprocmask() fails, the process's signal mask is not changed.

Parameters

how

(Input) The way in which the signal set is changed.

*set

(Input) A pointer to a set of signals to be used to change the currently blocked set. May be NULL.

*oset

(Output) A pointer to the space where the previous signal mask is stored. May be NULL.

The possible values for how, which are defined in the <sys/signal.h> header file, are as follows:

SIG_BLOCK

Indicates that the set of signals given by set should be blocked, in addition to the set currently being blocked.

SIG_UNBLOCK

Indicates that the set of signals given by set should not be blocked. These signals are removed from the current set of signals being blocked.

SIG_SETMASK

Indicates that the set of signals given by set should replace the old set of signals being blocked.

The set parameter points to a signal set giving the new signals that should be blocked or unblocked (depending on the value of how), or it points to the new signal mask if the value of how was SIG_SETMASK. Signal sets are described in sigemptyset()--Initialize and Empty Signal Set. If set is a NULL pointer, the set of blocked signals is not changed. If set is NULL, the value of howis ignored.

The signal set manipulation functions (sigemptyset(), sigfillset(), sigaddset(), and sigdelset()) must be used to establish the new signal set pointed to by set.

sigprocmask() determines the current signal set and returns this information in *oset. If set is NULL, oset returns the current set of signals being blocked. When set is not NULL, the set of signals pointed to by oset is the previous set.

Return Value

0

sigprocmask() was successful.

-1

sigprocmask() was not successful. The errno variable is set to indicate the error.

Error Conditions

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

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

One of the following has occurred:

• The value of how is not equal to one of the defined values.

• The signal set pointed to by set 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.

Usage Notes

1. When the sigprocmask function is used to change the signal mask of the calling process, it enables the 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, sigprocmask() is not successful, and an [ENOTSIGINIT] error is returned.

2. Typically, sigprocmask(SIG_BLOCK, ...) is used to block signals during a critical section of code. At the end of the critical section of code, sigprocmask(SIG_SETMASK, ...) is used to restore the mask to the previous value returned by sigprocmask(SIG_BLOCK, ...).

Related Information

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

• sigaction()--Examine and Change Signal Action

• Qp0sDisableSignals()--Disable Process for Signals

• Qp0sEnableSignals()--Enable Process for Signals

• 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

• sigsuspend()--Wait for Signal

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

• sigwait()--Synchronously Accept a Signal

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

Example

The following example changes the signal mask:

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

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

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

    time_t start, finish;
    struct sigaction sact;
    sigset_t new_set, old_set;
    double diff;

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

    sigemptyset( &new_set );
    sigaddset( &new_set, SIGALRM );
    sigprocmask( SIG_BLOCK, &new_set, &old_set);

    time( &start );
    printf( "SIGALRM signals blocked at %s\n", ctime(&start) );

    alarm( 1 );     /* SIGALRM will be sent in 1 second */

    do {
         time( &finish );
         diff = difftime( finish, start );
    } while (diff < 10);

    sigprocmask( SIG_SETMASK, &old_set, NULL );
    printf( "SIGALRM signals unblocked at %s\n", ctime(&finish) );

    return( 0 );
}

Output:

    SIGALRM signals blocked at Sun Jan 22 16:53:40 1995
    inside catcher() function
    SIGALRM signals unblocked at Sun Jan 22 16:53:50 1995