mirror of https://github.com/mkerrisk/man-pages
231 lines
7.2 KiB
Groff
231 lines
7.2 KiB
Groff
'\" t
|
|
.\" Copyright (c) 2001, Michael Kerrisk (mtk.manpages@gmail.com)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" aeb, various minor fixes
|
|
.TH SIGALTSTACK 2 2008-10-04 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sigaltstack \- set and/or get signal stack context
|
|
.SH SYNOPSIS
|
|
.B #include <signal.h>
|
|
.sp
|
|
.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR sigaltstack ():
|
|
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
|
|
.\" .br
|
|
.\" .BR sigstack ():
|
|
.\" _BSD_SOURCE || _XOPEN_SOURCE >= 500
|
|
.SH DESCRIPTION
|
|
.BR sigaltstack ()
|
|
allows a process to define a new alternate
|
|
signal stack and/or retrieve the state of an existing
|
|
alternate signal stack.
|
|
An alternate signal stack is used during the
|
|
execution of a signal handler if the establishment of that handler (see
|
|
.BR sigaction (2))
|
|
requested it.
|
|
|
|
The normal sequence of events for using an alternate signal stack
|
|
is the following:
|
|
.TP 3
|
|
1.
|
|
Allocate an area of memory to be used for the alternate
|
|
signal stack.
|
|
.TP
|
|
2.
|
|
Use
|
|
.BR sigaltstack ()
|
|
to inform the system of the existence and
|
|
location of the alternate signal stack.
|
|
.TP
|
|
3.
|
|
When establishing a signal handler using
|
|
.BR sigaction (2),
|
|
inform the system that the signal handler should be executed
|
|
on the alternate signal stack by
|
|
specifying the \fBSA_ONSTACK\fP flag.
|
|
.P
|
|
The \fIss\fP argument is used to specify a new
|
|
alternate signal stack, while the \fIoss\fP argument
|
|
is used to retrieve information about the currently
|
|
established signal stack.
|
|
If we are interested in performing just one
|
|
of these tasks then the other argument can be specified as NULL.
|
|
Each of these arguments is a structure of the following type:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
typedef struct {
|
|
void *ss_sp; /* Base address of stack */
|
|
int ss_flags; /* Flags */
|
|
size_t ss_size; /* Number of bytes in stack */
|
|
} stack_t;
|
|
.fi
|
|
.in
|
|
|
|
To establish a new alternate signal stack,
|
|
\fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
|
|
\fIss.ss_size\fP specify the starting address and size of
|
|
the stack.
|
|
The constant \fBSIGSTKSZ\fP is defined to be large enough
|
|
to cover the usual size requirements for an alternate signal stack,
|
|
and the constant \fBMINSIGSTKSZ\fP defines the minimum
|
|
size required to execute a signal handler.
|
|
|
|
When a signal handler is invoked on the alternate stack,
|
|
the kernel automatically aligns the address given in \fIss.ss_sp\fP
|
|
to a suitable address boundary for the underlying hardware architecture.
|
|
|
|
To disable an existing stack, specify \fIss.ss_flags\fP
|
|
as \fBSS_DISABLE\fP.
|
|
In this case, the remaining fields
|
|
in \fIss\fP are ignored.
|
|
|
|
If \fIoss\fP is not NULL, then it is used to return information about
|
|
the alternate signal stack which was in effect prior to the
|
|
call to
|
|
.BR sigaltstack ().
|
|
The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
|
|
address and size of that stack.
|
|
The \fIoss.ss_flags\fP may return either of the following values:
|
|
.TP
|
|
.B SS_ONSTACK
|
|
The process is currently executing on the alternate signal stack.
|
|
(Note that it is not possible
|
|
to change the alternate signal stack if the process is
|
|
currently executing on it.)
|
|
.TP
|
|
.B SS_DISABLE
|
|
The alternate signal stack is currently disabled.
|
|
.SH "RETURN VALUE"
|
|
.BR sigaltstack ()
|
|
returns 0 on success, or \-1 on failure with
|
|
\fIerrno\fP set to indicate the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
Either \fIss\fP or \fIoss\fP is not NULL and points to an area
|
|
outside of the process's address space.
|
|
.TP
|
|
.B EINVAL
|
|
\fIss\fP is not NULL and the \fIss_flags\fP field contains
|
|
a nonzero value other than
|
|
.BR SS_DISABLE .
|
|
.TP
|
|
.B ENOMEM
|
|
The specified size of the new alternate signal stack
|
|
(\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP.
|
|
.TP
|
|
.B EPERM
|
|
An attempt was made to change the alternate signal stack while
|
|
it was active (i.e., the process was already executing
|
|
on the current alternate signal stack).
|
|
.SH "CONFORMING TO"
|
|
SUSv2, SVr4, POSIX.1-2001.
|
|
.SH NOTES
|
|
The most common usage of an alternate signal stack is to handle the
|
|
.B SIGSEGV
|
|
signal that is generated if the space available for the
|
|
normal process stack is exhausted: in this case, a signal handler for
|
|
.B SIGSEGV
|
|
cannot be invoked on the process stack; if we wish to handle it,
|
|
we must use an alternate signal stack.
|
|
.P
|
|
Establishing an alternate signal stack is useful if a process
|
|
expects that it may exhaust its standard stack.
|
|
This may occur, for example, because the stack grows so large
|
|
that it encounters the upwardly growing heap, or it reaches a
|
|
limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
|
|
If the standard stack is exhausted, the kernel sends
|
|
the process a \fBSIGSEGV\fP signal.
|
|
In these circumstances the only way to catch this signal is
|
|
on an alternate signal stack.
|
|
.P
|
|
On most hardware architectures supported by Linux, stacks grow
|
|
downwards.
|
|
.BR sigaltstack ()
|
|
automatically takes account
|
|
of the direction of stack growth.
|
|
.P
|
|
Functions called from a signal handler executing on an alternate
|
|
signal stack will also use the alternate signal stack.
|
|
(This also applies to any handlers invoked for other signals while
|
|
the process is executing on the alternate signal stack.)
|
|
Unlike the standard stack, the system does not
|
|
automatically extend the alternate signal stack.
|
|
Exceeding the allocated size of the alternate signal stack will
|
|
lead to unpredictable results.
|
|
.P
|
|
A successful call to
|
|
.BR execve (2)
|
|
removes any existing alternate
|
|
signal stack.
|
|
A child process created via
|
|
.BR fork ()
|
|
inherits a copy of its parent's alternate signal stack settings.
|
|
.P
|
|
.BR sigaltstack ()
|
|
supersedes the older
|
|
.BR sigstack ()
|
|
call.
|
|
For backwards compatibility, glibc also provides
|
|
.BR sigstack ().
|
|
All new applications should be written using
|
|
.BR sigaltstack ().
|
|
.SS History
|
|
4.2BSD had a
|
|
.BR sigstack ()
|
|
system call.
|
|
It used a slightly
|
|
different struct, and had the major disadvantage that the caller
|
|
had to know the direction of stack growth.
|
|
.SH EXAMPLE
|
|
The following code segment demonstrates the use of
|
|
.BR sigaltstack ():
|
|
|
|
.in +4n
|
|
.nf
|
|
stack_t ss;
|
|
|
|
ss.ss_sp = malloc(SIGSTKSZ);
|
|
if (ss.ss_sp == NULL)
|
|
/* Handle error */;
|
|
ss.ss_size = SIGSTKSZ;
|
|
ss.ss_flags = 0;
|
|
if (sigaltstack(&ss, NULL) == \-1)
|
|
/* Handle error */;
|
|
.fi
|
|
.in
|
|
.SH "SEE ALSO"
|
|
.BR execve (2),
|
|
.BR setrlimit (2),
|
|
.BR sigaction (2),
|
|
.BR siglongjmp (3),
|
|
.BR sigsetjmp (3),
|
|
.BR signal (7)
|