sigaltstack(2)                                               sigaltstack(2)




 NAME    [Toc]    [Back]
      sigaltstack - set and/or get signal alternate stack context.

 SYNOPSIS    [Toc]    [Back]
      #include <signal.h>

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

 DESCRIPTION    [Toc]    [Back]
      The sigaltstack() function allows a process to define and examine the
      state of an alternate stack for signal handlers. Signals that have
      been explicitly declared to execute on the alternate stack will 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 will 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 will 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 interface 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 will 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 fails.
                                    This flag must 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



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 sigaltstack(2)                                               sigaltstack(2)




      <signal.h>.

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

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, sigaltstack() returns 0. Otherwise, it
      returns -1 and sets errno to indicate the error.

 ERRORS    [Toc]    [Back]
      The sigaltstack() function will 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.

 WARNINGS    [Toc]    [Back]
      At HP-UX release 11i Version 1.6 and forward, use of sigaltstack() in
      threads created with process contention scope will result in undefined
      behavior.  This function will continue to be reliable in threads
      created with system contention scope.

 APPLICATION USAGE    [Toc]    [Back]
      The following code fragment illustrates a method for allocating memory
      for an alternate stack:

           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");

      In some implementations, a signal (whether or not indicated to execute
      on the alternate stack) will always execute on the alternate stack if
      it is delivered while another signal is being caught using the
      alternate stack.

      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.

    Threads Considerations    [Toc]    [Back]
      Each thread may define an alternate signal handling stack.



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 sigaltstack(2)                                               sigaltstack(2)




    LWP (Light Weight Processes) Considerations    [Toc]    [Back]
      Each LWP may define an alternate signal handling stack.

 SEE ALSO    [Toc]    [Back]
      sigaction(2), setjmp(3C), <signal.h>.

 CHANGE HISTORY    [Toc]    [Back]
      First released in Issue 4, Version 2.


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003