sigstack() — Set or get signal stack context

Standards

Standards / Extensions C or C++ Dependencies
XPG4.2 both POSIX(ON)

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <signal.h>

int sigstack(struct sigstack *ss, struct sigstack *oss);

General description

The sigstack() function allows the calling thread to indicate, to the system, an area of its address space to be used for processing signals received by this thread.

Note: To explicitly declare that a signal catcher is to run on the alternate signal stack, the SA_ONSTACK flag must be set in the sa_flags when the signal action is set using sigaction().
If the ss argument is not a NULL pointer, it must point to a sigstack structure. The length of the application-supplied stack must be at least SIGSTKSZ bytes. If the alternate signal stack overflows, the resulting behavior is undefined.
  • The value of the ss_onstack member indicates whether the thread wants the system to use an alternate signal stack when delivering signals.
  • The value of the ss_sp member indicates the desired location of the alternate signal stack area in the process's address space.
    AMODE 64: Storage for this stack must be above the 2GB bar. It may not be storage acquired with the __malloc24() or __malloc31() functions.
  • If the ss argument is a NULL pointer, the current alternate signal stack context is not changed.

If the oss argument is not a NULL pointer, it must point to a sigstack structure into which the current alternate signal stack context is placed. The value stored in the ss_onstack member of this sigstack structure will be nonzero if the thread is currently executing on the alternate signal stack. If the oss argument is a NULL pointer, the current alternate signal stack context is not returned.

When a signal's action indicates its handler should execute on the alternate signal stack (specified by calling sigaction()), the implementation checks to see if the thread is currently executing on the alternate signal stack. If it is not, the system will switch to the alternate signal stack for the duration of the signal handler's execution.

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

Notes:
  1. If a signal handler is enabled to run on an alternate stack, then all functions called by that signal handler must be compiled with the same linkage. For example, if the signal handler is compiled with XPLINK, then all functions it calls must also be compiled XPLINK. Since only one alternate stack can be supplied, no mixing of linkages (which would require both upward and downward-growing alternate stacks) is allowed. The type of stack created will be based on the attributes of the signal handler to be given control. If the signal handler has been compiled with XPLINK, then a downward-growing stack will be created in the alternate stack, including, in AMODE 31, using enough storage in the user stack to create a 4k read-only guard page (aligned on a 4k boundary).
  2. If a new signal is received while a signal handler is running on an alternate stack, and that new signal specified a signal handler that also runs on the alternate stack, then both signal handlers must have been compiled with the same linkage (XPLINK versus non-XPLINK).

  3. This function is kept for historical reasons. It was part of the Legacy Feature in Single UNIX Specification, Version 2, but has been withdrawn and is not supported as part of Single UNIX Specification, Version 3. New applications should use sigaltstack() instead of sigstack().

    If it is necessary to continue using this function in an application written for Single UNIX Specification, Version 3, define the feature test macro _UNIX03_WITHDRAWN before including any standard system headers. The macro exposes all interfaces and symbols removed in Single UNIX Specification, Version 3.

Returned value

If successful, sigstack() returns 0.

If unsuccessful, sigstack() returns -1 and sets errno to one of the following values:
Error Code
Description
EPERM
An attempt was made to modify an active stack.

Related information

Parent topic: Library functions