sigaltstack

SYNOPSIS
       #include <signal.h>

       int sigaltstack(const stack_t *restrict ss, stack_t *restrict oss);


DESCRIPTION
       The  sigaltstack()  function allows a process to define and examine the
       state of an alternate stack for signal handlers for the current thread.
       Signals  that have been explicitly declared to execute on the alternate
       stack shall be delivered on the alternate stack.

       If ss is not a null pointer, it points  to  a  stack_t  structure  that
       specifies the alternate signal stack that shall take effect upon return
       from sigaltstack(). The ss_flags member specifies the new stack  state.
       If it is set to SS_DISABLE, the stack is disabled and ss_sp and ss_size
       are ignored. Otherwise, the stack shall be enabled, and the  ss_sp  and
       ss_size members specify the new address and size of the stack.

       The range of addresses starting at ss_sp up to but not including ss_sp+
       ss_size is available to the implementation for use as the  stack.  This
       function makes no assumptions regarding which end is the stack base and
       in which direction the stack grows as items are pushed.

       If oss is not a null pointer, on successful completion it  shall  point
       to  a  stack_t structure that specifies the alternate signal stack that
       was in effect prior to  the  call  to  sigaltstack().   The  ss_sp  and
       ss_size  members  specify  the  address  and  size  of  that stack. The
       ss_flags member specifies the stack's state, and may contain one of the
       following values:

       SS_ONSTACK
              The  process  is  currently  executing  on  the alternate signal
              stack.  Attempts to modify the alternate signal stack while  the
              process is executing on it fail. This flag shall not be modified
              by processes.

       SS_DISABLE
              The alternate signal stack is currently disabled.


       The value SIGSTKSZ is a system default specifying the number  of  bytes
       that  would be used to cover the usual case when manually allocating an
       alternate stack area. The value MINSIGSTKSZ is defined to be the  mini-
       mum  stack  size  for a signal handler. In computing an alternate stack
       size, a program should add that amount to  its  stack  requirements  to
       allow for the system implementation overhead. The constants SS_ONSTACK,
       SS_DISABLE, SIGSTKSZ, and MINSIGSTKSZ are defined in <signal.h>.

       After a successful call to one of the  exec  functions,  there  are  no
       alternate signal stacks in the new process image.

       In  some implementations, a signal (whether or not indicated to execute
       The sigaltstack() function shall fail if:

       EINVAL The ss argument is not a null pointer, and the  ss_flags  member
              pointed to by ss contains flags other than SS_DISABLE.

       ENOMEM The size of the alternate stack area is less than MINSIGSTKSZ.

       EPERM  An attempt was made to modify an active stack.


       The following sections are informative.

EXAMPLES
   Allocating Memory for an Alternate Stack
       The following example illustrates a method for allocating memory for an
       alternate stack.


              #include <signal.h>
              ...
              if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
                  /* Error return. */
              sigstk.ss_size = SIGSTKSZ;
              sigstk.ss_flags = 0;
              if (sigaltstack(&sigstk,(stack_t *)0) < 0)
                  perror("sigaltstack");

APPLICATION USAGE
       On some implementations,  stack  space  is  automatically  extended  as
       needed.  On those implementations, automatic extension is typically not
       available for an alternate stack. If the stack overflows, the  behavior
       is undefined.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Signal Concepts , sigaction() , sigsetjmp() , the Base Definitions vol-
       ume of IEEE Std 1003.1-2001, <signal.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .