]>
Commit | Line | Data |
---|---|---|
cfdc176b | 1 | .\" Copyright (c) 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" aeb, various minor fixes | |
1d767b55 | 6 | .TH SIGALTSTACK 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da | 7 | .SH NAME |
e9496f74 | 8 | sigaltstack \- set and/or get signal stack context |
b483887b AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
fea681da | 12 | .SH SYNOPSIS |
c7db92b9 | 13 | .nf |
fea681da | 14 | .B #include <signal.h> |
68e4db0a | 15 | .PP |
c1603508 AC |
16 | .BI "int sigaltstack(const stack_t *restrict " ss \ |
17 | ", stack_t *restrict " old_ss ); | |
c7db92b9 | 18 | .fi |
5270d24e | 19 | .PP |
d39ad78f | 20 | .RS -4 |
cc4615cc MK |
21 | Feature Test Macro Requirements for glibc (see |
22 | .BR feature_test_macros (7)): | |
d39ad78f | 23 | .RE |
5270d24e | 24 | .PP |
cc4615cc | 25 | .BR sigaltstack (): |
9d2adbae | 26 | .nf |
5c10d2c5 MK |
27 | _XOPEN_SOURCE >= 500 |
28 | .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED | |
29 | || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L | |
9d2adbae MK |
30 | || /* Glibc <= 2.19: */ _BSD_SOURCE |
31 | .fi | |
fea681da | 32 | .SH DESCRIPTION |
60a90ecd | 33 | .BR sigaltstack () |
3b7d8996 | 34 | allows a thread to define a new alternate |
fea681da | 35 | signal stack and/or retrieve the state of an existing |
c13182ef MK |
36 | alternate signal stack. |
37 | An alternate signal stack is used during the | |
fea681da MK |
38 | execution of a signal handler if the establishment of that handler (see |
39 | .BR sigaction (2)) | |
40 | requested it. | |
5270d24e | 41 | .PP |
fea681da MK |
42 | The normal sequence of events for using an alternate signal stack |
43 | is the following: | |
d1b4e37d | 44 | .TP 3 |
fea681da MK |
45 | 1. |
46 | Allocate an area of memory to be used for the alternate | |
47 | signal stack. | |
48 | .TP | |
49 | 2. | |
60a90ecd MK |
50 | Use |
51 | .BR sigaltstack () | |
52 | to inform the system of the existence and | |
fea681da MK |
53 | location of the alternate signal stack. |
54 | .TP | |
55 | 3. | |
60a90ecd MK |
56 | When establishing a signal handler using |
57 | .BR sigaction (2), | |
fea681da MK |
58 | inform the system that the signal handler should be executed |
59 | on the alternate signal stack by | |
60 | specifying the \fBSA_ONSTACK\fP flag. | |
11ac5b51 | 61 | .PP |
fea681da | 62 | The \fIss\fP argument is used to specify a new |
6635bc01 | 63 | alternate signal stack, while the \fIold_ss\fP argument |
fea681da MK |
64 | is used to retrieve information about the currently |
65 | established signal stack. | |
66 | If we are interested in performing just one | |
7e546372 | 67 | of these tasks, then the other argument can be specified as NULL. |
1614a085 MK |
68 | .PP |
69 | The | |
70 | .I stack_t | |
71 | type used to type the arguments of this function is defined as follows: | |
efeece04 | 72 | .PP |
bd191423 | 73 | .in +4n |
b8302363 | 74 | .EX |
fea681da MK |
75 | typedef struct { |
76 | void *ss_sp; /* Base address of stack */ | |
77 | int ss_flags; /* Flags */ | |
78 | size_t ss_size; /* Number of bytes in stack */ | |
79 | } stack_t; | |
b8302363 | 80 | .EE |
bd191423 | 81 | .in |
efeece04 | 82 | .PP |
fea681da | 83 | To establish a new alternate signal stack, |
1614a085 MK |
84 | the fields of this structure are set as follows: |
85 | .TP | |
86 | .I ss.ss_flags | |
cfdc176b MK |
87 | This field contains either 0, or the following flag: |
88 | .RS | |
89 | .TP | |
90 | .BR SS_AUTODISARM " (since Linux 4.7)" | |
91 | .\" commit 2a74213838104a41588d86fd5e8d344972891ace | |
92 | .\" See tools/testing/selftests/sigaltstack/sas.c in kernel sources | |
93 | Clear the alternate signal stack settings on entry to the signal handler. | |
94 | When the signal handler returns, | |
95 | the previous alternate signal stack settings are restored. | |
96 | .IP | |
67238a53 | 97 | This flag was added in order to make it safe |
cfdc176b MK |
98 | to switch away from the signal handler with |
99 | .BR swapcontext (3). | |
100 | Without this flag, a subsequently handled signal will corrupt | |
101 | the state of the switched-away signal handler. | |
102 | On kernels where this flag is not supported, | |
103 | .BR sigaltstack () | |
104 | fails with the error | |
1ae6b2c7 | 105 | .B EINVAL |
cfdc176b MK |
106 | when this flag is supplied. |
107 | .RE | |
1614a085 MK |
108 | .TP |
109 | .I ss.ss_sp | |
110 | This field specifies the starting address of the stack. | |
111 | When a signal handler is invoked on the alternate stack, | |
112 | the kernel automatically aligns the address given in \fIss.ss_sp\fP | |
113 | to a suitable address boundary for the underlying hardware architecture. | |
114 | .TP | |
115 | .I ss.ss_size | |
116 | This field specifies the size of the stack. | |
fea681da MK |
117 | The constant \fBSIGSTKSZ\fP is defined to be large enough |
118 | to cover the usual size requirements for an alternate signal stack, | |
119 | and the constant \fBMINSIGSTKSZ\fP defines the minimum | |
120 | size required to execute a signal handler. | |
5270d24e | 121 | .PP |
fea681da | 122 | To disable an existing stack, specify \fIss.ss_flags\fP |
c13182ef | 123 | as \fBSS_DISABLE\fP. |
cfdc176b | 124 | In this case, the kernel ignores any other flags in |
1ae6b2c7 | 125 | .I ss.ss_flags |
cfdc176b MK |
126 | and the remaining fields |
127 | in \fIss\fP. | |
5270d24e | 128 | .PP |
6635bc01 | 129 | If \fIold_ss\fP is not NULL, then it is used to return information about |
fea681da | 130 | the alternate signal stack which was in effect prior to the |
60a90ecd MK |
131 | call to |
132 | .BR sigaltstack (). | |
6635bc01 | 133 | The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting |
fea681da | 134 | address and size of that stack. |
6635bc01 | 135 | The \fIold_ss.ss_flags\fP may return either of the following values: |
fea681da MK |
136 | .TP |
137 | .B SS_ONSTACK | |
3b7d8996 | 138 | The thread is currently executing on the alternate signal stack. |
c13182ef | 139 | (Note that it is not possible |
3b7d8996 | 140 | to change the alternate signal stack if the thread is |
fea681da MK |
141 | currently executing on it.) |
142 | .TP | |
143 | .B SS_DISABLE | |
144 | The alternate signal stack is currently disabled. | |
cfdc176b | 145 | .IP |
3b7d8996 | 146 | Alternatively, this value is returned if the thread is currently |
cfdc176b MK |
147 | executing on an alternate signal stack that was established using the |
148 | .B SS_AUTODISARM | |
149 | flag. | |
150 | In this case, it is safe to switch away from the signal handler with | |
151 | .BR swapcontext (3). | |
152 | It is also possible to set up a different alternative signal stack | |
153 | using a further call to | |
154 | .BR sigaltstack (). | |
155 | .\" FIXME Was it intended that one can set up a different alternative | |
156 | .\" signal stack in this scenario? (In passing, if one does this, the | |
157 | .\" sigaltstack(NULL, &old_ss) now returns old_ss.ss_flags==SS_AUTODISARM | |
158 | .\" rather than old_ss.ss_flags==SS_DISABLE. The API design here seems | |
159 | .\" confusing... | |
160 | .TP | |
161 | .B SS_AUTODISARM | |
162 | The alternate signal stack has been marked to be autodisarmed | |
163 | as described above. | |
b3e2be83 MK |
164 | .PP |
165 | By specifying | |
166 | .I ss | |
167 | as NULL, and | |
168 | .I old_ss | |
169 | as a non-NULL value, one can obtain the current settings for | |
170 | the alternate signal stack without changing them. | |
47297adb | 171 | .SH RETURN VALUE |
60a90ecd MK |
172 | .BR sigaltstack () |
173 | returns 0 on success, or \-1 on failure with | |
fea681da | 174 | \fIerrno\fP set to indicate the error. |
fea681da MK |
175 | .SH ERRORS |
176 | .TP | |
177 | .B EFAULT | |
6635bc01 | 178 | Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area |
fea681da MK |
179 | outside of the process's address space. |
180 | .TP | |
181 | .B EINVAL | |
6c5dedd3 | 182 | \fIss\fP is not NULL and the \fIss_flags\fP field contains |
bc2fcb73 | 183 | an invalid flag. |
fea681da MK |
184 | .TP |
185 | .B ENOMEM | |
186 | The specified size of the new alternate signal stack | |
0c892e5b | 187 | .I ss.ss_size |
c435eb91 | 188 | was less than |
6699401b | 189 | .BR MINSIGSTKSZ . |
fea681da MK |
190 | .TP |
191 | .B EPERM | |
192 | An attempt was made to change the alternate signal stack while | |
3b7d8996 | 193 | it was active (i.e., the thread was already executing |
fea681da | 194 | on the current alternate signal stack). |
8d537684 ZL |
195 | .SH ATTRIBUTES |
196 | For an explanation of the terms used in this section, see | |
197 | .BR attributes (7). | |
c466875e MK |
198 | .ad l |
199 | .nh | |
8d537684 ZL |
200 | .TS |
201 | allbox; | |
c466875e | 202 | lbx lb lb |
8d537684 ZL |
203 | l l l. |
204 | Interface Attribute Value | |
205 | T{ | |
206 | .BR sigaltstack () | |
207 | T} Thread safety MT-Safe | |
208 | .TE | |
c466875e MK |
209 | .hy |
210 | .ad | |
211 | .sp 1 | |
47297adb | 212 | .SH CONFORMING TO |
4d4ee4bf | 213 | POSIX.1-2001, POSIX.1-2008, SUSv2, SVr4. |
eff26dce | 214 | .PP |
cfdc176b MK |
215 | The |
216 | .B SS_AUTODISARM | |
217 | flag is a Linux extension. | |
889829be MK |
218 | .SH NOTES |
219 | The most common usage of an alternate signal stack is to handle the | |
220 | .B SIGSEGV | |
221 | signal that is generated if the space available for the | |
3b7d8996 | 222 | standard stack is exhausted: in this case, a signal handler for |
889829be | 223 | .B SIGSEGV |
3b7d8996 | 224 | cannot be invoked on the standard stack; if we wish to handle it, |
889829be | 225 | we must use an alternate signal stack. |
11ac5b51 | 226 | .PP |
3b7d8996 | 227 | Establishing an alternate signal stack is useful if a thread |
fea681da MK |
228 | expects that it may exhaust its standard stack. |
229 | This may occur, for example, because the stack grows so large | |
230 | that it encounters the upwardly growing heap, or it reaches a | |
231 | limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP. | |
232 | If the standard stack is exhausted, the kernel sends | |
3b7d8996 | 233 | the thread a \fBSIGSEGV\fP signal. |
fea681da MK |
234 | In these circumstances the only way to catch this signal is |
235 | on an alternate signal stack. | |
11ac5b51 | 236 | .PP |
fea681da | 237 | On most hardware architectures supported by Linux, stacks grow |
5fab2e7c | 238 | downward. |
60a90ecd MK |
239 | .BR sigaltstack () |
240 | automatically takes account | |
fea681da | 241 | of the direction of stack growth. |
11ac5b51 | 242 | .PP |
fea681da MK |
243 | Functions called from a signal handler executing on an alternate |
244 | signal stack will also use the alternate signal stack. | |
245 | (This also applies to any handlers invoked for other signals while | |
3b7d8996 | 246 | the thread is executing on the alternate signal stack.) |
fea681da MK |
247 | Unlike the standard stack, the system does not |
248 | automatically extend the alternate signal stack. | |
249 | Exceeding the allocated size of the alternate signal stack will | |
250 | lead to unpredictable results. | |
11ac5b51 | 251 | .PP |
60a90ecd MK |
252 | A successful call to |
253 | .BR execve (2) | |
254 | removes any existing alternate | |
fea681da | 255 | signal stack. |
6d017952 | 256 | A child process created via |
0b80cf56 | 257 | .BR fork (2) |
6d017952 | 258 | inherits a copy of its parent's alternate signal stack settings. |
52e5819c MK |
259 | The same is also true for a child process created using |
260 | .BR clone (2), | |
261 | unless the clone flags include | |
1ae6b2c7 | 262 | .B CLONE_VM |
52e5819c MK |
263 | and do not include |
264 | .BR CLONE_VFORK , | |
265 | in which case any alternate signal stack that was established in the parent | |
266 | is disabled in the child process. | |
11ac5b51 | 267 | .PP |
60a90ecd MK |
268 | .BR sigaltstack () |
269 | supersedes the older | |
270 | .BR sigstack () | |
271 | call. | |
5fab2e7c | 272 | For backward compatibility, glibc also provides |
60a90ecd MK |
273 | .BR sigstack (). |
274 | All new applications should be written using | |
275 | .BR sigaltstack (). | |
889829be | 276 | .SS History |
d9c1ae64 MK |
277 | 4.2BSD had a |
278 | .BR sigstack () | |
279 | system call. | |
c13182ef | 280 | It used a slightly |
75cad981 | 281 | different struct, and had the major disadvantage that the caller |
fea681da | 282 | had to know the direction of stack growth. |
27009c99 | 283 | .SH BUGS |
a86cae61 MK |
284 | In Linux 2.2 and earlier, the only flag that could be specified |
285 | in | |
286 | .I ss.sa_flags | |
287 | was | |
288 | .BR SS_DISABLE . | |
006ac5f0 | 289 | In the lead up to the release of the Linux 2.4 kernel, |
27009c99 | 290 | .\" Linux 2.3.40 |
006ac5f0 | 291 | .\" After quite a bit of web and mail archive searching, |
c6688cd1 | 292 | .\" I could not find the patch on any mailing list, and I |
006ac5f0 MK |
293 | .\" could find no place where the rationale for this change |
294 | .\" explained -- mtk | |
295 | a change was made to allow | |
296 | .BR sigaltstack () | |
a86cae61 MK |
297 | to allow |
298 | .I ss.ss_flags==SS_ONSTACK | |
299 | with the same meaning as | |
1ae6b2c7 | 300 | .I ss.ss_flags==0 |
a86cae61 | 301 | (i.e., the inclusion of |
006ac5f0 MK |
302 | .B SS_ONSTACK |
303 | in | |
304 | .I ss.ss_flags | |
305 | is a no-op). | |
27009c99 MK |
306 | On other implementations, and according to POSIX.1, |
307 | .B SS_ONSTACK | |
308 | appears only as a reported flag in | |
309 | .IR old_ss.ss_flags . | |
a86cae61 MK |
310 | On Linux, there is no need ever to specify |
311 | .B SS_ONSTACK | |
312 | in | |
006ac5f0 MK |
313 | .IR ss.ss_flags , |
314 | and indeed doing so should be avoided on portability grounds: | |
315 | various other systems | |
e710f10c MK |
316 | .\" See the source code of Illumos and FreeBSD, for example. |
317 | give an error if | |
318 | .B SS_ONSTACK | |
319 | is specified in | |
006ac5f0 | 320 | .IR ss.ss_flags . |
a14af333 | 321 | .SH EXAMPLES |
81b8997f MK |
322 | The following code segment demonstrates the use of |
323 | .BR sigaltstack () | |
324 | (and | |
325 | .BR sigaction (2)) | |
326 | to install an alternate signal stack that is employed by a handler | |
327 | for the | |
1ae6b2c7 | 328 | .B SIGSEGV |
81b8997f MK |
329 | signal: |
330 | .PP | |
331 | .in +4n | |
332 | .EX | |
333 | stack_t ss; | |
334 | ||
335 | ss.ss_sp = malloc(SIGSTKSZ); | |
336 | if (ss.ss_sp == NULL) { | |
337 | perror("malloc"); | |
338 | exit(EXIT_FAILURE); | |
339 | } | |
340 | ||
341 | ss.ss_size = SIGSTKSZ; | |
342 | ss.ss_flags = 0; | |
343 | if (sigaltstack(&ss, NULL) == \-1) { | |
344 | perror("sigaltstack"); | |
345 | exit(EXIT_FAILURE); | |
346 | } | |
347 | ||
348 | sa.sa_flags = SA_ONSTACK; | |
349 | sa.sa_handler = handler(); /* Address of a signal handler */ | |
350 | sigemptyset(&sa.sa_mask); | |
0a23e9aa | 351 | if (sigaction(SIGSEGV, &sa, NULL) == \-1) { |
81b8997f MK |
352 | perror("sigaction"); |
353 | exit(EXIT_FAILURE); | |
354 | } | |
355 | .EE | |
356 | .in | |
47297adb | 357 | .SH SEE ALSO |
fea681da MK |
358 | .BR execve (2), |
359 | .BR setrlimit (2), | |
360 | .BR sigaction (2), | |
361 | .BR siglongjmp (3), | |
362 | .BR sigsetjmp (3), | |
363 | .BR signal (7) |