sigprocmask()

Updated: April 19, 2023

Modify or examine a thread's signal-blocked mask

Synopsis:

#include <signal.h>

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

Arguments:

how
The manner in which you want to change the set; one of:
  • SIG_BLOCK — add the signals pointed to by set to the thread mask.
  • SIG_UNBLOCK — remove the signals pointed to by set from the thread mask.
  • SIG_SETMASK — set the thread mask to be the signals pointed to by set.
set
NULL, or a pointer to a sigset_t object that defines the signals that you want to change in the thread's signal mask. If this argument is NULL, the how argument is ignored.
oset
NULL, or a pointer to a sigset_t object that the function sets to indicate the thread's current signal mask.

You can use various combinations of set and oset to query or change (or both) the signal-blocked mask for a signal.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The sigprocmask() function is used to examine or change (or both) the signal mask for the calling thread. If the value of set isn't NULL, it points to a set of signals to be used to change the currently blocked set.

If a signal occurs on a signal that's masked, it becomes pending, but doesn't affect the execution of the process. You can examine pending signals by calling sigpending(). When a pending signal is unmasked, it's acted upon immediately, before this function returns.

When a signal handler is invoked, the signal responsible is automatically masked before its handler is called. If the handler returns normally, the operating system restores the signal mask present just before the handler was called as an atomic operation. Changes made using sigprocmask() in the handler are undone.

The sigaction() function lets you specify any mask that's applied before a handler is invoked. This can simplify multiple signal handler design.

Note: To maintain code portability, use pthread_sigmask() in a multithreaded application.

The signals SIGSEGV, SIGBUS, SIGILL, and SIGFPE are used by the kernel to indicate to a process that a fault has occurred, and by default will terminate the process. Any such signal delivered by the kernel is a synchronous signal. This means that blocking it does not prevent process termination when the fault is delivered, and any installed signal handlers are skipped. Conversely, if any of these signals is delivered from another user-mode process, via kill(), raise(), pthread_kill(), sigqueue() or SignalKill(), it is an asynchronous signal and is subjected to blocking.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EAGAIN
Insufficient system resources are available to mask the signals.
EFAULT
A fault occurred trying to access the buffers provided.
EINVAL
The value of how is invalid, or you tried to set SIGKILL or SIGSTOP to something other than SIG_DFL.

Examples:

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

int main( void )
  {
    sigset_t set, oset, pset;

    sigemptyset( &set );
    sigaddset( &set, SIGINT );
    sigprocmask( SIG_BLOCK, &set, &oset );
    printf( "Old set was %8.8ld.\n", oset );

    sigpending( &pset );
    printf( "Pending set is %8.8ld.\n", pset );

    kill( getpid(), SIGINT );

    sigpending( &pset );
    printf( "Pending set is %8.8ld.\n", pset );

    sigprocmask( SIG_UNBLOCK, &set, &oset );

    /* The program terminates with a SIGINT */
    return( EXIT_SUCCESS );
  }

Classification:

POSIX 1003.1 CX

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes