# sigaction

## 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



           sigaction — examine and change a signal action
    


## SYNOPSIS



           #include <signal.h>
    
           int sigaction(int _sig_ , const struct sigaction *restrict _act_ ,
               struct sigaction *restrict _oact_);
    


## DESCRIPTION



           The _sigaction_() function allows the calling process to examine
           and/or specify the action to be associated with a specific signal.
           The argument _sig_ specifies the signal; acceptable values are
           defined in _< signal.h>_.
    
           The structure **sigaction** , used to describe an action to be taken,
           is defined in the _< signal.h>_ header to include at least the
           following members:
      ┌─────────────────┬───────────────┬───────────────────────────────────────┐
      │   **Member Type** │ **Member Name** │             **Description** │
      ├─────────────────┼───────────────┼───────────────────────────────────────┤
      │ **void(*) (int)** │ _sa_handler_    │Pointer to a signal-catching function  │
      │                 │               │or one of the macros SIG_IGN or        │
      │                 │               │SIG_DFL.                               │
      │ **sigset_t** │ _sa_mask_       │Additional set of signals to be        │
      │                 │               │blocked during execution of signal-    │
      │                 │               │catching function.                     │
      │ **int** │ _sa_flags_      │Special flags to affect behavior of    │
      │                 │               │signal.                                │
      │ **void(*) (int,** │ _sa_sigaction_  │Pointer to a signal-catching function. │
      │   **siginfo_t *,** │               │                                       │
      │ **void *)** │               │                                       │
      └─────────────────┴───────────────┴───────────────────────────────────────┘
    
           The  storage  occupied by _sa_handler_ and _sa_sigaction_ may overlap,
           and a conforming application shall not use both simultaneously.
    
           If the argument _act_  is  not  a  null  pointer,  it  points  to  a
           structure   specifying  the  action  to  be  associated  with  the
           specified signal. If the argument _oact_ is not a null pointer,  the
           action  previously  associated  with  the  signal is stored in the
           location pointed to by the argument _oact_.  If the argument _act_  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 _sa_flags_
           field of the **sigaction** structure, the _sa_handler_ field  identifies
           the  action  to  be  associated with the specified signal.  If the
           SA_SIGINFO flag is set in the  _sa_flags_  field,  the  _sa_sigaction_
           field specifies a signal-catching function.
    
           The  _sa_flags_  field  can  be  used  to modify the behavior of the
           specified signal.
    
           The following flags, defined in the _< signal.h>_ header, can be  set
           in _sa_flags_ :
    
           SA_NOCLDSTOP  Do not generate SIGCHLD when children stop or
                         stopped children continue.
    
                         If _sig_ is SIGCHLD and the SA_NOCLDSTOP flag is not
                         set in _sa_flags_ , 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 _sig_
                         is SIGCHLD and the SA_NOCLDSTOP flag is set in
                         _sa_flags_ , 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 _sigaltstack_(), 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.
    
                         **Note:** 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, _sigaction_() 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
                         _errno_ set to **[EINTR]**.  If set, and a function
                         specified as interruptible is interrupted by this
                         signal, the function shall restart and shall not
                         fail with **[EINTR]** 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 _errno_ set to **[EINTR]**.
    
           SA_SIGINFO    If cleared and the signal is caught, the signal-
                         catching function shall be entered as:
    
                             void func(int _signo_);
    
                         where _signo_ is the only argument to the signal-
                         catching function. In this case, the application
                         shall use the _sa_handler_ member to describe the
                         signal-catching function and the application shall
                         not modify the _sa_sigaction_ member.
    
                         If SA_SIGINFO is set and the signal is caught, the
                         signal-catching function shall be entered as:
    
                             void func(int _signo_ , siginfo_t *_info_ , void *_context_);
    
                         where two additional arguments are passed to the
                         signal-catching function. The second argument shall
                         point to an object of type **siginfo_t** explaining the
                         reason why the signal was generated; the third
                         argument can be cast to a pointer to an object of
                         type **ucontext_t** to refer to the receiving thread's
                         context that was interrupted when the signal was
                         delivered. In this case, the application shall use
                         the _sa_sigaction_ member to describe the signal-
                         catching function and the application shall not
                         modify the _sa_handler_ member.
    
                         The _si_signo_ member contains the system-generated
                         signal number.
    
                         The _si_errno_ 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 _si_code_ member contains a code identifying the
                         cause of the signal, as described in _Section 2.4.3_ ,
                         _Signal Actions_.
    
           SA_NOCLDWAIT  If _sig_ does not equal SIGCHLD, the behavior is
                         unspecified. Otherwise, the behavior of the
                         SA_NOCLDWAIT flag is as specified in _Consequences of_
                         _Process Termination_.
    
           SA_NODEFER    If set and _sig_ is caught, _sig_ shall not be added to
                         the thread's signal mask on entry to the signal
                         handler unless it is included in _sa_mask_.
                         Otherwise, _sig_ 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
           _sigaction_(), a new signal mask is calculated and installed for the
           duration of the signal-catching function (or until a call to
           either _sigprocmask_() or _sigsuspend_() is made). This mask is formed
           by taking the union of the current signal mask and the value of
           the _sa_mask_ 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 _sigaction_()), until the SA_RESETHAND flag causes resetting
           of the handler, or until one of the _exec_ functions is called.
    
           If the previous action for _sig_ had been established by _signal_(),
           the values of the fields returned in the structure pointed to by
           _oact_ are unspecified, and in particular _oact_ ->_sa_handler_ is not
           necessarily the same value passed to _signal_().  However, if a
           pointer to the same structure or a copy thereof is passed to a
           subsequent call to _sigaction_() via the _act_ argument, handling of
           the signal shall be as if the original call to _signal_() were
           repeated.
    
           If _sigaction_() 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 _errno_ set to **[EINVAL]**.
    
           If SA_SIGINFO is not set in _sa_flags_ , then the disposition of
           subsequent occurrences of _sig_ 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 _sa_flags_ ,
           then subsequent occurrences of _sig_ generated by _sigqueue_() or as a
           result of any signal-generating function that supports the
           specification of an application-defined value (when _sig_ 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 _si_value_ member of the **siginfo_t**
           structure.
    
           The result of the use of _sigaction_() and a _sigwait_() function
           concurrently within a process on the same signal is unspecified.
    


## RETURN VALUE



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


## ERRORS



           The _sigaction_() function shall fail if:
    
           **EINVAL** The _sig_ 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.
    
           The _sigaction_() function may fail if:
    
           **EINVAL** An attempt was made to set the action to SIG_DFL for a
                  signal that cannot be caught or ignored (or both).
    
           In addition, on systems that do not support the XSI option, the
           _sigaction_() function may fail if the SA_SIGINFO flag is set in the
           _sa_flags_ field of the **sigaction** structure for a signal not in the
           range SIGRTMIN to SIGRTMAX.
    
           _The following sections are informative._
    


## EXAMPLES



       **Establishing a Signal Handler**
           The following example demonstrates the use of _sigaction_() to
           establish a handler for the SIGINT signal.
    
               #include <signal.h>
    
               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 */
               }
    


