SIGACTION(2)        Linux Programmer's Manual        SIGACTION(2)



NAME

       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
       the SA_NODEFER or SA_NOMASK flags are used.



Linux 2.4                 August 2, 2000                        1





SIGACTION(2)        Linux Programmer's Manual        SIGACTION(2)


       sa_flags  specifies  a  set  of  flags  which  modify  the
       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
       should only read the fields that are  meaningful  for  the



Linux 2.4                 August 2, 2000                        2





SIGACTION(2)        Linux Programmer's Manual        SIGACTION(2)


       given  signal.  kill(2), POSIX.1b signals and SIGCHLD fill
       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: tab(:) allbox; c s  l
       l.   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

       tab(:) allbox; c s l l.  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

       tab(:) allbox; c s l l.  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

       tab(:)  allbox;  c s l l.  SIGSEGV SEGV_MAPERR:address not
       mapped  to  object  SEGV_ACCERR:invalid  permissions   for
       mapped object

       tab(:) allbox; c s l l.  SIGBUS BUS_ADRALN:invalid address
       alignment   BUS_ADRERR:non-existant    physical    address
       BUS_OBJERR:object specific hardware error

       tab(:) allbox; c s l l.  SIGTRAP TRAP_BRKPT:process break-
       point TRAP_TRACE:process trace trap

       tab(:) allbox; c s  l  l.   SIGCHLD  CLD_EXITED:child  has
       exited CLD_KILLED:child was killed CLD_DUMPED:child termi-
       nated  abnormally  CLD_TRAPPED:traced  child  has  trapped
       CLD_STOPPED:child  has stopped CLD_CONTINUED:stopped child
       has continued

       tab(:) allbox; c s l l.  SIGPOLL POLL_IN:data input avail-
       able POLL_OUT:output buffers available POLL_MSG:input mes-
       sage 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.



Linux 2.4                 August 2, 2000                        3





SIGACTION(2)        Linux Programmer's Manual        SIGACTION(2)


              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-
       nals (ones which have been  raised  while  blocked).   The
       signal mask of pending signals is stored in set.

       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 VALUE

       The  functions sigaction, sigprocmask, sigpending and sig-
       suspend return 0 on success and -1 on error.  (In the case
       of sigsuspend there will be no success, and only the error
       return with EINTR is possible.)



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



Linux 2.4                 August 2, 2000                        4





SIGACTION(2)        Linux Programmer's Manual        SIGACTION(2)


       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-
       tively overriding any sa_mask settings).

       The SA_RESETHAND and SA_NODEFER names for SVr4 compatibil-
       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)





Linux 2.4                 August 2, 2000                        5