SIGACTION(3)               POSIX Programmer's Manual              SIGACTION(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
       sigaction -- examine and change a signal action

SSYYNNOOPPSSIISS
       #include <signal.h>

       int sigaction(int _s_i_g, const struct sigaction *restrict _a_c_t,
           struct sigaction *restrict _o_a_c_t);

DDEESSCCRRIIPPTTIIOONN
       The _s_i_g_a_c_t_i_o_n() function allows the calling process to examine and/or
       specify the action to be associated with a specific signal. The
       argument _s_i_g specifies the signal; acceptable values are defined in
       _<_s_i_g_n_a_l_._h_>.

       The structure ssiiggaaccttiioonn, used to describe an action to be taken, is
       defined in the _<_s_i_g_n_a_l_._h_> header to include at least the following
       members:

      +----------------+---------------+---------------------------------------+
      |  MMeemmbbeerr TTyyppee   | MMeemmbbeerr NNaammee   |             DDeessccrriippttiioonn               |
      +----------------+---------------+---------------------------------------+
      |vvooiidd((**)) ((iinntt))   | _s_a___h_a_n_d_l_e_r    |Pointer to a signal-catching function  |
      |                |               |or one of the macros SIG_IGN or        |
      |                |               |SIG_DFL.                               |
      |ssiiggsseett__tt        | _s_a___m_a_s_k       |Additional set of signals to be        |
      |                |               |blocked during execution of signal-    |
      |                |               |catching function.                     |
      |iinntt             | _s_a___f_l_a_g_s      |Special flags to affect behavior of    |
      |                |               |signal.                                |
      |vvooiidd((**)) ((iinntt,,   | _s_a___s_i_g_a_c_t_i_o_n  |Pointer to a signal-catching function. |
      |  ssiiggiinnffoo__tt **,,  |               |                                       |
      |vvooiidd **))         |               |                                       |
      +----------------+---------------+---------------------------------------+
       The storage occupied by _s_a___h_a_n_d_l_e_r and _s_a___s_i_g_a_c_t_i_o_n may overlap, and a
       conforming application shall not use both simultaneously.

       If the argument _a_c_t is not a null pointer, it points to a structure
       specifying the action to be associated with the specified signal. If
       the argument _o_a_c_t is not a null pointer, the action previously
       associated with the signal is stored in the location pointed to by the
       argument _o_a_c_t.  If the argument _a_c_t is a null pointer, signal handling
       is unchanged; thus, the call can be used to enquire about the current
       handling of a given signal. The SIGKILL and SIGSTOP signals shall not
       be added to the signal mask using this mechanism; this restriction
       shall be enforced by the system without causing an error to be
       indicated.

       If the SA_SIGINFO flag (see below) is cleared in the _s_a___f_l_a_g_s field of
       the ssiiggaaccttiioonn structure, the _s_a___h_a_n_d_l_e_r field identifies the action to
       be associated with the specified signal.  If the SA_SIGINFO flag is set
       in the _s_a___f_l_a_g_s field, the _s_a___s_i_g_a_c_t_i_o_n field specifies a signal-
       catching function.

       The _s_a___f_l_a_g_s field can be used to modify the behavior of the specified
       signal.

       The following flags, defined in the _<_s_i_g_n_a_l_._h_> header, can be set in
       _s_a___f_l_a_g_s:

       SA_NOCLDSTOP  Do not generate SIGCHLD when children stop or stopped
                     children continue.

                     If _s_i_g is SIGCHLD and the SA_NOCLDSTOP flag is not set in
                     _s_a___f_l_a_g_s, and the implementation supports the SIGCHLD
                     signal, then a SIGCHLD signal shall be generated for the
                     calling process whenever any of its child processes stop
                     and a SIGCHLD signal may be generated for the calling
                     process whenever any of its stopped child processes are
                     continued.  If _s_i_g is SIGCHLD and the SA_NOCLDSTOP flag
                     is set in _s_a___f_l_a_g_s, then the implementation shall not
                     generate a SIGCHLD signal in this way.

       SA_ONSTACK    If set and an alternate signal stack has been declared
                     with _s_i_g_a_l_t_s_t_a_c_k(), the signal shall be delivered to the
                     calling process on that stack.  Otherwise, the signal
                     shall be delivered on the current stack.

       SA_RESETHAND  If set, the disposition of the signal shall be reset to
                     SIG_DFL and the SA_SIGINFO flag shall be cleared on entry
                     to the signal handler.

                     NNoottee::     SIGILL and SIGTRAP cannot be automatically
                               reset when delivered; the system silently
                               enforces this restriction.

                     Otherwise, the disposition of the signal shall not be
                     modified on entry to the signal handler.

                     In addition, if this flag is set, _s_i_g_a_c_t_i_o_n() may behave
                     as if the SA_NODEFER flag were also set.

       SA_RESTART    This flag affects the behavior of interruptible
                     functions; that is, those specified to fail with _e_r_r_n_o
                     set to [[EEIINNTTRR]].  If set, and a function specified as
                     interruptible is interrupted by this signal, the function
                     shall restart and shall not fail with [[EEIINNTTRR]] unless
                     otherwise specified. If an interruptible function which
                     uses a timeout is restarted, the duration of the timeout
                     following the restart is set to an unspecified value that
                     does not exceed the original timeout value. If the flag
                     is not set, interruptible functions interrupted by this
                     signal shall fail with _e_r_r_n_o set to [[EEIINNTTRR]].

       SA_SIGINFO    If cleared and the signal is caught, the signal-catching
                     function shall be entered as:

                         vvooiidd ffuunncc((iinntt _s_i_g_n_o));;

                     where _s_i_g_n_o is the only argument to the signal-catching
                     function. In this case, the application shall use the
                     _s_a___h_a_n_d_l_e_r member to describe the signal-catching
                     function and the application shall not modify the
                     _s_a___s_i_g_a_c_t_i_o_n member.

                     If SA_SIGINFO is set and the signal is caught, the
                     signal-catching function shall be entered as:

                         vvooiidd ffuunncc((iinntt _s_i_g_n_o,, ssiiggiinnffoo__tt **_i_n_f_o,, vvooiidd **_c_o_n_t_e_x_t));;

                     where two additional arguments are passed to the signal-
                     catching function. The second argument shall point to an
                     object of type ssiiggiinnffoo__tt explaining the reason why the
                     signal was generated; the third argument can be cast to a
                     pointer to an object of type uuccoonntteexxtt__tt to refer to the
                     receiving thread's context that was interrupted when the
                     signal was delivered. In this case, the application shall
                     use the _s_a___s_i_g_a_c_t_i_o_n member to describe the signal-
                     catching function and the application shall not modify
                     the _s_a___h_a_n_d_l_e_r member.

                     The _s_i___s_i_g_n_o member contains the system-generated signal
                     number.

                     The _s_i___e_r_r_n_o member may contain implementation-defined
                     additional error information; if non-zero, it contains an
                     error number identifying the condition that caused the
                     signal to be generated.

                     The _s_i___c_o_d_e member contains a code identifying the cause
                     of the signal, as described in _S_e_c_t_i_o_n _2_._4_._3, _S_i_g_n_a_l
                     _A_c_t_i_o_n_s.

       SA_NOCLDWAIT  If set, and _s_i_g equals SIGCHLD, child processes of the
                     calling processes shall not be transformed into zombie
                     processes when they terminate. If the calling process
                     subsequently waits for its children, and the process has
                     no unwaited-for children that were transformed into
                     zombie processes, it shall block until all of its
                     children terminate, and _w_a_i_t(), _w_a_i_t_i_d(), and _w_a_i_t_p_i_d()
                     shall fail and set _e_r_r_n_o to [[EECCHHIILLDD]].  Otherwise,
                     terminating child processes shall be transformed into
                     zombie processes, unless SIGCHLD is set to SIG_IGN.

       SA_NODEFER    If set and _s_i_g is caught, _s_i_g shall not be added to the
                     thread's signal mask on entry to the signal handler
                     unless it is included in _s_a___m_a_s_k.  Otherwise, _s_i_g shall
                     always be added to the thread's signal mask on entry to
                     the signal handler.

       When a signal is caught by a signal-catching function installed by
       _s_i_g_a_c_t_i_o_n(), a new signal mask is calculated and installed for the
       duration of the signal-catching function (or until a call to either
       _s_i_g_p_r_o_c_m_a_s_k() or _s_i_g_s_u_s_p_e_n_d() is made). This mask is formed by taking
       the union of the current signal mask and the value of the _s_a___m_a_s_k for
       the signal being delivered, and unless SA_NODEFER or SA_RESETHAND is
       set, then including the signal being delivered. If and when the user's
       signal handler returns normally, the original signal mask is restored.

       Once an action is installed for a specific signal, it shall remain
       installed until another action is explicitly requested (by another call
       to _s_i_g_a_c_t_i_o_n()), until the SA_RESETHAND flag causes resetting of the
       handler, or until one of the _e_x_e_c functions is called.

       If the previous action for _s_i_g had been established by _s_i_g_n_a_l(), the
       values of the fields returned in the structure pointed to by _o_a_c_t are
       unspecified, and in particular _o_a_c_t->_s_a___h_a_n_d_l_e_r is not necessarily the
       same value passed to _s_i_g_n_a_l().  However, if a pointer to the same
       structure or a copy thereof is passed to a subsequent call to
       _s_i_g_a_c_t_i_o_n() via the _a_c_t argument, handling of the signal shall be as if
       the original call to _s_i_g_n_a_l() were repeated.

       If _s_i_g_a_c_t_i_o_n() fails, no new signal handler is installed.

       It is unspecified whether an attempt to set the action for a signal
       that cannot be caught or ignored to SIG_DFL is ignored or causes an
       error to be returned with _e_r_r_n_o set to [[EEIINNVVAALL]].

       If SA_SIGINFO is not set in _s_a___f_l_a_g_s, then the disposition of
       subsequent occurrences of _s_i_g when it is already pending is
       implementation-defined; the signal-catching function shall be invoked
       with a single argument.  If SA_SIGINFO is set in _s_a___f_l_a_g_s, then
       subsequent occurrences of _s_i_g generated by _s_i_g_q_u_e_u_e() or as a result of
       any signal-generating function that supports the specification of an
       application-defined value (when _s_i_g is already pending) shall be queued
       in FIFO order until delivered or accepted; the signal-catching function
       shall be invoked with three arguments. The application specified value
       is passed to the signal-catching function as the _s_i___v_a_l_u_e member of the
       ssiiggiinnffoo__tt structure.

       The result of the use of _s_i_g_a_c_t_i_o_n() and a _s_i_g_w_a_i_t() function
       concurrently within a process on the same signal is unspecified.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _s_i_g_a_c_t_i_o_n() shall return 0; otherwise, -1
       shall be returned, _e_r_r_n_o shall be set to indicate the error, and no new
       signal-catching function shall be installed.

