# sigaltstack

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           sigaltstack — set and get signal alternate stack context
    


## 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, upon 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 minimum 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 on the alternate stack) shall always execute on the
           alternate stack if it is delivered while another signal is being
           caught using the alternate stack.
    
           Use of this function by library threads that are not bound to
           kernel-scheduled entities results in undefined behavior.
    


## RETURN VALUE



           Upon successful completion, _sigaltstack_() shall return 0;
           otherwise, it shall return -1 and set _errno_ to indicate the error.
    


## ERRORS



           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.
    


* * *