.if n .pH g2.sigaltstack @(#)sigaltstack	41.3 of 4/17/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 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 \f4stack_t\fP includes the following members.
.P
.RS
.nf
.ft 4 
char	*ss_sp
int	 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.  The \f4ss_sp\f1 field should be
adjusted for the direction of growth (see example below).  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.  \f4SS_ONSTACK\fP cannot be modified by
users.
.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
If \f2ss\fP is non-null, and the \f4ss_flags\fP field pointed to by
\f2ss\fP contains invalid flags.
.TP
\f4EPERM\fP
If an attempt was made to modify an active stack.
.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 stack grows downward from high to lower addresses.
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_sp += SIGSTKSZ - 1;
	/* adjust ss_sp to point to base of stack */
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