## APPLICATION USAGE



           The _sigaction_() function supersedes the _signal_() function, and
           should be used in preference. In particular, _sigaction_() and
           _signal_() 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‐2017, 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 _sleep_() 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 semget(3p),
           sem_init(3p), sem_open(3p), and so on). Note in particular that
           even the ``safe'' functions may modify _errno_ ; 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 _errno_ and the subsequent examination of _errno_ could
           result in the signal-catching function changing the value of
           _errno_.  Naturally, the same principles apply to the async-signal-
           safety of application routines and asynchronous data access. Note
           that _longjmp_() and _siglongjmp_() are not in the list of async-
           signal-safe functions. This is because the code executing after
           _longjmp_() and _siglongjmp_() can call any unsafe functions with the
           same danger as calling those unsafe functions directly from the
           signal handler. Applications that use _longjmp_() and _siglongjmp_()
           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 _malloc_() or
           _free_() 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‐2017 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 _longjmp_() or __longjmp_() is
           used to leave the signal handler, then the signal mask must be
           explicitly restored.
    
           This volume of POSIX.1‐2017 defines the third argument of a signal
           handling function when SA_SIGINFO is set as a **void *** instead of a
           **ucontext_t *** , but without requiring type checking. New
           applications should explicitly cast the third argument of the
           signal handling function to **ucontext_t ***.
    
           The BSD optional four argument signal handling function is not
           supported by this volume of POSIX.1‐2017. The BSD declaration
           would be:
    
               void handler(int _sig_ , int _code_ , struct sigcontext *_scp_ ,
                   char *_addr_);
    
           where _sig_ is the signal number, _code_ is additional information on
           certain signals, _scp_ is a pointer to the **sigcontext** structure, and
           _addr_ 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 _sigaction_() 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‐2017, _Section_
           _B.2.4.2_ , _Signal Generation and Delivery_.
    


## RATIONALE



           Although this volume of POSIX.1‐2017 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 _sigaction_() reflect this in
           the information returned in the _oact_ argument. In other words, if
           SIGKILL is included in the _sa_mask_ field of _act_ , it is unspecified
           whether or not a subsequent call to _sigaction_() returns with
           SIGKILL included in the _sa_mask_ field of _oact_.
    
           The SA_NOCLDSTOP flag, when supplied in the _act_ ->_sa_flags_
           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 _waitpid_()
           function with the WNOHANG flag set, acting on each child for which
           status is returned, until _waitpid_() 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 _ptrace_() 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‐2017.
    
           This volume of POSIX.1‐2017 requires that calls to _sigaction_()
           that supply a NULL _act_ argument succeed, even in the case of
           signals that cannot be caught or ignored (that is, SIGKILL or
           SIGSTOP).  The System V _signal_() and BSD _sigvec_() functions return
           **[EINVAL]** in these cases and, in this respect, their behavior
           varies from _sigaction_().
    
           This volume of POSIX.1‐2017 requires that _sigaction_() properly
           save and restore a signal action set up by the ISO C standard
           _signal_() function. However, there is no guarantee that the reverse
           is true, nor could there be given the greater amount of
           information conveyed by the **sigaction** 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 _sigaction_().
    
           It was intended that the _signal_() function should be implementable
           as a library routine using _sigaction_().
    
           The POSIX Realtime Extension extends the _sigaction_() 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.
    


## FUTURE DIRECTIONS



           None.
    


* * *