Reformatting page.  Please Wait... done


Headers                                           SIGNAL.H(3HEAD)


NAME
     signal.h, signal - base signals

SYNOPSIS
     #include <signal.h>


DESCRIPTION
     A signal is an asynchronous notification of an event. A sig-
     nal  is said to be generated for (or sent to) a process when
     the event associated with that signal first occurs. Examples
     of such events include hardware faults, timer expiration and
     terminal activity, as well as the invocation of the  kill(2)
     or  sigsend(2)  functions.  In  some circumstances, the same
     event generates signals for multiple  processes.  A  process
     may  request  a  detailed  notification of the source of the
     signal  and  the  reason   why   it   was   generated.   See
     siginfo.h(3HEAD).


     Signals can be generated  synchronously  or  asynchronously.
     Events directly caused by the execution of code by a thread,
     such as a reference to an unmapped, protected, or bad memory
     can  generate  SIGSEGV or SIGBUS; a floating point exception
     can  generate  SIGFPE;  and  the  execution  of  an  illegal
     instruction can generate SIGILL. Such events are referred to
     as traps; signals generated by traps are said to be synchro-
     nously  generated.  Synchronously generated signals are ini-
     tiated by a specific thread and are delivered to and handled
     by that thread.


     Signals may also be generated by calling kill(), sigqueue(),
     or  sigsend().  Events  such as keyboard interrupts generate
     signals, such as SIGINT, which are sent to the  target  pro-
     cess.  Such  events  are  referred to as interrupts; signals
     generated by interrupts are said to be  asynchronously  gen-
     erated. Asynchronously generated signals are not directed to
     a particular thread but are handled by an  arbitrary  thread
     that meets either of the following conditions:

         o    The thread is blocked in a call to sigwait(2) whose
              argument includes the type of signal generated.

         o    The thread has a signal mask that does not  include
              the     type     of     signal    generated.    See
              pthread_sigmask(3C). Each  process  can  specify  a
              system  action to be taken in response to each sig-
              nal sent to it, called  the  signal's  disposition.
              All  threads  in the process share the disposition.
              The set of system signal actions for a  process  is
              initialized  from  that  of  its  parent.   Once an


Illumos             Last change: Feb 5, 2008                    1


Headers                                           SIGNAL.H(3HEAD)


              action is installed for a specific signal, it  usu-
              ally remains installed until another disposition is
              explicitly requested by a  call  to  either  sigac-
              tion(), signal() or  sigset(), or until the process
              execs(). See sigaction(2) and  signal(3C).  When  a
              process  execs,  all  signals whose disposition has
              been set  to  catch  the  signal  will  be  set  to
              SIG_DFL.  Alternatively, a process may request that
              the system automatically reset the disposition of a
              signal  to   SIG_DFL  after it has been caught. See
              sigaction(2) and signal(3C).

  SIGNAL DELIVERY
     A signal is said to be delivered to a process when a  thread
     within  the  process  takes  the appropriate action for  the
     disposition of the signal.  Delivery  of  a  signal  can  be
     blocked.  There  are  two methods for handling delivery of a
     signal in a  multithreaded  application.  The  first  method
     specifies a signal handler function to execute when the sig-
     nal is received by the process. See sigaction(2). The second
     method  uses  sigwait(2)  to  create  a thread to handle the
     receipt of the signal. The sigaction() function can be  used
     for both synchronously and asynchronously generated signals.
     The sigwait() function will  work  only  for  asynchronously
     generated  signals,  as  synchronously generated signals are
     sent to the thread that  caused  the  event.  The  sigwait()
     function  is  the  recommended  for use with a multithreaded
     application.

  SIGNAL MASK
     Each thread has a signal mask  that defines the set of  sig-
     nals  currently blocked from delivery to it. The signal mask
     of the main thread is inherited from the signal mask of  the
     thread  that created it in the parent process. The selection
     of the thread  within  the  process  that  is  to  take  the
     appropriate  action for the signal is based on the method of
     signal generation and the signal masks of the threads in the
     receiving process. Signals that are generated by action of a
     particular thread such as hardware faults are  delivered  to
     the  thread  that caused the signal. See pthread_sigmask(3C)
     or sigprocmask(2). See alarm(2)  for  current  semantics  of
     delivery of SIGALRM. Signals that are directed to a particu-
     lar thread   are  delivered  to  the  targeted  thread.  See
     pthread_kill(3C).  If  the  selected  thread has blocked the
     signal, it  remains  pending  on  the  thread  until  it  is
     unblocked.   For  all other types of signal generation  (for
     example, kill(2)sigsend(2), terminal activity,  and  other
     external  events  not ascribable to a particular thread) one
     of the threads that does not  have  the  signal  blocked  is
     selected  to  process  the signal. If all the threads within
     the process block the signal, it remains pending on the pro-
     cess  until  a  thread  in  the  process unblocks it. If the


