1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
|
'\" 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 2010-09-20 "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 ():
.ad l
.RS 4
.PD 0
.TP 4
Since glibc 2.12
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED ||
_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700
.TP
Before glibc 2.12
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
.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.
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)
.SH COLOPHON
This page is part of release 3.27 of the Linux
.I man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://www.kernel.org/doc/man-pages/.
|