sigaction(2)                                                   sigaction(2)




 NAME
      sigaction - examine and change signal action

 SYNOPSIS
      #include <signal.h>

      int sigaction (
           int sig,
           const struct sigaction *act,
           struct sigaction *oact
      );

 DESCRIPTION
      The sigaction() function allows the calling process to examine and/or
      specify the action to be associated with a specific signal. The
      argument sig specifies the signal; acceptable values are defined in
      <signal.h>.

      The structure sigaction, used to describe an  action to  be taken, is
      defined in the header <signal.h> to include at least the following
      members:

      Member Type                       Member Name    Description

      void(*)(int)                      sa_handler     SIG_DFL, SIG_IGN or
                                                       pointer to a
                                                       function.

      sigset_t                          sa_mask        Additional set of
                                                       signals to be
                                                       blocked during
                                                       execution of
                                                       signal-catching
                                                       function.

      int                               sa_flags       Special flags to
                                                       affect behavior of
                                                       signal.

      void(*)(int, siginfo_t*,void *)   sa_sigaction   signal-catching
                                                       function.

      If the argument act is not a null pointer, it points to a structure
      specifying the action to be associated with the specified  signal. If
      the argument oact is not a null pointer, the action previously
      associated with the signal is stored in the location pointed to by the
      argument oact.  If the argument act is a null pointer, signal handling
      is unchanged; thus, the call can be used to enquire about the current
      handling of a given  signal. The sa_handler field of the sigaction
      structure identifies the action to be associated with the specified
      signal. If the sa_handler field specifies a signal-catching function,



 Hewlett-Packard Company            - 1 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




      the sa_mask field identifies a set of signals that will be added to
      the process' signal mask before the signal-catching function is
      invoked. The SIGKILL and SIGSTOP signals will not be added to the
      signal mask using this mechanism; this restriction will be enforced by
      the system without causing an error to be indicated.

      The sa_flags field can be used to modify the behaviour of the
      specified signal.  The following flags, defined in the header
      <signal.h>, can be set in sa_flags:

           SA_NOCLDSTOP           Do not generate SIGCHLD when children
                                  stop.

           SA_ONSTACK             If set and an alternate signal stack has
                                  been declared with sigaltstack() or
                                  sigstack(), the signal will be delivered
                                  to the calling process on that stack.
                                  Otherwise, the signal will be delivered on
                                  the current stack.

           SA_RESETHAND           If set, the disposition of the signal will
                                  be reset to SIG_DFL and the SA_SIGINFO
                                  flag will be cleared on entry to the
                                  signal handler (Note: SIGILL and SIGTRAP
                                  cannot be automatically reset when
                                  delivered; the system silently enforces
                                  this restriction). Otherwise, the
                                  disposition of the signal will not be
                                  modified on entry to the signal handler.
                                  In addition, if this flag is set,
                                  sigaction() behaves as if the SA_NODEFER
                                  flag  were  also set.

           SA_RESTART             This flag affects the behaviour of
                                  interruptible functions; that is, those
                                  specified to fail with errno set to EINTR.
                                  If set, and a function specified as
                                  interruptible is interrupted by this
                                  signal, the function will restart and will
                                  not fail with EINTR unless otherwise
                                  specified. If the flag is not set,
                                  interruptible functions interrupted by
                                  this signal will fail with errno set to
                                  EINTR.

           SA_SIGINFO             If cleared and the signal is caught, the
                                  signal-catching function will be entered
                                  as:

                                  void func(int signo); where signo is the
                                  only argument to the signal catching



 Hewlett-Packard Company            - 2 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




                                  function.  In this case the sa_handler
                                  member must be used to describe the signal
                                  catching function and the application must
                                  not modify the sa_sigaction member.

                                  If SA_SIGINFO is set and the signal is
                                  caught, the signal-catching function will
                                  be entered as:

                                  void func(int signo, siginfo_t *info, void
                                  *context); where two additional arguments
                                  are passed to the signal catching
                                  function. If the second argument is not a
                                  null pointer, it will point to an object
                                  of type siginfo_t explaining the reason
                                  why the signal was generated; the third
                                  argument can be cast to a pointer to an
                                  object of type ucontext_t to refer to the
                                  receiving process' context that was
                                  interrupted when the signal was delivered.
                                  In this case the sa_sigaction member must
                                  be used to describe the signal catching
                                  function and the application must not
                                  modify the sa_handler member.

                                  The si_signo member contains the
                                  system-generated signal number.

                                  The si_errno member may contain
                                  implementation-dependent additional error
                                  information; if non-zero, it contains an
                                  error number identifying the condition
                                  that caused the signal to be generated.

                                  The si_code member contains a code
                                  identifying the cause of the signal. If
                                  the value of si_code is less than or equal
                                  to 0, then the signal was generated by a
                                  process and si_pid and si_uid respectively
                                  indicate the process ID and the real user
                                  ID of the sender. The values of si_pid and
                                  si_uid are otherwise meaningless.

           SA_NOCLDWAIT           If set, and sig equals SIGCHLD, child
                                  processes of the calling processes will
                                  not be transformed into zombie processes
                                  when they terminate. If the calling
                                  process subsequently waits for its
                                  children, and the process has no unwaited
                                  for children that were transformed into
                                  zombie processes, it will block until all



 Hewlett-Packard Company            - 3 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




                                  of its children terminate, and wait(),
                                  wait3(), waitid(), and waitpid() will fail
                                  and set errno to ECHILD.  Otherwise,
                                  terminating child processes will be
                                  transformed into zombie processes, unless
                                  SIGCHLD is set to SIG_IGN.

           SA_NODEFER             If set and sig is caught, sig will not be
                                  added to the process' signal mask on entry
                                  to the signal handler unless it is
                                  included in sa_mask.  Otherwise, sig will
                                  always be added to the process' signal
                                  mask on entry to the signal handler.

      If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags,
      and the implementation supports the SIGCHLD signal, then a SIGCHLD
      signal will be generated for the calling process whenever any of its
      child processes stop. If sig is SIGCHLD and the SA_NOCLDSTOP flag is
      set in sa_flags, then the implementation will not generate a SIGCHLD
      signal in this way.

      When a signal is caught by a signal-catching function installed by
      sigaction(), a new signal mask is calculated and installed for the
      duration of the signal-catching function (or until a call to either
      sigprocmask() or sigsuspend() is made). This mask is formed by taking
      the union of the current signal mask and the value of the sa_mask for
      the signal being delivered unless SA_NODEFER or SA_RESETHAND is set,
      and then including the signal being delivered.  If and when the user's
      signal handler returns normally, the original signal mask is restored.

      Once an action is installed for a specific signal, it remains
      installed until another action is explicitly requested (by another
      call to sigaction()), until the SA_RESETHAND flag causes resetting of
      the handler, or until one of the exec functions is called.

      If the previous action for sig had been established by signal(), the
      values of the fields returned in the structure pointed to by oact are
      unspecified, and in particular oact->sa_handler is not necessarily the
      same value passed to signal().  However, if a pointer to the same
      structure or a copy thereof is passed to a subsequent call to
      sigaction() via the act argument, handling of the signal will be as if
      the original call to signal() were repeated.

      If sigaction() fails, no new signal handler is installed.

      It is unspecified whether an attempt to set the action for a signal
      that cannot be caught or ignored to SIG_DFL is ignored or causes an
      error to be returned with errno set to EINVAL.

      A signal is said to be generated for (or sent to) a process when the
      event that causes the signal first occurs. Examples of such events



 Hewlett-Packard Company            - 4 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




      include detection of hardware faults, timer expiration and terminal
      activity, as well as the invocation of kill().  In some circumstances,
      the same event generates signals for multiple processes.

      Each process has an action to be taken in response to each signal
      defined by the system (see Signal Actions). A signal is said to be
      delivered to a process when the appropriate action for the process and
      signal is taken.

      During the time between the generation of a signal and its delivery,
      the signal is said to be pending.  Ordinarily, this interval cannot be
      detected by an application. However, a signal can be blocked from
      delivery to a process. If the action associated with a blocked signal
      is anything other than to ignore the signal, and if that signal is
      generated for the process, the signal will remain pending until either
      it is unblocked or the action associated with it is set to ignore the
      signal.  If the action associated with a blocked signal is to ignore
      the signal and if that signal is generated for the process, it is
      unspecified whether the signal is discarded immediately upon
      generation or remains pending.

      Each process has a signal mask that defines the set of signals
      currently blocked from delivery to it.  The signal mask for a process
      is initialised from that of its parent. The sigaction(),
      sigprocmask(), and sigsuspend() functions control the manipulation of
      the signal mask.

      The determination of which action is taken in response to a signal is
      made at the time the signal is delivered, allowing for any changes
      since the time of generation.  This determination is independent of
      the means by which the signal was originally generated.  If a
      subsequent occurrence of a pending signal is generated, it is
      implementation-dependent as to whether the signal is delivered more
      than once.  The order in which multiple, simultaneously pending
      signals are delivered to a process is unspecified.

      When any stop signal ( SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is
      generated for a process, any pending SIGCONT signals for that process
      will be discarded.  Conversely, when SIGCONT is generated for a
      process, all pending stop signals for that process will be discarded.
      When SIGCONT is generated for a process that is stopped, the process
      will be continued, even if the SIGCONT signal is blocked or ignored.
      If SIGCONT is blocked and not ignored, it will remain pending until it
      is either unblocked or a stop signal is generated for the process.

      An implementation will document any condition not specified by this
      document under which the implementation generates signals.

      Signal Actions





 Hewlett-Packard Company            - 5 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




      There are three types of action that can be associated with a signal:
      SIG_DFL, SIG_IGN or a pointer to a function. Initially, all signals
      will be set to SIG_DFL or SIG_IGN prior to entry of the main() routine
      (see the exec functions). The actions prescribed by these values are
      as follows:

      SIG_DFL- signal-specific default action

           o  The default actions for the signals defined in this document
              are specified under <signal.h>.

           o  If the default action is to stop the process, the execution of
              that process is temporarily suspended. When a process stops, a
              SIGCHLD signal will be generated for its parent process,
              unless the parent process has set the SA_NOCLDSTOP flag.
              While a process is stopped, any additional signals that are
              sent to the process will not be delivered until the process is
              continued, except SIGKILL which always terminates the
              receiving process.  A process that is a member of an orphaned
              process group will not be allowed to stop in response to the
              SIGTSTP, SIGTTIN, or SIGTTOU signals.  In cases where delivery
              of one of these signals would stop such a process, the signal
              will be discarded.

           o  Setting a signal action to SIG_DFL for a signal that is
              pending, and whose default action is to ignore the signal (for
              example, SIGCHLD), will cause the pending signal to be
              discarded, whether or not it is blocked.

      SIG_IGN - ignore signal

           o  Delivery of the signal will have no effect on the process. The
              behaviour of a process is undefined after it ignores a SIGFPE,
              SIGILL, or SIGSEGV signal that was not generated by kill() or
              raise().

           o  The system will not allow the action for the signals SIGKILL
              or SIGSTOP to be set to SIG_IGN.

           o  Setting a signal action to SIG_IGN for a signal that is
              pending will cause the pending signal to be discarded, whether
              or not it is blocked.

           o  If a process sets the action for the SIGCHLD signal to
              SIG_IGN, the behaviour is unspecified, except as specified
              below.

              If the action for the SIGCHLD signal is set to SIG_IGN, child
              processes of the calling processes will not be transformed
              into zombie processes when they terminate. If the calling
              process subsequently waits for its children, and the process



 Hewlett-Packard Company            - 6 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




              has no unwaited for children that were transformed into zombie
              processes, it will block until all of its children terminate,
              and wait(), wait3(), waitid(), and waitpid() will fail and set
              errno to ECHILD.

      Pointer to a function - catch signal

           o  On delivery of the signal, the receiving process is to execute
              the signal-catching function at the specified address. After
              returning from the signal-catching function, the receiving
              process will resume execution at the point at which it was
              interrupted.

           o  If SA_SIGINFO is cleared, the signal- catching function will
              be entered as:

              void func(int signo);

           where func is the specified signal-catching function and signo is
           the signal number of the signal being delivered.

           o  If SA_SIGINFO is set, the signal-catching function will be
              entered as:

              void func(int signo, siginfo_t *siginfo, void

           where func is the specified signal-catching function, signo is
           the signal number of the signal being delivered, siginfo points
           to an object of type siginfo_t associated with the signal being
           delivered, and ucontextptr points to a ucontext_t.

           o  The behaviour of a process is undefined after it returns
              normally from a signal- catching function for a SIGBUS,
              SIGFPE, SIGILL, or SIGSEGV signal that was not generated by
              kill() or raise().

           o  The system will not allow a process to catch the signals
              SIGKILL and SIGSTOP.

           o  If a process establishes a signal-catching function for the
              SIGCHLD signal while it has a terminated child process for
              which it has not waited, it is unspecified whether a SIGCHILD
              signal is generated to indicate that child process.

           o  When signal-catching functions are invoked asynchronously with
              process execution, the behaviour of some of the functions
              defined by this document is unspecified if they are called
              from a signal-catching function.

              The following table defines a set of functions that are either
              reentrant or not interruptible by signals.  Therefore



 Hewlett-Packard Company            - 7 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




              applications may invoke them, without restriction, from
              signal-catching functions:

              access()        fstat()       read()          sysconf()
              alarm()         getegid()     rename()        tcdrain()
              cfgetispeed()   geteuid()     rmdir()         tcflow()
              cfgetospeed()   getgid()      setgid()        tcflush()
              cfsetispeed()   getgroups()   setpgid()       tcgetattr()
              cfsetospeed()   getpgrp()     setsid()        tcgetpgrp()
              chdir()         getpid()      setuid()        tcsendbreak()
              chmod()         getppid()     sigaction()     tcsetattr()
              chown()         getuid()      sigaddset()     tcsetpgrp()
              close()         kill()        sigdelset()     time()
              creat()         link()        sigemptyset()   times()
              dup2()          lseek()       sigfillset()    umask()
              dup()           mkdir()       sigismember()   uname()
              execle()        mkfifo()      signal()        unlink()
              execve()        open()        sigpending()    utime()
              _exit()         pathconf()    sigprocmask()   wait()
              fcntl()         pause()       sigsuspend()    waitpid()
              fork()          pipe()        sleep()         write()
              fpathconf()     raise()       stat()

           All functions not in the above table are considered to be unsafe
           with respect to signals. In the presence of signals, all
           functions defined by this document will behave as defined when
           called from or interrupted by a signal-catching function, with a
           single exception: when a signal interrupts an unsafe function and
           the signal-catching function calls an unsafe function, the
           behaviour is undefined.

      Signal Effects on Other Functions

      Signals affect the behaviour of certain functions defined by this
      document if delivered to a process while it is executing such a
      function. If the action of the signal is to terminate the process, the
      process will be terminated and the function will not return. If the
      action of the signal is to stop the process, the process will stop
      until continued or terminated. Generation of a SIGCONT signal for the
      process causes the process to be continued, and the original function
      will continue at the point the process was stopped. If the action of
      the signal is to invoke a signal-catching function, the signal-
      catching function will be invoked; in this case the original function
      is said to be interrupted by the signal. If the signal-catching
      function executes a return statement, the behaviour of the interrupted
      function will be as described individually for that function. Signals
      that are ignored will not affect the behaviour of any function;
      signals that are blocked will not affect the behaviour of any function
      until they are unblocked and then delivered.





 Hewlett-Packard Company            - 8 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




 RETURN VALUE
      Upon successful completion, sigaction() returns 0. Otherwise -1 is
      returned, errno is set to indicate the error and no new signal-
      catching function will be installed.

 ERRORS
      The sigaction() function will fail if:

           [EINVAL]                 The sig argument is not a valid signal
                                    number or an attempt is made to catch a
                                    signal that cannot be caught or ignore a
                                    signal that cannot be ignored.

      The sigaction() function may fail if:

           [EINVAL]                 An attempt was made to set the action to
                                    SIG_DFL for a signal that cannot be
                                    caught or ignored (or both).

 APPLICATION USAGE
      The sigaction() function supersedes the signal() interface, and should
      be used in preference.  In particular, sigaction() and signal() should
      not be used in the same process to control the same signal.  The
      behaviour of reentrant functions, as defined in the description, is as
      specified by this document, regardless of invocation from a signal-
      catching function. This is the only intended meaning of the statement
      that reentrant functions may be used in signal-catching functions
      without restrictions.  Applications must still consider all effects of
      such functions on such things as data structures, files and process
      state. In particular, application writers need to consider the
      restrictions on interactions when interrupting sleep() and
      interactions among multiple handles for a file description. The fact
      that any specific function is listed as reentrant does not necessarily
      mean that invocation of that function from a signal-catching function
      is recommended.

      In order to prevent errors arising from interrupting non-reentrant
      function calls, applications should protect calls to these functions
      either by blocking the appropriate signals or through the use of some
      programmatic semaphore. This document does not address the more
      general problem of synchronising access to shared data structures.
      Note in particular that even the "safe" functions may modify the
      global variable errno; the signal-catching function may want to save
      and restore its value. Naturally, the same principles apply to the
      reentrancy of application routines and asynchronous data access. Note
      that longjmp() and siglongjmp() are not in the list of reentrant
      functions. This is because the code executing after longjmp() and
      siglongjmp() can call any unsafe functions with the same danger as
      calling those unsafe functions directly from the signal handler.
      Applications that use longjmp() and siglongjmp() from within signal
      handlers require rigorous protection in order to be portable. Many of



 Hewlett-Packard Company            - 9 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




      the other functions that are excluded from the list are traditionally
      implemented using either malloc() or free() functions or the standard
      I/O library, both of which traditionally use data structures in a
      non-reentrant manner.  Because any combination of different functions
      using a common data structure can cause reentrancy problems, this
      document does not define the behaviour when any unsafe function is
      called in a signal handler that interrupts an unsafe function.

      If the signal occurs other than as the result of calling abort(),
      kill(), or raise(), the behaviour is undefined if the signal handler
      calls any function in the standard library other than one of the
      functions listed in the table above or refers to any object with
      static storage duration other than by assigning a value to a static
      storage duration variable of type volatile sig_atomic_t.  Furthermore,
      if such a call fails, the value of errno is indeterminate.

      Usually, the signal is executed on the stack that was in effect before
      the signal was delivered. An alternate stack may be specified to
      receive a subset of the signals being caught.

      When the signal handler returns, the receiving process will resume
      execution at the point it was interrupted unless the signal handler
      makes other arrangements. If longjmp() or _longjmp() is used to leave
      the signal handler, then the signal mask must be explicitly restored
      by the process.

      POSIX.4-1993 defines the third argument of a signal handling function
      when SA_SIGINFO is set as a void * instead of a ucontext_t * , but
      without requiring type checking.  New applications should explicitly
      cast the third argument of the signal handling function to uncontext_t
      *.

      The BSD optional four argument signal handling function is not
      supported by this specification.  The BSD declaration would be

           void handler(int sig, int code, struct where sig is the signal
           number, code is additional information on certain signals, scp is
           a pointer to the sigcontext structure, and addr is additional
           address information.  Much the same information is available in
           the objects pointed to by the second argument of the signal
           handler specified when SA_SIGINFO is set.

 FUTURE DIRECTIONS
      The fpathconf() function is marked as an extension in the list of safe
      functions because it is not included in the corresponding list in the
      ISO POSIX-1 standard, but it is expected to be added in a future
      revision of that standard.

 SEE ALSO
      bsd_signal(), kill(), _longjmp(), longjmp(), raise(), sigaddset(),
      sigaltstack(), sigdelset(), sigemptyset(), sigfillset(),



 Hewlett-Packard Company           - 10 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




      sigismember(), signal(), sigprocmask(), sigsuspend(), wait(), wait3(),
      waitid(), waitpid(), <signal.h>, <ucontext.h>.

 CHANGE HISTORY
      First released in Issue 3.

      Entry included for alignment with the POSIX.1-1988 standard.

 Issue 4
      The following changes are incorporated for alignment with the ISO
      POSIX-1 standard:

           o  The type of argument act is changed from struct sigaction * to
              const struct sigaction *.

           o  A statement is added to the DESCRIPTION section indicating
              that the consequence of attempting to set SIG_DFL for a signal
              that cannot be caught or ignored is unspecified. The EINVAL
              error, describing one possible reaction to this condition, is
              added to the ERRORS section.

      Other changes are incorporated as follows:

           o  The raise() and signal() functions are added to the list of
              functions that are either reentrant or not interruptible by
              signals; fpathconf() is also added to this list and marked as
              an extension; ustat() is removed from the list, as this
              function is withdrawn from the interface definition.  It is no
              longer specified whether abort(), chroot(), exit(), and
              longjmp() also fall into this category of functions.

           o  The APPLICATION USAGE section is added. Most of this text is
              moved from the DESCRIPTION SECTION in Issue 3.

           o  The FUTURE DIRECTIONS section is added.

 Issue 4, Version 2
      The following changes are incorporated for X/OPEN UNIX conformance:

           o  The DESCRIPTION describes sa_sigaction, the member of the
              sigaction structure that is the signal-catching function.

           o  The DESCRIPTION describes the SA_ONSTACK, SA_RESETHAND,
              SA_RESTART, SA_SIGINFO, SA_NOCLDWAIT, and SA_NODEFER settings
              of sa_flags.  The text describes the implications of the use
              of SA_SIGINFO for the number of arguments passed to the
              signal-catching function. The text also describes the effects
              of the SA_NODEFER and SA_RESETHAND flags on the delivery of a
              signal and on the permanence of an installed action.





 Hewlett-Packard Company           - 11 -    HP-UX Release 10.20:  July 1996






 sigaction(2)                                                   sigaction(2)




           o  The DESCRIPTION specifies the effect if the action for the
              SIGCHLD signal is set to SIG_IGN.

           o  In the DESCRIPTION, additional text describes the effect if
              the action is a pointer to a function. A new bullet covers the
              case where SA_SIGINFO is set .  SIGBUS is given as an
              additional signal for which the behaviour of a process is
              undefined following a normal return from the signal-catching
              function.

           o  The APPLICATION USAGE section is updated to describe use of an
              alternate signal stack; resumption of the process receiving
              the signal; coding for compatibility with POSIX.4-1993; and
              implementation of signal-handling functions in BSD.








































                                   - 12 -         Formatted:  April 25, 2001






 sigaction(2)                                                   sigaction(2)




                                 HP-UX EXTENSIONS



 DESCRIPTION
      More details on the semantics of specific signals can be found in the
      signal(5) manual entry.

           SIG_DFL        Upon receipt of the signal sig, the default action
                          (specified on signal(5)) is performed.

 ERRORS
           [EFAULT]       act or oact points to an invalid address.  The
                          reliable detection of this error is implementation
                          dependent.

 AUTHOR
      sigaction() was derived from the IEEE POSIX 1003.1-1988 Standard.

 SEE ALSO
      ptrace(2), sigpending(2), sigspace(2), sigsetops(3C).

 STANDARDS CONFORMANCE
      sigaction(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1






























 Hewlett-Packard Company            - 1 -    HP-UX Release 10.20:  July 1996