# pthread_sigmask

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           pthread_sigmask, sigprocmask — examine and change blocked signals
    


## SYNOPSIS



           #include <signal.h>
    
           int pthread_sigmask(int _how_ , const sigset_t *restrict _set_ ,
               sigset_t *restrict _oset_);
           int sigprocmask(int _how_ , const sigset_t *restrict _set_ ,
               sigset_t *restrict _oset_);
    


## DESCRIPTION



           The _pthread_sigmask_() function shall examine or change (or both)
           the calling thread's signal mask, regardless of the number of
           threads in the process. The function shall be equivalent to
           _sigprocmask_(), without the restriction that the call be made in a
           single-threaded process.
    
           In a single-threaded process, the _sigprocmask_() function shall
           examine or change (or both) the signal mask of the calling thread.
    
           If the argument _set_ is not a null pointer, it points to a set of
           signals to be used to change the currently blocked set.
    
           The argument _how_ indicates the way in which the set is changed,
           and the application shall ensure it consists of one of the
           following values:
    
           SIG_BLOCK   The resulting set shall be the union of the current
                       set and the signal set pointed to by _set_.
    
           SIG_SETMASK The resulting set shall be the signal set pointed to
                       by _set_.
    
           SIG_UNBLOCK The resulting set shall be the intersection of the
                       current set and the complement of the signal set
                       pointed to by _set_.
    
           If the argument _oset_ is not a null pointer, the previous mask
           shall be stored in the location pointed to by _oset_.  If _set_ is a
           null pointer, the value of the argument _how_ is not significant and
           the thread's signal mask shall be unchanged; thus the call can be
           used to enquire about currently blocked signals.
    
           If there are any pending unblocked signals after the call to
           _sigprocmask_(), at least one of those signals shall be delivered
           before the call to _sigprocmask_() returns.
    
           It is not possible to block those signals which cannot be ignored.
           This shall be enforced by the system without causing an error to
           be indicated.
    
           If any of the SIGFPE, SIGILL, SIGSEGV, or SIGBUS signals are
           generated while they are blocked, the result is undefined, unless
           the signal was generated by the action of another process, or by
           one of the functions _kill_(), _pthread_kill_(), _raise_(), or
           _sigqueue_().
    
           If _sigprocmask_() fails, the thread's signal mask shall not be
           changed.
    
           The use of the _sigprocmask_() function is unspecified in a multi-
           threaded process.
    


## RETURN VALUE



           Upon successful completion _pthread_sigmask_() shall return 0;
           otherwise, it shall return the corresponding error number.
    
           Upon successful completion, _sigprocmask_() shall return 0;
           otherwise, -1 shall be returned, _errno_ shall be set to indicate
           the error, and the signal mask of the process shall be unchanged.
    


## ERRORS



           The _pthread_sigmask_() and _sigprocmask_() functions shall fail if:
    
           **EINVAL** The value of the _how_ argument is not equal to one of the
                  defined values.
    
           The _pthread_sigmask_() function shall not return an error code of
           **[EINTR]**.
    
           _The following sections are informative._
    


## EXAMPLES



       **Signaling in a Multi-Threaded Process**
           This example shows the use of _pthread_sigmask_() in order to deal
           with signals in a multi-threaded process. It provides a fairly
           general framework that could be easily adapted/extended.
    
               #include <stdio.h>
               #include <stdlib.h>
               #include <pthread.h>
               #include <signal.h>
               #include <string.h>
               #include <errno.h>
               ...
    
               static sigset_t   signal_mask;  /* signals to block         */
    
               int main (int argc, char *argv[])
               {
                   pthread_t  sig_thr_id;      /* signal handler thread ID */
                   int        rc;              /* return code              */
    
                   sigemptyset (&signal_mask);
                   sigaddset (&signal_mask, SIGINT);
                   sigaddset (&signal_mask, SIGTERM);
                   rc = pthread_sigmask (SIG_BLOCK, &signal_mask, NULL);
                   if (rc != 0) {
                       /* handle error */
                       ...
                   }
                   /* any newly created threads inherit the signal mask */
    
                   rc = pthread_create (&sig_thr_id, NULL, signal_thread, NULL);
                   if (rc != 0) {
                       /* handle error */
                       ...
                   }
    
                   /* APPLICATION CODE */
                   ...
               }
    
               void *signal_thread (void *arg)
               {
                   int       sig_caught;    /* signal caught       */
                   int       rc;            /* returned code       */
    
                   rc = sigwait (&signal_mask, &sig_caught);
                   if (rc != 0) {
                       /* handle error */
                   }
                   switch (sig_caught)
                   {
                   case SIGINT:     /* process SIGINT  */
                       ...
                       break;
                   case SIGTERM:    /* process SIGTERM */
                       ...
                       break;
                   default:         /* should normally not happen */
                       fprintf (stderr, "\nUnexpected signal %d\n", sig_caught);
                       break;
                   }
               }
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           When a thread's signal mask is changed in a signal-catching
           function that is installed by _sigaction_(), the restoration of the
           signal mask on return from the signal-catching function overrides
           that change (see _sigaction_()).  If the signal-catching function
           was installed with _signal_(), it is unspecified whether this
           occurs.
    
           See _kill_() for a discussion of the requirement on delivery of
           signals.
    


## FUTURE DIRECTIONS



           None.
    


* * *