118 lines
4.0 KiB
Groff
118 lines
4.0 KiB
Groff
.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
|