2 .\" Copyright (c) 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" aeb, various minor fixes
27 .TH SIGALTSTACK 2 2017-11-08 "Linux" "Linux Programmer's Manual"
29 sigaltstack \- set and/or get signal stack context
31 .B #include <signal.h>
33 .BI "int sigaltstack(const stack_t *" ss ", stack_t *" old_ss );
36 Feature Test Macro Requirements for glibc (see
37 .BR feature_test_macros (7)):
44 _XOPEN_SOURCE\ >=\ 500
45 .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
46 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
47 || /* Glibc versions <= 2.19: */ _BSD_SOURCE
53 allows a process to define a new alternate
54 signal stack and/or retrieve the state of an existing
55 alternate signal stack.
56 An alternate signal stack is used during the
57 execution of a signal handler if the establishment of that handler (see
61 The normal sequence of events for using an alternate signal stack
65 Allocate an area of memory to be used for the alternate
71 to inform the system of the existence and
72 location of the alternate signal stack.
75 When establishing a signal handler using
77 inform the system that the signal handler should be executed
78 on the alternate signal stack by
79 specifying the \fBSA_ONSTACK\fP flag.
81 The \fIss\fP argument is used to specify a new
82 alternate signal stack, while the \fIold_ss\fP argument
83 is used to retrieve information about the currently
84 established signal stack.
85 If we are interested in performing just one
86 of these tasks, then the other argument can be specified as NULL.
90 type used to type the arguments of this function is defined as follows:
95 void *ss_sp; /* Base address of stack */
96 int ss_flags; /* Flags */
97 size_t ss_size; /* Number of bytes in stack */
102 To establish a new alternate signal stack,
103 the fields of this structure are set as follows:
106 This field contains either 0, or the following flag:
109 .BR SS_AUTODISARM " (since Linux 4.7)"
110 .\" commit 2a74213838104a41588d86fd5e8d344972891ace
111 .\" See tools/testing/selftests/sigaltstack/sas.c in kernel sources
112 Clear the alternate signal stack settings on entry to the signal handler.
113 When the signal handler returns,
114 the previous alternate signal stack settings are restored.
116 This flag was added in order make it safe
117 to switch away from the signal handler with
119 Without this flag, a subsequently handled signal will corrupt
120 the state of the switched-away signal handler.
121 On kernels where this flag is not supported,
125 when this flag is supplied.
129 This field specifies the starting address of the stack.
130 When a signal handler is invoked on the alternate stack,
131 the kernel automatically aligns the address given in \fIss.ss_sp\fP
132 to a suitable address boundary for the underlying hardware architecture.
135 This field specifies the size of the stack.
136 The constant \fBSIGSTKSZ\fP is defined to be large enough
137 to cover the usual size requirements for an alternate signal stack,
138 and the constant \fBMINSIGSTKSZ\fP defines the minimum
139 size required to execute a signal handler.
141 To disable an existing stack, specify \fIss.ss_flags\fP
143 In this case, the kernel ignores any other flags in
145 and the remaining fields
148 If \fIold_ss\fP is not NULL, then it is used to return information about
149 the alternate signal stack which was in effect prior to the
152 The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting
153 address and size of that stack.
154 The \fIold_ss.ss_flags\fP may return either of the following values:
157 The process is currently executing on the alternate signal stack.
158 (Note that it is not possible
159 to change the alternate signal stack if the process is
160 currently executing on it.)
163 The alternate signal stack is currently disabled.
165 Alternatively, this value is returned if the process is currently
166 executing on an alternate signal stack that was established using the
169 In this case, it is safe to switch away from the signal handler with
171 It is also possible to set up a different alternative signal stack
172 using a further call to
174 .\" FIXME Was it intended that one can set up a different alternative
175 .\" signal stack in this scenario? (In passing, if one does this, the
176 .\" sigaltstack(NULL, &old_ss) now returns old_ss.ss_flags==SS_AUTODISARM
177 .\" rather than old_ss.ss_flags==SS_DISABLE. The API design here seems
181 The alternate signal stack has been marked to be autodisarmed
188 as a non-NULL value, one can obtain the current settings for
189 the alternate signal stack without changing them.
192 returns 0 on success, or \-1 on failure with
193 \fIerrno\fP set to indicate the error.
197 Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area
198 outside of the process's address space.
201 \fIss\fP is not NULL and the \fIss_flags\fP field contains
205 The specified size of the new alternate signal stack
211 An attempt was made to change the alternate signal stack while
212 it was active (i.e., the process was already executing
213 on the current alternate signal stack).
215 For an explanation of the terms used in this section, see
221 Interface Attribute Value
224 T} Thread safety MT-Safe
227 POSIX.1-2001, POSIX.1-2008, SUSv2, SVr4.
231 flag is a Linux extension.
233 The most common usage of an alternate signal stack is to handle the
235 signal that is generated if the space available for the
236 normal process stack is exhausted: in this case, a signal handler for
238 cannot be invoked on the process stack; if we wish to handle it,
239 we must use an alternate signal stack.
241 Establishing an alternate signal stack is useful if a process
242 expects that it may exhaust its standard stack.
243 This may occur, for example, because the stack grows so large
244 that it encounters the upwardly growing heap, or it reaches a
245 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
246 If the standard stack is exhausted, the kernel sends
247 the process a \fBSIGSEGV\fP signal.
248 In these circumstances the only way to catch this signal is
249 on an alternate signal stack.
251 On most hardware architectures supported by Linux, stacks grow
254 automatically takes account
255 of the direction of stack growth.
257 Functions called from a signal handler executing on an alternate
258 signal stack will also use the alternate signal stack.
259 (This also applies to any handlers invoked for other signals while
260 the process is executing on the alternate signal stack.)
261 Unlike the standard stack, the system does not
262 automatically extend the alternate signal stack.
263 Exceeding the allocated size of the alternate signal stack will
264 lead to unpredictable results.
268 removes any existing alternate
270 A child process created via
272 inherits a copy of its parent's alternate signal stack settings.
278 For backward compatibility, glibc also provides
280 All new applications should be written using
287 different struct, and had the major disadvantage that the caller
288 had to know the direction of stack growth.
290 The following code segment demonstrates the use of
294 to install an alternate signal stack that is employed by a handler
303 ss.ss_sp = malloc(SIGSTKSZ);
304 if (ss.ss_sp == NULL) {
309 ss.ss_size = SIGSTKSZ;
311 if (sigaltstack(&ss, NULL) == \-1) {
312 perror("sigaltstack");
316 sa.sa_flags = SA_ONSTACK;
317 sa.sa_handler = handler(); /* Address of a signal handler */
318 sigemptyset(&sa.sa_mask);
319 if (sigaction(SIGSEGV, &sa, NULL) == -1) {
326 In Linux 2.2 and earlier, the only flag that could be specified
331 In the lead up to the release of the Linux 2.4 kernel,
333 .\" After quite a bit of web and mail archive searching,
334 .\" I could not find the patch on any mailing list, and I
335 .\" could find no place where the rationale for this change
337 a change was made to allow
340 .I ss.ss_flags==SS_ONSTACK
341 with the same meaning as
343 (i.e., the inclusion of
348 On other implementations, and according to POSIX.1,
350 appears only as a reported flag in
351 .IR old_ss.ss_flags .
352 On Linux, there is no need ever to specify
356 and indeed doing so should be avoided on portability grounds:
357 various other systems
358 .\" See the source code of Illumos and FreeBSD, for example.