PTHREAD_SIGMASK(3)         POSIX Programmer's Manual        PTHREAD_SIGMASK(3)



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


NNAAMMEE
       pthread_sigmask, sigprocmask -- examine and change blocked signals

SSYYNNOOPPSSIISS
       #include <signal.h>

       int pthread_sigmask(int _h_o_w, const sigset_t *restrict _s_e_t,
           sigset_t *restrict _o_s_e_t);
       int sigprocmask(int _h_o_w, const sigset_t *restrict _s_e_t,
           sigset_t *restrict _o_s_e_t);

DDEESSCCRRIIPPTTIIOONN
       The _p_t_h_r_e_a_d___s_i_g_m_a_s_k() 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 _s_i_g_p_r_o_c_m_a_s_k(), without
       the restriction that the call be made in a single-threaded process.

       In a single-threaded process, the _s_i_g_p_r_o_c_m_a_s_k() function shall examine
       or change (or both) the signal mask of the calling thread.

       If the argument _s_e_t is not a null pointer, it points to a set of
       signals to be used to change the currently blocked set.

       The argument _h_o_w 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 _s_e_t.

       SIG_SETMASK The resulting set shall be the signal set pointed to by
                   _s_e_t.

       SIG_UNBLOCK The resulting set shall be the intersection of the current
                   set and the complement of the signal set pointed to by _s_e_t.

       If the argument _o_s_e_t is not a null pointer, the previous mask shall be
       stored in the location pointed to by _o_s_e_t.  If _s_e_t is a null pointer,
       the value of the argument _h_o_w 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
       _s_i_g_p_r_o_c_m_a_s_k(), at least one of those signals shall be delivered before
       the call to _s_i_g_p_r_o_c_m_a_s_k() 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
       _k_i_l_l(), _p_t_h_r_e_a_d___k_i_l_l(), _r_a_i_s_e(), or _s_i_g_q_u_e_u_e().

       If _s_i_g_p_r_o_c_m_a_s_k() fails, the thread's signal mask shall not be changed.

       The use of the _s_i_g_p_r_o_c_m_a_s_k() function is unspecified in a multi-
       threaded process.

RREETTUURRNN VVAALLUUEE
       Upon successful completion _p_t_h_r_e_a_d___s_i_g_m_a_s_k() shall return 0; otherwise,
       it shall return the corresponding error number.

       Upon successful completion, _s_i_g_p_r_o_c_m_a_s_k() shall return 0; otherwise, -1
       shall be returned, _e_r_r_n_o shall be set to indicate the error, and the
       signal mask of the process shall be unchanged.

EERRRROORRSS
       The _p_t_h_r_e_a_d___s_i_g_m_a_s_k() and _s_i_g_p_r_o_c_m_a_s_k() functions shall fail if:

       EEIINNVVAALL The value of the _h_o_w argument is not equal to one of the defined
              values.

       The _p_t_h_r_e_a_d___s_i_g_m_a_s_k() function shall not return an error code of
       [[EEIINNTTRR]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   SSiiggnnaalliinngg iinn aa MMuullttii--TThhrreeaaddeedd PPrroocceessss
       This example shows the use of _p_t_h_r_e_a_d___s_i_g_m_a_s_k() in order to deal with
       signals in a multi-threaded process. It provides a fairly general
       framework that could be easily adapted/extended.

           ##iinncclluuddee <<ssttddiioo..hh>>
           ##iinncclluuddee <<ssttddlliibb..hh>>
           ##iinncclluuddee <<pptthhrreeaadd..hh>>
           ##iinncclluuddee <<ssiiggnnaall..hh>>
           ##iinncclluuddee <<ssttrriinngg..hh>>
           ##iinncclluuddee <<eerrrrnnoo..hh>>
           ......

           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;
               }
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       When a thread's signal mask is changed in a signal-catching function
       that is installed by _s_i_g_a_c_t_i_o_n(), the restoration of the signal mask on
       return from the signal-catching function overrides that change (see
       _s_i_g_a_c_t_i_o_n()).  If the signal-catching function was installed with
       _s_i_g_n_a_l(), it is unspecified whether this occurs.

       See _k_i_l_l() for a discussion of the requirement on delivery of signals.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _e_x_e_c, _k_i_l_l(), _s_i_g_a_c_t_i_o_n(), _s_i_g_a_d_d_s_e_t(), _s_i_g_d_e_l_s_e_t(), _s_i_g_e_m_p_t_y_s_e_t(),
       _s_i_g_f_i_l_l_s_e_t(), _s_i_g_i_s_m_e_m_b_e_r(), _s_i_g_p_e_n_d_i_n_g(), _s_i_g_q_u_e_u_e(), _s_i_g_s_u_s_p_e_n_d()

       The Base Definitions volume of POSIX.1-2008, <<ssiiggnnaall..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                   PTHREAD_SIGMASK(3)
