pthread_sigmask() — Examine or change a thread blocked signals format

Standards

Standards / Extensions C or C++ Dependencies
Single UNIX Specification, version 3
 both
z/OS® V1R7 POSIX(ON)

Format

#define _OPEN_THREADS 2
#include <signal.h>

int pthread_sigmask(int option, const sigset_t *__restrict__ new_set, 
                    sigset_t *__restrict__ old_set);

General description

pthread_sigmask() examines, changes, or examines and changes the signal mask of the calling thread. If there is only one thread, it does the same for the calling process.

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

option indicates the way in which the existing set of blocked signals should be changed. The following are the possible values for option, defined in the signal.h header file:
  • SIG_BLOCK – Indicates that the set of signals given by new_set should be blocked, in addition to the set currently being blocked.
  • SIG_UNBLOCK – Indicates that the set of signals given by new_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 new_set should replace the old set of signals being blocked.

new_set points to a signal set giving the new signals that should be blocked or unblocked (depending on the value of option) or it points to the new signal mask if the option was SIG_SETMASK. Signal sets are described in "sigemptyset() — Initialize a Signal Mask to Exclude All Signals" in topic 3.727. If new_set is a NULL pointer, the set of blocked signals is not changed. pthread_sigmask() determines the current set and returns this information in *old_set. If new_set is NULL, the value of option is not significant. The signal set manipulation functions: sigemptyset(), sigfillset(), sigaddset(), and sigdelset() must be used to establish the new signal set pointed to by new_set.

old_set points to a memory location where pthread_sigmask() can store a signal set. If new_set is NULL, old_set returns the current set of signals being blocked. When new_set is not NULL, the set of signals pointed to by old_set is the previous set.

If there are any pending unblocked signals, either at the process level or at the current thread's level after pthread_sigmask() has changed the signal mask, then at least one of those signals is delivered to the thread before pthread_sigmask() returns.

The signals SIGKILL, SIGSTOP, or SIGTRACE cannot be blocked. If you attempt to use pthread_sigmask() to block these signals, the attempt is ignored. pthread_sigmask() does not return an error status.

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

If an artificially raised SIGFPE, SIGILL, or SIGSEGV signal is pending and blocked when an exception causes another SIGFPE, SIGILL, or SIGSEGV signal, both the artificial and exception-caused signals may be delivered to the application.

If pthread_sigmask() fails, the signal mask of the thread is not changed.

Usage Notes®

  1. The use of the SIGTHSTOP and SIGTHCONT signal is not supported with this function.

Returned value

If successful, pthread_sigmask() returns 0. Otherwise, pthread_sigmask() returns one of the following error numbers:
EINVAL
option does not have one of the recognized values.

Related information