File: libc.info,  Node: Basic Signal Handling,  Next: Advanced Signal Handling,\  Up: Signal Actions

Basic Signal Handling
---------------------

   The `signal' function provides a simple interface for establishing
an action for a particular signal.  The function and associated macros
are declared in the header file `signal.h'.

 - Data Type: sighandler_t
     This is the type of signal handler functions.  Signal handlers
     take one integer argument specifying the signal number, and have
     return type `void'.  So, you should define handler functions like
     this:

          void HANDLER (int `signum') { ... }

     The name `sighandler_t' for this data type is a GNU extension.

 - Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION)
     The `signal' function establishes ACTION as the action for the
     signal SIGNUM.

     The first argument, SIGNUM, identifies the signal whose behavior
     you want to control, and should be a signal number.  The proper
     way to specify a signal number is with one of the symbolic signal
     names (*note Standard Signals::.)--don't use an explicit number,
     because the numerical code for a given kind of signal may vary
     from operating system to operating system.

     The second argument, ACTION, specifies the action to use for the
     signal SIGNUM.  This can be one of the following:

    `SIG_DFL'
          `SIG_DFL' specifies the default action for the particular
          signal.  The default actions for various kinds of signals are
          stated in *Note Standard Signals::.

    `SIG_IGN'
          `SIG_IGN' specifies that the signal should be ignored.

          Your program generally should not ignore signals that
          represent serious events or that are normally used to request
          termination.  You cannot ignore the `SIGKILL' or `SIGSTOP'
          signals at all.  You can ignore program error signals like
          `SIGSEGV', but ignoring the error won't enable the program to
          continue executing meaningfully.  Ignoring user requests such
          as `SIGINT', `SIGQUIT', and `SIGTSTP' is unfriendly.

          When you do not wish signals to be delivered during a certain
          part of the program, the thing to do is to block them, not
          ignore them.  *Note Blocking Signals::.

    `HANDLER'
          Supply the address of a handler function in your program, to
          specify running this handler as the way to deliver the signal.

          For more information about defining signal handler functions,
          see *Note Defining Handlers::.

     If you set the action for a signal to `SIG_IGN', or if you set it
     to `SIG_DFL' and the default action is to ignore that signal, then
     any pending signals of that type are discarded (even if they are
     blocked).  Discarding the pending signals means that they will
     never be delivered, not even if you subsequently specify another
     action and unblock this kind of signal.

     The `signal' function returns the action that was previously in
     effect for the specified SIGNUM.  You can save this value and
     restore it later by calling `signal' again.

     If `signal' can't honor the request, it returns `SIG_ERR' instead.
     The following `errno' error conditions are defined for this
     function:

    `EINVAL'
          You specified an invalid SIGNUM; or you tried to ignore or
          provide a handler for `SIGKILL' or `SIGSTOP'.

   *Compatibility Note:* A problem when working with the `signal'
function is that it has a different semantic on BSD and SVID system.
The difference is that on SVID systems the signal handler is
deinstalled after an signal was delivered.  On BSD systems the handler
must be explicitly deinstalled.  In the GNU C Library we use the BSD
version by default.  To use the SVID version you can either use the
function `sysv_signal' (see below) or use the `_XOPEN_SOURCE' feature
select macro (*note Feature Test Macros::.).  Generally it should be
avoided to use this functions due to the compatibility problems.  It is
better to use `sigaction' if it is available since the results are much
more reliable.

   Here is a simple example of setting up a handler to delete temporary
files when certain fatal signals happen:

     #include <signal.h>

     void
     termination_handler (int signum)
     {
       struct temp_file *p;

       for (p = temp_file_list; p; p = p->next)
         unlink (p->name);
     }

     int
     main (void)
     {
       ...
       if (signal (SIGINT, termination_handler) == SIG_IGN)
         signal (SIGINT, SIG_IGN);
       if (signal (SIGHUP, termination_handler) == SIG_IGN)
         signal (SIGHUP, SIG_IGN);
       if (signal (SIGTERM, termination_handler) == SIG_IGN)
         signal (SIGTERM, SIG_IGN);
       ...
     }

Note how if a given signal was previously set to be ignored, this code
avoids altering that setting.  This is because non-job-control shells
often ignore certain signals when starting children, and it is important
for the children to respect this.

   We do not handle `SIGQUIT' or the program error signals in this
example because these are designed to provide information for debugging
(a core dump), and the temporary files may give useful information.

 - Function: sighandler_t sysv_signal (int SIGNUM, sighandler_t ACTION)
     The `sysv_signal' implements the behaviour of the standard
     `signal' function as found on SVID systems.  The difference to BSD
     systems is that the handler is deinstalled after a delivery of a
     signal.

     *Compatibility Note:* As said above for `signal', this function
     should be avoided when possible.  `sigaction' is the preferred
     method.

 - Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)
     The `ssignal' function does the same thing as `signal'; it is
     provided only for compatibility with SVID.

 - Macro: sighandler_t SIG_ERR
     The value of this macro is used as the return value from `signal'
     to indicate an error.


