.if n .pH g2.sigaltstack @(#)sigaltstack	40.22 of 10/11/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} sigaltstack 2 "" "\&"
.if \nX=1 .ds x} sigaltstack 2 ""
.if \nX=2 .ds x} sigaltstack 2 "" "\&"
.if \nX=3 .ds x} sigaltstack "" "" "\&"
.TH \*(x}
.SH NAME
\f4sigaltstack\f1 \- set or get signal alternate stack context
.SH SYNOPSIS
\f4#include <signal.h>\f1
.P
\f4int sigaltstack(const stack_t *ss, stack_t *oss);\f1
.SH DESCRIPTION
\f4sigaltstack\fP allows users to define an 
alternate stack area on which signals are to be
processed.  If \f2ss\fP is non-zero, it specifies a pointer to,  
and the size of a 
stack area on which to deliver signals, and tells the system 
if the process is currently executing on that stack. 
When a signal's action indicates its handler should 
execute on the alternate signal stack [specified with a \f4sigaction\fP(2) call],
the system checks to see if the process is currently executing on
that stack.  If the process 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. 
.P
The structure \f4sigaltstack\fP includes the following members.
.P
.RS
.nf
.ft 4 
int     *ss_sp
long    ss_size	
int     ss_flags
.ft 1
.fi
.RE
.P
If \f2ss\f1 is not \f4NULL\fP, it points to a structure specifying the
alternate signal stack that will take effect upon return from
\f4sigaltstack\fP.  The \f4ss_sp\f1 and \f4ss_size\f1 fields specify
the new base and size of the stack, which is automatically
adjusted for direction of growth and alignment.  The \f4ss_flags\f1
field specifies the new stack state 
and may be set to the following:
.TP 14
\f4SS_DISABLE\fP
The stack is to be disabled and \f4ss_sp\f1 and \f4ss_size\f1 are ignored.
If \f4SS_DISABLE\fP is not set, the stack will be enabled.
.PP
If \f2oss\f1 is not \f4NULL\fP, it points to a structure specifying the
alternate signal stack that was in effect prior to the call to
\f4sigaltstack\fP.  The \f4ss_sp\f1 and \f4ss_size\f1 fields specify
the base and size of that stack.  The \f4ss_flags\f1 field specifies the
stack's state, and may contain the following values:
.TP 14
\f4SS_ONSTACK\fP
The process is currently executing on the alternate signal stack.
Attempts to modify the alternate signal stack while the process is
executing on it will fail.
.TP
\f4SS_DISABLE\fP
The alternate signal stack is currently disabled.
.PP
\f4sigaltstack\fP fails if any of the following is true:
.TP 14
\f4EFAULT\fP
Either \f2ss\fP or \f2oss\fP points outside the process's allocated address
space.
.TP
\f4EINVAL\fP
An attempt was made to disable an active stack or the \f4ss_flags\fP 
field specifies invalid flags.
.TP
\f4ENOMEM\fP
The size of the alternate stack area is less than \f4MINSIGSTKSZ\fP.
.SH NOTES
The value \f4SIGSTKSZ\fP 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 \%\f4MINSIGSTKSZ\fP 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
operating system overhead.
.PP
The following code fragment is typically used to allocate an
alternate stack.
.PP
.RS
.nf
.ft 4
if ((sigstk.ss_sp = (char *)malloc(SIGSTKSZ)) == NULL)
	/* error return */;
.sp
sigstk.ss_size = SIGSTKSZ;
sigstk.ss_flags = 0;
if (sigaltstack(&sigstk, (stack_t *)0) < 0)
	perror("sigaltstack");
.ft 1
.fi
.RE
.SH "SEE ALSO"
\f4getcontext\fP(2), \f4sigaction\fP(2), \f4sigsetjmp\fP(3C), \f4ucontext\fP(5).
.SH DIAGNOSTICS
On success, \f4sigaltstack\fP returns zero.
On failure, it returns \-1 and sets \f4errno\f1 to indicate the error.
.\"	@(#)sigaltstack.2	1 of 9/27/88
.Ee
