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  syn-
     chronously  generated.   Synchronously generated signals are
     initiated by a specific thread and are delivered to and han-
     dled 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 action

SunOS 5.11           Last change: 5 Feb 2008                    1


Headers                                           signal.h(3HEAD)

              is installed for  a  specific  signal,  it  usually
              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 asynchro-
     nously 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 partic-
     ular 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

SunOS 5.11           Last change: 5 Feb 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

SunOS 5.11           Last change: 5 Feb 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.

     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.

SunOS 5.11           Last change: 5 Feb 2008                    4


Headers                                           signal.h(3HEAD)

     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
     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:

SunOS 5.11           Last change: 5 Feb 2008                    5


Headers                                           signal.h(3HEAD)

             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 mechanism
     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
                     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.

SunOS 5.11           Last change: 5 Feb 2008                    6


Headers                                           signal.h(3HEAD)

     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
     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:

SunOS 5.11           Last change: 5 Feb 2008                    7


Headers                                           signal.h(3HEAD)

     ____________________________________________________________
    |       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
     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.

SunOS 5.11           Last change: 5 Feb 2008                    8


Headers                                           signal.h(3HEAD)

     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.

SunOS 5.11           Last change: 5 Feb 2008                    9


Man(1) output converted with man2html


FhG Schily's Home VED powered