sigaction,  sigprocmask,  sigpending,  sigsuspend  - POSIX
       signal handling functions.


SYNOPSIS

       #include <signal.h>


       int sigaction(int signum,  const  struct  sigaction  *act,
       struct sigaction *oldact);

       int  sigprocmask(int  how,  const  sigset_t *set, sigset_t
       *oldset);

       int sigpending(sigset_t *set);

       int sigsuspend(const sigset_t *mask);


DESCRIPTION

       The sigaction system call is used  to  change  the  action
       taken by a process on receipt of a specific signal.

       signum  specifies  the  signal and can be any valid signal
       except SIGKILL and SIGSTOP.

       If act is non-null, the new action for  signal  signum  is
       installed  from  act.  If oldact is non-null, the previous
       action is saved in oldact.

       The sigaction structure is defined as something like

              struct sigaction {
                  void (*sa_handler)(int);
                  void (*sa_sigaction)(int, siginfo_t *, void *);
                  sigset_t sa_mask;
                  int sa_flags;
                  void (*sa_restorer)(void);
              }

       On some architectures a union is involved - do not  assign
       to both sa_handler and sa_sigaction.

       The  sa_restorer  element  is  obsolete  and should not be
       used.  POSIX does not specify a sa_restorer element.

       sa_handler specifies the  action  to  be  associated  with
       signum  and may be SIG_DFL for the default action, SIG_IGN
       to ignore this signal, or a pointer to a  signal  handling
       function.

       sa_mask  gives  a  mask of signals which should be blocked
       during execution of the signal handler.  In addition,  the
       signal which triggered the handler will be blocked, unless
       behaviour  of the signal handling process. It is formed by
       the bitwise OR of zero or more of the following:

              SA_NOCLDSTOP
                     If signum is SIGCHLD, do not receive notifi­
                     cation when child processes stop (i.e., when
                     child  processes  receive  one  of  SIGSTOP,
                     SIGTSTP, SIGTTIN or SIGTTOU).

              SA_ONESHOT or SA_RESETHAND
                     Restore  the  signal  action  to the default
                     state  once  the  signal  handler  has  been
                     called.   (This  is  the default behavior of
                     the signal(2) system call.)

              SA_RESTART
                     Provide behaviour compatible with BSD signal
                     semantics  by  making  certain  system calls
                     restartable across signals.

              SA_NOMASK or SA_NODEFER
                     Do  not  prevent  the  signal   from   being
                     received from within its own signal handler.

              SA_SIGINFO
                     The signal handler takes  3  arguments,  not
                     one.   In  this case, sa_sigaction should be
                     set instead of sa_handler.   (The  sa_sigac­
                     tion field was added in Linux 2.1.86.)

       The  siginfo_t  parameter to sa_sigaction is a struct with
       the following elements

              siginfo_t {
                  int      si_signo;  /* Signal number */
                  int      si_errno;  /* An errno value */
                  int      si_code;   /* Signal code */
                  pid_t    si_pid;    /* Sending process ID */
                  uid_t    si_uid;    /* Real user ID of sending process */
                  int      si_status; /* Exit value or signal */
                  clock_t  si_utime;  /* User time consumed */
                  clock_t  si_stime;  /* System time consumed */
                  sigval_t si_value;  /* Signal value */
                  int      si_int;    /* POSIX.1b signal */
                  void *   si_ptr;    /* POSIX.1b signal */
                  void *   si_addr;   /* Memory location which caused fault */
                  int      si_band;   /* Band event */
                  int      si_fd;     /* File descriptor */
              }

       si_signo, si_errno and si_code are defined  for  all  sig­
       nals.   The rest of the struct may be a union, so that one
       in si_pid and si_uid.   SIGCHLD also fills  in  si_status,
       si_utime and si_stime.  si_int and si_ptr are specified by
       the  sender  of  the  POSIX.1b  signal.   SIGILL,  SIGFPE,
       SIGSEGV and SIGBUS fill in si_addr with the address of the
       fault.  SIGPOLL fills in si_band and si_fd.

       si_code indicates why this  signal  was  sent.   It  is  a
       value,  not  a bitmask.  The values which are possible for
       any signal are listed in this table:
       +------------------------------------+
       |              si_code               |
       +-----------+------------------------+
       |Value      | Signal origin          |
       +-----------+------------------------+
       |SI_USER    | kill, sigsend or raise |
       +-----------+------------------------+
       |SI_KERNEL  | The kernel             |
       +-----------+------------------------+
       |SI_QUEUE   | sigqueue               |
       +-----------+------------------------+
       |SI_TIMER   | timer expired          |
       +-----------+------------------------+
       |SI_MESGQ   | mesq state changed     |
       +-----------+------------------------+
       |SI_ASYNCIO | AIO completed          |
       +-----------+------------------------+
       |SI_SIGIO   | queued SIGIO           |
       +-----------+------------------------+
       +-------------------------------------+
       |               SIGILL                |
       +-----------+-------------------------+
       |ILL_ILLOPC | illegal opcode          |
       +-----------+-------------------------+
       |ILL_ILLOPN | illegal operand         |
       +-----------+-------------------------+
       |ILL_ILLADR | illegal addressing mode |
       +-----------+-------------------------+
       |ILL_ILLTRP | illegal trap            |
       +-----------+-------------------------+
       |ILL_PRVOPC | privileged opcode       |
       +-----------+-------------------------+
       |ILL_PRVREG | privileged register     |
       +-----------+-------------------------+
       |ILL_COPROC | coprocessor error       |
       +-----------+-------------------------+
       |ILL_BADSTK | internal stack error    |
       +-----------+-------------------------+



       |                   SIGFPE                     |
       +-----------+----------------------------------+
       |FPE_INTDIV | integer divide by zero           |
       +-----------+----------------------------------+
       |FPE_INTOVF | integer overflow                 |
       +-----------+----------------------------------+
       |FPE_FLTDIV | floating point divide by zero    |
       +-----------+----------------------------------+
       |FPE_FLTOVF | floating point overflow          |
       +-----------+----------------------------------+
       |FPE_FLTUND | floating point underflow         |
       +-----------+----------------------------------+
       |FPE_FLTRES | floating point inexact result    |
       +-----------+----------------------------------+
       |FPE_FLTINV | floating point invalid operation |
       +-----------+----------------------------------+
       |FPE_FLTSUB | subscript out of range           |
       +-----------+----------------------------------+
       +----------------------------------------------------+
       |                      SIGSEGV                       |
       +------------+---------------------------------------+
       |SEGV_MAPERR | address not mapped to object          |
       +------------+---------------------------------------+
       |SEGV_ACCERR | invalid permissions for mapped object |
       +------------+---------------------------------------+
       +--------------------------------------------+
       |                  SIGBUS                    |
       +-----------+--------------------------------+
       |BUS_ADRALN | invalid address alignment      |
       +-----------+--------------------------------+
       |BUS_ADRERR | non-existant physical address  |
       +-----------+--------------------------------+
       |BUS_OBJERR | object specific hardware error |
       +-----------+--------------------------------+
       +--------------------------------+
       |            SIGTRAP             |
       +-----------+--------------------+
       |TRAP_BRKPT | process breakpoint |
       +-----------+--------------------+
       |TRAP_TRACE | process trace trap |
       +-----------+--------------------+



       |                  SIGCHLD                   |
       +--------------+-----------------------------+
       |CLD_EXITED    | child has exited            |
       +--------------+-----------------------------+
       |CLD_KILLED    | child was killed            |
       +--------------+-----------------------------+
       |CLD_DUMPED    | child terminated abnormally |
       +--------------+-----------------------------+
       |CLD_TRAPPED   | traced child has trapped    |
       +--------------+-----------------------------+
       |CLD_STOPPED   | child has stopped           |
       +--------------+-----------------------------+
       |CLD_CONTINUED | stopped child has continued |
       +--------------+-----------------------------+
       +-----------------------------------------+
       |                SIGPOLL                  |
       +---------+-------------------------------+
       |POLL_IN  | data input available          |
       +---------+-------------------------------+
       |POLL_OUT | output buffers available      |
       +---------+-------------------------------+
       |POLL_MSG | input message available       |
       +---------+-------------------------------+
       |POLL_ERR | i/o error                     |
       +---------+-------------------------------+
       |POLL_PRI | high priority input available |
       +---------+-------------------------------+
       |POLL_HUP | device disconnected           |
       +---------+-------------------------------+

       The sigprocmask call is used to change the  list  of  cur­
       rently  blocked  signals.  The  behaviour  of  the call is
       dependent on the value of how, as follows.

              SIG_BLOCK
                     The set of blocked signals is the  union  of
                     the current set and the set argument.

              SIG_UNBLOCK
                     The signals in set are removed from the cur­
                     rent set of blocked signals.  It is legal to
                     attempt  to  unblock  a  signal which is not
                     blocked.

              SIG_SETMASK
                     The set of blocked signals  is  set  to  the
                     argument set.

       If  oldset  is  non-null, the previous value of the signal
       mask is stored in oldset.

       The sigpending call allows the examination of pending sig­

       The sigsuspend call temporarily replaces the  signal  mask
       for  the process with that given by mask and then suspends
       the process until a signal is received.