EERRRROORRSS
       The _s_i_g_a_c_t_i_o_n() function shall fail if:

       EEIINNVVAALL The _s_i_g argument is not a valid signal number or an attempt is
              made to catch a signal that cannot be caught or ignore a signal
              that cannot be ignored.

       EENNOOTTSSUUPP
              The SA_SIGINFO bit flag is set in the _s_a___f_l_a_g_s field of the
              ssiiggaaccttiioonn structure.

       The _s_i_g_a_c_t_i_o_n() function may fail if:

       EEIINNVVAALL An attempt was made to set the action to SIG_DFL for a signal
              that cannot be caught or ignored (or both).

       In addition, the _s_i_g_a_c_t_i_o_n() function may fail if the SA_SIGINFO flag
       is set in the _s_a___f_l_a_g_s field of the ssiiggaaccttiioonn structure for a signal
       not in the range SIGRTMIN to SIGRTMAX.

       _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
   EEssttaabblliisshhiinngg aa SSiiggnnaall HHaannddlleerr
       The following example demonstrates the use of _s_i_g_a_c_t_i_o_n() to establish
       a handler for the SIGINT signal.

           ##iinncclluuddee <<ssiiggnnaall..hh>>

           static void handler(int signum)
           {
               /* Take appropriate actions for signal delivery */
           }

           int main()
           {
               struct sigaction sa;

               sa.sa_handler = handler;
               sigemptyset(&sa.sa_mask);
               sa.sa_flags = SA_RESTART; /* Restart functions if
                                            interrupted by handler */
               if (sigaction(SIGINT, &sa, NULL) == -1)
                   /* Handle error */;

               /* Further code */
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _s_i_g_a_c_t_i_o_n() function supersedes the _s_i_g_n_a_l() function, and should
       be used in preference. In particular, _s_i_g_a_c_t_i_o_n() and _s_i_g_n_a_l() should
       not be used in the same process to control the same signal.  The
       behavior of async-signal-safe functions, as defined in their respective
       DESCRIPTION sections, is as specified by this volume of POSIX.1-2008,
       regardless of invocation from a signal-catching function. This is the
       only intended meaning of the statement that async-signal-safe functions
       may be used in signal-catching functions without restrictions.
       Applications must still consider all effects of such functions on such
       things as data structures, files, and process state. In particular,
       application developers need to consider the restrictions on
       interactions when interrupting _s_l_e_e_p() and interactions among multiple
       handles for a file description. The fact that any specific function is
       listed as async-signal-safe does not necessarily mean that invocation
       of that function from a signal-catching function is recommended.

       In order to prevent errors arising from interrupting non-async-signal-
       safe function calls, applications should protect calls to these
       functions either by blocking the appropriate signals or through the use
       of some programmatic semaphore (see _s_e_m_g_e_t(), _s_e_m___i_n_i_t(), _s_e_m___o_p_e_n(),
       and so on). Note in particular that even the ``safe'' functions may
       modify _e_r_r_n_o; the signal-catching function, if not executing as an
       independent thread, should save and restore its value in order to avoid
       the possibility that delivery of a signal in between an error return
       from a function that sets _e_r_r_n_o and the subsequent examination of _e_r_r_n_o
       could result in the signal-catching function changing the value of
       _e_r_r_n_o.  Naturally, the same principles apply to the async-signal-safety
       of application routines and asynchronous data access. Note that
       _l_o_n_g_j_m_p() and _s_i_g_l_o_n_g_j_m_p() are not in the list of async-signal-safe
       functions. This is because the code executing after _l_o_n_g_j_m_p() and
       _s_i_g_l_o_n_g_j_m_p() can call any unsafe functions with the same danger as
       calling those unsafe functions directly from the signal handler.
       Applications that use _l_o_n_g_j_m_p() and _s_i_g_l_o_n_g_j_m_p() from within signal
       handlers require rigorous protection in order to be portable. Many of
       the other functions that are excluded from the list are traditionally
       implemented using either _m_a_l_l_o_c() or _f_r_e_e() functions or the standard
       I/O library, both of which traditionally use data structures in a non-
       async-signal-safe manner. Since any combination of different functions
       using a common data structure can cause async-signal-safety problems,
       this volume of POSIX.1-2008 does not define the behavior when any
       unsafe function is called in a signal handler that interrupts an unsafe
       function.

       Usually, the signal is executed on the stack that was in effect before
       the signal was delivered. An alternate stack may be specified to
       receive a subset of the signals being caught.

       When the signal handler returns, the receiving thread resumes execution
       at the point it was interrupted unless the signal handler makes other
       arrangements. If _l_o_n_g_j_m_p() or ___l_o_n_g_j_m_p() is used to leave the signal
       handler, then the signal mask must be explicitly restored.

       This volume of POSIX.1-2008 defines the third argument of a signal
       handling function when SA_SIGINFO is set as a vvooiidd ** instead of a
       uuccoonntteexxtt__tt **, but without requiring type checking. New applications
       should explicitly cast the third argument of the signal handling
       function to uuccoonntteexxtt__tt **.

       The BSD optional four argument signal handling function is not
       supported by this volume of POSIX.1-2008. The BSD declaration would be:

           vvooiidd hhaannddlleerr((iinntt _s_i_g,, iinntt _c_o_d_e,, ssttrruucctt ssiiggccoonntteexxtt **_s_c_p,,
               cchhaarr **_a_d_d_r));;

       where _s_i_g is the signal number, _c_o_d_e is additional information on
       certain signals, _s_c_p is a pointer to the ssiiggccoonntteexxtt structure, and _a_d_d_r
       is additional address information. Much the same information is
       available in the objects pointed to by the second argument of the
       signal handler specified when SA_SIGINFO is set.

       Since the _s_i_g_a_c_t_i_o_n() function is allowed but not required to set
       SA_NODEFER when the application sets the SA_RESETHAND flag,
       applications which depend on the SA_RESETHAND functionality for the
       newly installed signal handler must always explicitly set SA_NODEFER
       when they set SA_RESETHAND in order to be portable.

       See also the rationale for Realtime Signal Generation and Delivery in
       the Rationale (Informative) volume of POSIX.1-2008, _S_e_c_t_i_o_n _B_._2_._4_._2,
       _S_i_g_n_a_l _G_e_n_e_r_a_t_i_o_n _a_n_d _D_e_l_i_v_e_r_y.

RRAATTIIOONNAALLEE
       Although this volume of POSIX.1-2008 requires that signals that cannot
       be ignored shall not be added to the signal mask when a signal-catching
       function is entered, there is no explicit requirement that subsequent
       calls to _s_i_g_a_c_t_i_o_n() reflect this in the information returned in the
       _o_a_c_t argument. In other words, if SIGKILL is included in the _s_a___m_a_s_k
       field of _a_c_t, it is unspecified whether or not a subsequent call to
       _s_i_g_a_c_t_i_o_n() returns with SIGKILL included in the _s_a___m_a_s_k field of _o_a_c_t.

       The SA_NOCLDSTOP flag, when supplied in the _a_c_t->_s_a___f_l_a_g_s parameter,
       allows overloading SIGCHLD with the System V semantics that each SIGCLD
       signal indicates a single terminated child. Most conforming
       applications that catch SIGCHLD are expected to install signal-catching
       functions that repeatedly call the _w_a_i_t_p_i_d() function with the WNOHANG
       flag set, acting on each child for which status is returned, until
       _w_a_i_t_p_i_d() returns zero. If stopped children are not of interest, the
       use of the SA_NOCLDSTOP flag can prevent the overhead from invoking the
       signal-catching routine when they stop.

       Some historical implementations also define other mechanisms for
       stopping processes, such as the _p_t_r_a_c_e() function. These
       implementations usually do not generate a SIGCHLD signal when processes
       stop due to this mechanism; however, that is beyond the scope of this
       volume of POSIX.1-2008.

       This volume of POSIX.1-2008 requires that calls to _s_i_g_a_c_t_i_o_n() that
       supply a NULL _a_c_t argument succeed, even in the case of signals that
       cannot be caught or ignored (that is, SIGKILL or SIGSTOP).  The System
       V _s_i_g_n_a_l() and BSD _s_i_g_v_e_c() functions return [[EEIINNVVAALL]] in these cases
       and, in this respect, their behavior varies from _s_i_g_a_c_t_i_o_n().

       This volume of POSIX.1-2008 requires that _s_i_g_a_c_t_i_o_n() properly save and
       restore a signal action set up by the ISO C standard _s_i_g_n_a_l() function.
       However, there is no guarantee that the reverse is true, nor could
       there be given the greater amount of information conveyed by the
       ssiiggaaccttiioonn structure. Because of this, applications should avoid using
       both functions for the same signal in the same process. Since this
       cannot always be avoided in case of general-purpose library routines,
       they should always be implemented with _s_i_g_a_c_t_i_o_n().

       It was intended that the _s_i_g_n_a_l() function should be implementable as a
       library routine using _s_i_g_a_c_t_i_o_n().

       The POSIX Realtime Extension extends the _s_i_g_a_c_t_i_o_n() function as
       specified by the POSIX.1-1990 standard to allow the application to
       request on a per-signal basis via an additional signal action flag that
       the extra parameters, including the application-defined signal value,
       if any, be passed to the signal-catching function.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._4, _S_i_g_n_a_l _C_o_n_c_e_p_t_s, _e_x_e_c, _k_i_l_l(), ___l_o_n_g_j_m_p(), _l_o_n_g_j_m_p(),
       _p_t_h_r_e_a_d___s_i_g_m_a_s_k(), _r_a_i_s_e(), _s_e_m_g_e_t(), _s_e_m___i_n_i_t(), _s_e_m___o_p_e_n(),
       _s_i_g_a_d_d_s_e_t(), _s_i_g_a_l_t_s_t_a_c_k(), _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_n_a_l(), _s_i_g_s_u_s_p_e_n_d(), _w_a_i_t(), _w_a_i_t_i_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                         SIGACTION(3)
