General description
The sigaltstack()
function allows a thread 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.
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
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.
AMODE 64 considerations: Storage for this stack must be above
the 2GB bar. It may not be storage acquired with the __malloc24()
or __malloc31() functions.
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 before
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 thread
is currently executing on the alternate signal stack. Attempts to
modify the alternate signal stack while the thread is executing on
it fails. This flag must not be modified by threads.
- 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 signal 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.
Notes: - 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).
- 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).
Returned value
If successful, sigaltstack()
returns 0.
If unsuccessful, sigaltstack() returns -1 and sets
errno to one of the following values:
- Error Code
- Description
- EINVAL
- 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.