newlib/libc/signal/signal.tex

   1 @node Signals
   2 @chapter Signal Handling (@file{signal.h})
   3
   4 A @dfn{signal} is an event that interrupts the normal flow of control
   5 in your program.  Your operating environment normally defines the full
   6 set of signals available (see @file{sys/signal.h}), as well as the
   7 default means of dealing with them---typically, either printing an
   8 error message and aborting your program, or ignoring the signal.
   9
  10 All systems support at least the following signals:
  11 @table @code
  12 @item SIGABRT
  13 Abnormal termination of a program; raised by the @code{abort} function.
  14
  15 @item SIGFPE
  16 A domain error in arithmetic, such as overflow, or division by zero.
  17
  18 @item SIGILL
  19 Attempt to execute as a function data that is not executable.
  20
  21 @item SIGINT
  22 Interrupt; an interactive attention signal.
  23
  24 @item SIGSEGV
  25 An attempt to access a memory location that is not available.
  26
  27 @item SIGTERM
  28 A request that your program end execution.
  29 @end table
  30
  31 Two functions are available for dealing with asynchronous
  32 signals---one to allow your program to send signals to itself (this is
  33 called @dfn{raising} a signal), and one to specify subroutines (called
  34 @dfn{handlers} to handle particular signals that you anticipate may
  35 occur---whether raised by your own program or the operating environment.
  36
  37 To support these functions, @file{signal.h} defines three macros:
  38
  39 @table @code
  40 @item SIG_DFL
  41 Used with the @code{signal} function in place of a pointer to a
  42 handler subroutine, to select the operating environment's default
  43 handling of a signal.
  44
  45 @item SIG_IGN
  46 Used with the @code{signal} function in place of a pointer to a
  47 handler, to ignore a particular signal.
  48
  49 @item SIG_ERR
  50 Returned by the @code{signal} function in place of a pointer to a
  51 handler, to indicate that your request to set up a handler could not
  52 be honored for some reason.
  53 @end table
  54
  55 @file{signal.h} also defines an integral type, @code{sig_atomic_t}.
  56 This type is not used in any function declarations; it exists only to
  57 allow your signal handlers to declare a static storage location where
  58 they may store a signal value.  (Static storage is not otherwise
  59 reliable from signal handlers.)
  60
  61 @menu
  62 * Function psignal:: Print a signal message to standard error
  63 * Function raise::   Send a signal
  64 * Function sig2str:: Translate between signal number and name
  65 * Function signal::  Specify handler subroutine for a signal
  66 @end menu
  67
  68 @page
  69 @include signal/psignal.def
  70
  71 @page
  72 @include signal/raise.def
  73
  74 @page
  75 @include signal/sig2str.def
  76
  77 @page
  78 @include signal/signal.def