2 .\" Copyright (c) 2001, 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 2016-03-15 "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 *" oss );
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 \fIoss\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.
87 Each of these arguments is a structure of the following type:
92 void *ss_sp; /* Base address of stack */
93 int ss_flags; /* Flags */
94 size_t ss_size; /* Number of bytes in stack */
99 To establish a new alternate signal stack,
100 \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
101 \fIss.ss_size\fP specify the starting address and size of
103 The constant \fBSIGSTKSZ\fP is defined to be large enough
104 to cover the usual size requirements for an alternate signal stack,
105 and the constant \fBMINSIGSTKSZ\fP defines the minimum
106 size required to execute a signal handler.
108 When a signal handler is invoked on the alternate stack,
109 the kernel automatically aligns the address given in \fIss.ss_sp\fP
110 to a suitable address boundary for the underlying hardware architecture.
112 To disable an existing stack, specify \fIss.ss_flags\fP
114 In this case, the remaining fields
115 in \fIss\fP are ignored.
117 If \fIoss\fP is not NULL, then it is used to return information about
118 the alternate signal stack which was in effect prior to the
121 The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
122 address and size of that stack.
123 The \fIoss.ss_flags\fP may return either of the following values:
126 The process is currently executing on the alternate signal stack.
127 (Note that it is not possible
128 to change the alternate signal stack if the process is
129 currently executing on it.)
132 The alternate signal stack is currently disabled.
135 returns 0 on success, or \-1 on failure with
136 \fIerrno\fP set to indicate the error.
140 Either \fIss\fP or \fIoss\fP is not NULL and points to an area
141 outside of the process's address space.
144 \fIss\fP is not NULL and the \fIss_flags\fP field contains
145 a nonzero value other than
149 The specified size of the new alternate signal stack
155 An attempt was made to change the alternate signal stack while
156 it was active (i.e., the process was already executing
157 on the current alternate signal stack).
159 For an explanation of the terms used in this section, see
165 Interface Attribute Value
168 T} Thread safety MT-Safe
172 POSIX.1-2001, POSIX.1-2009, SUSv2, SVr4.
174 The most common usage of an alternate signal stack is to handle the
176 signal that is generated if the space available for the
177 normal process stack is exhausted: in this case, a signal handler for
179 cannot be invoked on the process stack; if we wish to handle it,
180 we must use an alternate signal stack.
182 Establishing an alternate signal stack is useful if a process
183 expects that it may exhaust its standard stack.
184 This may occur, for example, because the stack grows so large
185 that it encounters the upwardly growing heap, or it reaches a
186 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
187 If the standard stack is exhausted, the kernel sends
188 the process a \fBSIGSEGV\fP signal.
189 In these circumstances the only way to catch this signal is
190 on an alternate signal stack.
192 On most hardware architectures supported by Linux, stacks grow
195 automatically takes account
196 of the direction of stack growth.
198 Functions called from a signal handler executing on an alternate
199 signal stack will also use the alternate signal stack.
200 (This also applies to any handlers invoked for other signals while
201 the process is executing on the alternate signal stack.)
202 Unlike the standard stack, the system does not
203 automatically extend the alternate signal stack.
204 Exceeding the allocated size of the alternate signal stack will
205 lead to unpredictable results.
209 removes any existing alternate
211 A child process created via
213 inherits a copy of its parent's alternate signal stack settings.
219 For backward compatibility, glibc also provides
221 All new applications should be written using
228 different struct, and had the major disadvantage that the caller
229 had to know the direction of stack growth.
231 The following code segment demonstrates the use of
238 ss.ss_sp = malloc(SIGSTKSZ);
239 if (ss.ss_sp == NULL)
241 ss.ss_size = SIGSTKSZ;
243 if (sigaltstack(&ss, NULL) == \-1)