Debian Codegraph @

upstream/debian-unstable/man2/sigaltstack.2

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