NAME    [Toc]    [Back]

     sigaltstack - set and/or get signal stack context

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <signal.h>

     struct sigaltstack {
             void    *ss_sp;
             size_t  ss_size;
             int     ss_flags;
     };

     int
     sigaltstack(const struct sigaltstack *ss, struct sigaltstack
*oss);

DESCRIPTION    [Toc]    [Back]

     sigaltstack()  allows  users to define an alternate stack on
which signals
     are to be processed.  If ss  is  non-zero,  it  specifies  a
pointer to and
     the  size of a signal stack on which to deliver signals, and
tells the
     system if the process is currently executing on that  stack.
When a signal's
  action  indicates  its  handler should execute on the
signal stack
     (specified with a sigaction(2) call), the system  checks  to
see if the
     process  is  currently executing on that stack.  If the process is not currently
 executing on the signal stack, the system arranges  a
switch to the
     signal stack for the duration of the signal handler's execution.

     If SS_DISABLE is set in ss_flags, ss_sp and ss_size are  ignored and the
     signal  stack will be disabled.  Trying to disable an active
stack will
     cause sigaltstack to return -1 with errno set to EINVAL.   A
disabled
     stack will cause all signals to be taken on the regular user
stack.  If
     the stack is later re-enabled then  all  signals  that  were
specified to be
     processed on an alternate stack will resume doing so.

     If  oss  is  non-zero, the current signal stack state is returned.  The
     ss_flags field will contain the value SS_ONSTACK if the process is currently
  on a signal stack and SS_DISABLE if the signal stack
is currently
     disabled.

NOTES    [Toc]    [Back]

     The  value  SIGSTKSZ  is  defined  to  be  the   number   of
bytes/chars that would
     be used to cover the usual case when allocating an alternate
stack area.
     The following code fragment is typically used to allocate an
alternate
     stack.

           if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
                   /* error return */
           sigstk.ss_size = SIGSTKSZ;
           sigstk.ss_flags = 0;
           if (sigaltstack(&sigstk,0) < 0)
                   perror("sigaltstack");

     An alternative approach is provided for programs with signal
handlers
     that require a specific amount of stack space other than the
default
     size.   The value MINSIGSTKSZ is defined to be the number of
bytes/chars
     that is required by the operating system  to  implement  the
alternate stack
     feature.   In  computing  an  alternate stack size, programs
should add
     MINSIGSTKSZ to their stack requirements to allow for the operating system
     overhead.

     Signal  stacks  are automatically adjusted for the direction
of stack
     growth and alignment requirements.  Signal stacks may or may
not be protected
  by  the hardware and are not ``grown'' automatically
as is done for
     the normal stack.  If the stack overflows and this space  is
not protected
     unpredictable results may occur.

RETURN VALUES    [Toc]    [Back]

     Upon  successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

ERRORS    [Toc]    [Back]

     sigaltstack() will fail and the signal  stack  context  will
remain unchanged
 if one of the following occurs.

     [EFAULT]   Either  ss  or oss points to memory that is not a
valid part of
               the process address space.

     [EINVAL]  An attempt was made to disable an active stack.

     [ENOMEM]  Size of alternate stack area is less than or equal
to
               MINSIGSTKSZ.

SEE ALSO    [Toc]    [Back]

     sigaction(2), setjmp(3)

HISTORY    [Toc]    [Back]

     The  predecessor to sigaltstack, the sigstack() system call,
appeared in
     4.2BSD.

OpenBSD      3.6                           June      4,      1993