Illumos             Last change: Feb 5, 2008                    2


Headers                                           SIGNAL.H(3HEAD)


     action associated with a signal is set to ignore the  signal
     then  both currently pending and subsequently generated sig-
     nals of this type are discarded immediately  for  this  pro-
     cess.


     The determination of which action is taken in response to  a
     signal   is  made  at  the time the signal is delivered to a
     thread within the process, allowing for  any  changes  since
     the  time of generation.   This determination is independent
     of the means by which the signal was originally generated.


     The signals currently defined by <signal.h> are as follows:


         Name       Value   Default                   Event
     SIGHUP         1       Exit      Hangup (see termio(7I))
     SIGINT         2       Exit      Interrupt (see termio(7I))
     SIGQUIT        3       Core      Quit (see termio(7I))
     SIGILL         4       Core      Illegal Instruction
     SIGTRAP        5       Core      Trace or Breakpoint Trap
     SIGABRT        6       Core      Abort
     SIGEMT         7       Core      Emulation Trap
     SIGFPE         8       Core      Arithmetic Exception
     SIGKILL        9       Exit      Killed
     SIGBUS         10      Core      Bus Error
     SIGSEGV        11      Core      Segmentation Fault
     SIGSYS         12      Core      Bad System Call
     SIGPIPE        13      Exit      Broken Pipe
     SIGALRM        14      Exit      Alarm Clock
     SIGTERM        15      Exit      Terminated
     SIGUSR1        16      Exit      User Signal 1
     SIGUSR2        17      Exit      User Signal 2
     SIGCHLD        18      Ignore    Child Status Changed
     SIGPWR         19      Ignore    Power Fail or Restart
     SIGWINCH       20      Ignore    Window Size Change
     SIGURG         21      Ignore    Urgent Socket Condition
     SIGPOLL        22      Exit      Pollable Event (see streamio(7I))
     SIGSTOP        23      Stop      Stopped (signal)
     SIGTSTP        24      Stop      Stopped (user) (see termio(7I))
     SIGCONT        25      Ignore    Continued
     SIGTTIN        26      Stop      Stopped (tty input) (see termio(7I))
     SIGTTOU        27      Stop      Stopped (tty output) (see termio(7I))
     SIGVTALRM      28      Exit      Virtual Timer Expired
     SIGPROF        29      Exit      Profiling Timer Expired
     SIGXCPU        30      Core      CPU   time   limit   exceeded    (see
                                      getrlimit(2))
     SIGXFSZ        31      Core      File   size   limit   exceeded   (see
                                      getrlimit(2))
     SIGWAITING     32      Ignore    Reserved


Illumos             Last change: Feb 5, 2008                    3


Headers                                           SIGNAL.H(3HEAD)


     SIGLWP         33      Ignore    Reserved
     SIGFREEZE      34      Ignore    Check point Freeze
     SIGTHAW        35      Ignore    Check point Thaw
     SIGCANCEL      36      Ignore    Reserved for threading support
     SIGLOST        37      Exit      Resource lost (for  example,  record-
                                      lock lost)
     SIGXRES        38      Ignore    Resource   control   exceeded    (see
                                      setrctl(2))
     SIGJVM1        39      Ignore    Reserved for Java Virtual Machine 1
     SIGJVM2        40      Ignore    Reserved for Java Virtual Machine 2
     SIGRTMIN       *       Exit      First real time signal
     (SIGRTMIN+1)   *       Exit      Second real time signal
     ...
     (SIGRTMAX-1)   *       Exit      Second-to-last real time signal
     SIGRTMAX       *       Exit      Last real time signal


     The symbols SIGRTMIN through SIGRTMAX are evaluated  dynami-
     cally to permit future configurability.


     Applications should  not  use  any  of  the  signals  marked
     "reserved"  in  the  above  table  for any purpose, to avoid
     interfering with their use by the system.

  SIGNAL DISPOSITION
     A process using a  signal(3C),  sigset(3C)  or  sigaction(2)
     system call can specify one of three dispositions for a sig-
     nal: take the default action for the signal, ignore the sig-
     nal, or catch the signal.

  Default Action: SIG_DFL
     A disposition of  SIG_DFL specifies the default action.  The
     default  action for each signal is listed in the table above
     and is selected from the following:

     Exit
               When it gets the signal, the receiving process  is
               to  be  terminated  with all the consequences out-
               lined in exit(2).


     Core
               When it gets the signal, the receiving process  is
               to  be  terminated  with all the consequences out-
               lined in exit(2). In addition, a ``core image'' of
               the process is constructed in the  current working
               directory.


