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