RETURN VALUES

       sigaction, sigprocmask, sigpending and sigsuspend return 0
       on success and -1 on error.



ERRORS

       EINVAL An invalid signal was specified.  This will also be
              generated if an  attempt  is  made  to  change  the
              action  for  SIGKILL  or  SIGSTOP,  which cannot be
              caught.

       EFAULT act, oldact, set or oldset point to memory which is
              not a valid part of the process address space.

       EINTR  System call was interrupted.



NOTES

       It  is  not  possible to block SIGKILL or SIGSTOP with the
       sigprocmask call.  Attempts to  do  so  will  be  silently
       ignored.

       According  to  POSIX,  the behaviour of a process is unde­
       fined after it ignores a SIGFPE, SIGILL, or SIGSEGV signal
       that  was not generated by the kill() or the raise() func­
       tions.  Integer division by zero has undefined result.  On
       some  architectures  it  will  generate  a  SIGFPE signal.
       (Also dividing the most negative integer by -1 may  gener­
       ate  SIGFPE.)   Ignoring this signal might lead to an end­
       less loop.

       POSIX (B.3.3.1.3) disallows setting the action for SIGCHLD
       to  SIG_IGN.   The BSD and SYSV behaviours differ, causing
       BSD software that sets the action for SIGCHLD  to  SIG_IGN
       to fail on Linux.

       The  POSIX  spec  only defines SA_NOCLDSTOP.  Use of other
       sa_flags is non-portable.

       The SA_RESETHAND flag is compatible with the SVr4 flag  of
       the same name.

       The  SA_NODEFER  flag  is compatible with the SVr4 flag of
       the same name under kernels 1.3.9  and  newer.   On  older
       kernels  the  Linux  implementation allowed the receipt of
       any signal, not just the one  we  are  installing  (effec­
       ity  are  present  only  in  library  versions  3.0.9  and
       greater.

       The SA_SIGINFO flag is specified by POSIX.1b.  Support for
       it was added in Linux 2.2.

       sigaction can be called with a  null  second  argument  to
       query  the  current signal handler. It can also be used to
       check whether a given signal  is  valid  for  the  current
       machine  by  calling  it  with null second and third argu­
       ments.

       See sigsetops(3) for details on manipulating signal  sets.


CONFORMING TO

       POSIX,  SVr4.  SVr4 does not document the EINTR condition.



UNDOCUMENTED

       Before the introduction of SA_SIGINFO it was also possible
       to  get  some  additional  information,  namely by using a
       sa_handler with second argument of type struct sigcontext.
       See  the relevant kernel sources for details.  This use is
       obsolete now.



SEE ALSO

       kill(1), kill(2), killpg(2), pause(2), raise(3), siginter­
       rupt(3), signal(2), signal(7), sigsetops(3), sigvec(2)