Illumos             Last change: Feb 5, 2008                    4


Headers                                           SIGNAL.H(3HEAD)


     Stop
               When it gets the signal, the receiving process  is
               to  stop.  When  a  process  is  stopped,  all the
               threads within the process also stop executing.


     Ignore
               When it gets the signal, the receiving process  is
               to  ignore  it.  This  is identical to setting the
               disposition to SIG_IGN.


  Ignore Signal: SIG_IGN
     A disposition of SIG_IGN specifies that the signal is to  be
     ignored.   Setting  a  signal action to SIG_IGN for a signal
     that is pending causes the pending signal to  be  discarded,
     whether  or not it is blocked. Any queued values pending are
     also discarded, and the resources used  to  queue  them  are
     released and made available to queue other signals.

  Catch Signal: function address
     A disposition that is a  function  address  specifies  that,
     when  it gets the signal, the thread within the process that
     is selected to process the signal will  execute  the  signal
     handler  at  the  specified  address.  Normally,  the signal
     handler is passed the signal number as its only argument. If
     the disposition was set with the sigaction(2) function, how-
     ever, additional arguments can be requested. When the signal
     handler  returns, the receiving process resumes execution at
     the point it was  interrupted,  unless  the  signal  handler
     makes  other arrangements. If an invalid function address is
     specified, results are undefined.


     If the disposition has been set with the sigset() or  sigac-
     tion(),  the  signal  is automatically blocked in the thread
     while it is executing the signal catcher. If a longjmp()  is
     used  to  leave  the signal catcher, then the signal must be
     explicitly unblocked by the user. See setjmp(3C)signal(3C)
     and sigprocmask(2).


     If execution of the  signal  handler  interrupts  a  blocked
     function  call,  the handler is executed and the interrupted
     function call returns  -1 to the calling process with  errno
     set  to  EINTR. If the SA_RESTART flag is set, however, cer-
     tain function calls will be transparently restarted.


     Some signal-generating functions, such  as  high  resolution
     timer expiration, asynchronous I/O completion, inter-process
     message arrival, and the sigqueue(3C) function, support  the


Illumos             Last change: Feb 5, 2008                    5


Headers                                           SIGNAL.H(3HEAD)


     specification of an application defined value, either expli-
     citly as a parameter to  the  function,  or  in  a  sigevent
     structure  parameter.  The  sigevent structure is defined by
     <signal.h> and contains at least the following members:


             Type                     Name                   Description
     _________________________________________________________________________
     int                     sigev_notify              Notification type
     int                     sigev_signo               Signal number
     _________________________________________________________________________
     union sigval            sigev_value               Signal value
     _________________________________________________________________________
     void(*)(union sigval)   sigev_notify_function     Notification function
     _________________________________________________________________________
     (pthread_attr_t *)      sigev_notify_attributes   Notification attributes


     The sigval union is defined  by  <signal.h>and  contains  at
     least the following members:


      Type      Name          Description
     _________________________________________
     int      sival_int   Integer signal value
     void *   sival_ptr   Pointer signal value


     The  sigev_notify member specifies the notification  mechan-
     ism   to   use   when  an  asynchronous  event  occurs.  The
     sigev_notify  member  may  be  defined  with  the  following
     values:

     SIGEV_NONE
                     No asynchronous  notification  is  delivered
                     when the event of interest occurs.


     SIGEV_SIGNAL
                     A queued signal, with  its  value  equal  to
                     sigev_signo,  is generated when the event of
                     interest occurs.


     SIGEV_THREAD
                     The sigev_notify_function  is  called,  with
                     sigev_value  as  its  argument,  to  perform
                     notification  when  the  asynchronous  event


Illumos             Last change: Feb 5, 2008                    6


