mirror of https://github.com/mkerrisk/man-pages
291 lines
8.4 KiB
Groff
291 lines
8.4 KiB
Groff
'\" t
|
|
.\" Copyright (c) 2001, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" 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.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" aeb, various minor fixes
|
|
.TH SIGALTSTACK 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
sigaltstack \- set and/or get signal stack context
|
|
.SH SYNOPSIS
|
|
.B #include <signal.h>
|
|
.PP
|
|
.BI "int sigaltstack(const stack_t *" ss ", stack_t *" old_ss );
|
|
.PP
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.PP
|
|
.BR sigaltstack ():
|
|
.ad l
|
|
.RS 4
|
|
.PD 0
|
|
_XOPEN_SOURCE\ >=\ 500
|
|
.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
|
|
|| /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
|
|
|| /* Glibc versions <= 2.19: */ _BSD_SOURCE
|
|
.PD
|
|
.RE
|
|
.ad
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The \fIss\fP argument is used to specify a new
|
|
alternate signal stack, while the \fIold_ss\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.
|
|
.PP
|
|
The
|
|
.I stack_t
|
|
type used to type the arguments of this function is defined as follows:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
typedef struct {
|
|
void *ss_sp; /* Base address of stack */
|
|
int ss_flags; /* Flags */
|
|
size_t ss_size; /* Number of bytes in stack */
|
|
} stack_t;
|
|
.EE
|
|
.in
|
|
.PP
|
|
To establish a new alternate signal stack,
|
|
the fields of this structure are set as follows:
|
|
.TP
|
|
.I ss.ss_flags
|
|
This field is set to zero.
|
|
.TP
|
|
.I ss.ss_sp
|
|
This field specifies the starting address of the stack.
|
|
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.
|
|
.TP
|
|
.I ss.ss_size
|
|
This field specifies the 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
If \fIold_ss\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 \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting
|
|
address and size of that stack.
|
|
The \fIold_ss.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.
|
|
.PP
|
|
By specifying
|
|
.I ss
|
|
as NULL, and
|
|
.I old_ss
|
|
as a non-NULL value, one can obtain the current settings for
|
|
the alternate signal stack without changing them.
|
|
.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 \fIold_ss\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
|
|
an invalid flag.
|
|
.TP
|
|
.B ENOMEM
|
|
The specified size of the new alternate signal stack
|
|
.I ss.ss_size
|
|
was less than
|
|
.BR MINSTKSZ .
|
|
.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 ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lb lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR sigaltstack ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2009, SUSv2, SVr4.
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
On most hardware architectures supported by Linux, stacks grow
|
|
downward.
|
|
.BR sigaltstack ()
|
|
automatically takes account
|
|
of the direction of stack growth.
|
|
.PP
|
|
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.
|
|
.PP
|
|
A successful call to
|
|
.BR execve (2)
|
|
removes any existing alternate
|
|
signal stack.
|
|
A child process created via
|
|
.BR fork (2)
|
|
inherits a copy of its parent's alternate signal stack settings.
|
|
.PP
|
|
.BR sigaltstack ()
|
|
supersedes the older
|
|
.BR sigstack ()
|
|
call.
|
|
For backward 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 ():
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
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 */;
|
|
.EE
|
|
.in
|
|
.SH BUGS
|
|
In the lead up to the development of the Linux 2.4 kernel,
|
|
.\" Linux 2.3.40
|
|
someone got confused and allowed the kernel to accept
|
|
.B SS_ONSTACK
|
|
in
|
|
.IR ss.ss_flags ,
|
|
which results in behavior that is the same as when
|
|
.I ss_flags
|
|
is 0.
|
|
On other implementations, and according to POSIX.1,
|
|
.B SS_ONSTACK
|
|
appears only as a reported flag in
|
|
.IR old_ss.ss_flags .
|
|
There is no need ever to specify this flag in
|
|
.IR ss.ss_flags
|
|
(and indeed, doing so decreases portability,
|
|
since some implementations
|
|
.\" See the source code of Illumos and FreeBSD, for example.
|
|
give an error if
|
|
.B SS_ONSTACK
|
|
is specified in
|
|
.IR ss.ss_flags ).
|
|
.SH SEE ALSO
|
|
.BR execve (2),
|
|
.BR setrlimit (2),
|
|
.BR sigaction (2),
|
|
.BR siglongjmp (3),
|
|
.BR sigsetjmp (3),
|
|
.BR signal (7)
|