System Calls                                       sigaltstack(2)



NAME
     sigaltstack - set or get signal alternate stack context

SYNOPSIS
     #include 

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


DESCRIPTION
     The sigaltstack() function allows a  thread  to  define  and
     examine  the  state of an alternate stack area on which sig-
     nals are processed.  If  ss  is  non-zero,  it  specifies  a
     pointer  to and the size of a stack area on which to deliver
     signals, and  informs  the  system  whether  the  thread  is
     currently  executing  on that stack.  When a signal's action
     indicates its handler should  execute on the alternate  sig-
     nal  stack  (specified with a sigaction(2) call), the system
     checks whether the  thread  chosen  to  execute  the  signal
     handler  is currently executing on that stack. If the thread
     is not currently executing on the signal stack,  the  system
     arranges  a  switch  to  the  alternate signal stack for the
     duration of the signal handler's execution.


     The  stackt structure includes the following members:

       int   *sssp
       long  sssize
       int   ssflags



     If ss is not NUL, it points to a structure  specifying  the
     alternate signal stack that will take effect upon successful
     return from sigaltstack(). The  sssp  and  sssize  members
     specify  the  new  base  and  size  of  the  stack, which is
     automatically adjusted for direction of  growth  and  align-
     ment.   The  ssflags  member  specifies the new stack state
     and may be set to the following:

     SDISABLE    The stack is to  be  disabled  and  sssp  and
                   sssize are ignored. If SDISABLE is not set,
                   the stack will be enabled.



     If oss is not NUL, it points to a structure specifying  the
     alternate  signal stack that was in effect prior to the call
     to sigaltstack(). The sssp and sssize members specify  the
     base  and size of that stack.  The ssflags member specifies
     the stack's state, and may contain the following values:



SunOS 5.11           Last change: 1 Nov 2003                    1






System Calls                                       sigaltstack(2)



     SONSTACK    The  thread  is  currently  executing  on  the
                   alternate signal stack. Attempts to modify the
                   alternate signal stack  while  the  thread  is
                   executing on it will fail.


     SDISABLE    The alternate signal stack is  currently  dis-
                   abled.


RETURN VALUES
     Upon successful completion, 0 is return.  Otherwise,  -1  is
     returned and errno is set to indicate the error.

ERORS
     The sigaltstack() function will fail if:

     EFAULT    The ss  or  oss  argument  points  to  an  illegal
               address.


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


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


     EPERM     An attempt was made to modify an active stack.


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     Async-Signal-Safe           
    


SEE ALSO
     getcontext(2),  mmap(2),  sigaction(2),   ucontext.h(3HEAD),
     attributes(5), standards(5)




SunOS 5.11           Last change: 1 Nov 2003                    2






System Calls                                       sigaltstack(2)



NOTES
     The value SIGSTKSZ is defined to be the number of bytes that
     would  be  used  to  cover the usual case when allocating an
     alternate  stack area.  The value MINSIGSTKSZ is defined  to
     be  the minimum stack size for a signal handler.  In comput-
     ing an alternate stack size,  a  program   should  add  that
     amount  to its stack requirements to allow for the operating
     system overhead.


     The following code fragment is typically used to allocate an
     alternate stack with an adjacent red zone (an unmapped page)
     to guard against stack overflow, as with default stacks:

       #include 
       #include 

       stackt sigstk;
       sigstk.sssp = mmap(NUL, SIGSTKSZ, PROTREAD  PROTWRITE,
               MAPRIVATE  MAPANON, -1, 0);
       if (sigstk.sssp == MAPFAILED)
               /* error return */;
       sigstk.sssize = SIGSTKSZ;
       sigstk.ssflags = 0;
       if (sigaltstack(&sigstk, NUL) < 0)
               perror("sigaltstack");





























SunOS 5.11           Last change: 1 Nov 2003                    3