Headers                                           SIGNAL.H(3HEAD)


                     occurs.  The  function  is  executed  in  an
                     environment as if it were the start  routine
                     for  a  newly  created  thread  with  thread
                     attributes    sigev_notify_attributes.    If
                     sigev_notify_attributes  is NULL, the thread
                     runs  as  a  detached  thread  with  default
                     attributes.  Otherwise, the thread runs with
                     the specified attributes, but as a  detached
                     thread  regardless. The thread runs with all
                     blockable signals blocked.


     SIGEV_PORT
                     An asynchronous notification is delivered to
                     an  event  port  when  the event of interest
                     occurs.  The  sigev_value.sival_ptr   member
                     points  to a port_notify_t structure defined
                     in <port.h>  (see  port_associate(3C)).  The
                     event   port   identifier   as  well  as  an
                     application-defined cookie are part  of  the
                     port_notify_t structure.


     The  sigev_signo  member  contains  the  application-defined
     value  to  be  passed  to  the signal-catching function (for
     notification type SIGEV_SIGNAL) at the time  of  the  signal
     delivery  as the si_value member of the siginfo_t structure,
     or as the argument to the notification function (for notifi-
     cation  type SIGEV_THREAD) that is called when the asynchro-
     nous  event  occurs.   For  notification  type   SIGEV_PORT,
     sigev_value.sival_ptr  points  to  a port_notify_t structure
     that specifies the port and an application-defined cookie.


     The sigev_value member references  the  application  defined
     value  to  be  passed to the signal-catching function at the
     time of the signal delivery as the si_value  member  of  the
     siginfo_t structure.


     The sival_int member is used when  the  application  defined
     value  is of type int, and the sival_ptr member is used when
     the application defined value is a pointer.


     When  a  signal  is  generated  by   sigqueue(3C)   or   any
     signal-generating  function which supports the specification
     of an application defined value, the signal is marked  pend-
     ing and, if the  SA_SIGINFO flag is set for that signal, the
     signal is queued to the process along with  the  application
     specified  signal  value. Multiple occurrences of signals so


Illumos             Last change: Feb 5, 2008                    7


Headers                                           SIGNAL.H(3HEAD)


     generated are queued in FIFO order. If the  SA_SIGINFO  flag
     is  not  set  for  that  signal,  later  occurrences of that
     signal's generation, when a signal is  already  queued,  are
     silently discarded.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:


     _________________________________________
    |   ATTRIBUTE TYPE   |   ATTRIBUTE VALUE |
    |____________________|___________________|
    | Interface Stability|  Committed        |
    |____________________|___________________|
    | Standard           |  See standards(5).|
    |____________________|___________________|


SEE ALSO
     lockd(1M),   Intro(2),    alarm(2),    exit(2),    fcntl(2),
     getrlimit(2),   ioctl(2),   kill(2),  pause(2),  setrctl(2),
     sigaction(2),  sigaltstack(2),  sigprocmask(2),  sigsend(2),
     sigsuspend(2),        sigwait(2),        port_associate(3C),
     pthread_create(3C),  pthread_kill(3C),  pthread_sigmask(3C),
     setjmp(3C),   siginfo.h(3HEAD),   signal(3C),  sigqueue(3C),
     sigsetops(3C)ucontext.h(3HEAD),  wait(3C),  attributes(5),
     standards(5)

NOTES
     The dispositions of the SIGKILL and SIGSTOP  signals  cannot
     be  altered  from their default values. The system generates
     an error if this is attempted.


     The  SIGKILL,  SIGSTOP,  and  SIGCANCEL  signals  cannot  be
     blocked. The system silently enforces this restriction.


     The SIGCANCEL signal cannot be  directed  to  an  individual
     thread  using pthread_kill(3C), but it can be sent to a pro-
     cess using kill(2)sigsend(2), or sigqueue(3C).


     Whenever a process receives a SIGSTOP, SIGTSTP, SIGTTIN,  or
     SIGTTOU  signal,  regardless of its disposition, any pending
     SIGCONT signal are discarded.


     Whenever a process receives a SIGCONT signal, regardless  of
     its  disposition, any pending SIGSTOP, SIGTSTP, SIGTTIN, and


Illumos             Last change: Feb 5, 2008                    8


Headers                                           SIGNAL.H(3HEAD)


     SIGTTOU signals is discarded. In addition,  if  the  process
     was stopped, it is continued.


     SIGPOLL is issued when a file descriptor corresponding to  a
     STREAMS file has a "selectable" event pending. See Intro(2).
     A process must specifically request that this signal be sent
     using  the  I_SETSIG ioctl call. Otherwise, the process will
     never receive SIGPOLL.


     If the disposition of the SIGCHLD signal has been  set  with
     signal()   or   sigset(),   or   with  sigaction()  and  the
     SA_NOCLDSTOP flag has been specified, it will only  be  sent
     to the calling process when its children exit; otherwise, it
     will also be sent when the calling  process's  children  are
     stopped or continued due to job control.


     The name SIGCLD is also defined in this header  and  identi-
     fies  the  same  signal  as  SIGCHLD. SIGCLD is provided for
     backward  compatibility,   new   applications   should   use
     SIGCHLD.


     The disposition of signals that  are  inherited  as  SIG_IGN
     should not be changed.


     Signals which are  generated  synchronously  should  not  be
     masked.  If  such  a  signal  is  blocked and delivered, the
     receiving process is killed.


Illumos             Last change: Feb 5, 2008                    9