Debian Codegraph @

upstream/debian-trixie/man2/sigaltstack.2

raw
1 '\" t
2 .\" Copyright (c) 2001, 2017 Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" aeb, various minor fixes
7 .TH sigaltstack 2 2024-05-02 "Linux man-pages 6.9.1"
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 \fBSA_ONSTACK\fP flag.
62 .P
63 The \fIss\fP argument is used to specify a new
64 alternate signal stack, while the \fIold_ss\fP argument
65 is used to retrieve information about the currently
66 established signal stack.
67 If we are interested in performing just one
68 of these tasks, then the other argument can be specified as NULL.
69 .P
70 The
71 .I stack_t
72 type used to type the arguments of this function is defined as follows:
73 .P
74 .in +4n
75 .EX
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;
81 .EE
82 .in
83 .P
84 To establish a new alternate signal stack,
85 the fields of this structure are set as follows:
86 .TP
87 .I ss.ss_flags
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
98 This flag was added in order to make it safe
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
106 .B EINVAL
107 when this flag is supplied.
108 .RE
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.
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.
122 .P
123 To disable an existing stack, specify \fIss.ss_flags\fP
124 as \fBSS_DISABLE\fP.
125 In this case, the kernel ignores any other flags in
126 .I ss.ss_flags
127 and the remaining fields
128 in \fIss\fP.
129 .P
130 If \fIold_ss\fP is not NULL, then it is used to return information about
131 the alternate signal stack which was in effect prior to the
132 call to
133 .BR sigaltstack ().
134 The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting
135 address and size of that stack.
136 The \fIold_ss.ss_flags\fP may return either of the following values:
137 .TP
138 .B SS_ONSTACK
139 The thread is currently executing on the alternate signal stack.
140 (Note that it is not possible
141 to change the alternate signal stack if the thread is
142 currently executing on it.)
143 .TP
144 .B SS_DISABLE
145 The alternate signal stack is currently disabled.
146 .IP
147 Alternatively, this value is returned if the thread is currently
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.
165 .P
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.
172 .SH RETURN VALUE
173 .BR sigaltstack ()
174 returns 0 on success, or \-1 on failure with
175 \fIerrno\fP set to indicate the error.
176 .SH ERRORS
177 .TP
178 .B EFAULT
179 Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area
180 outside of the process's address space.
181 .TP
182 .B EINVAL
183 \fIss\fP is not NULL and the \fIss_flags\fP field contains
184 an invalid flag.
185 .TP
186 .B ENOMEM
187 The specified size of the new alternate signal stack
188 .I ss.ss_size
189 was less than
190 .BR MINSIGSTKSZ .
191 .TP
192 .B EPERM
193 An attempt was made to change the alternate signal stack while
194 it was active (i.e., the thread was already executing
195 on the current alternate signal stack).
196 .SH ATTRIBUTES
197 For an explanation of the terms used in this section, see
198 .BR attributes (7).
199 .TS
200 allbox;
201 lbx lb lb
202 l l l.
203 Interface Attribute Value
204 T{
205 .na
206 .nh
207 .BR sigaltstack ()
208 T} Thread safety MT-Safe
209 .TE
210 .SH STANDARDS
211 POSIX.1-2008.
212 .P
213 .B SS_AUTODISARM
214 is a Linux extension.
215 .SH HISTORY
216 POSIX.1-2001, SUSv2, SVr4.
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
221 standard stack is exhausted: in this case, a signal handler for
222 .B SIGSEGV
223 cannot be invoked on the standard stack; if we wish to handle it,
224 we must use an alternate signal stack.
225 .P
226 Establishing an alternate signal stack is useful if a thread
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
230 limit established by a call to \fB\%setrlimit(RLIMIT_STACK, &rlim)\fP.
231 If the standard stack is exhausted, the kernel sends
232 the thread a \fBSIGSEGV\fP signal.
233 In these circumstances the only way to catch this signal is
234 on an alternate signal stack.
235 .P
236 On most hardware architectures supported by Linux, stacks grow
237 downward.
238 .BR sigaltstack ()
239 automatically takes account
240 of the direction of stack growth.
241 .P
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
245 the thread is executing on the alternate signal stack.)
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.
250 .P
251 A successful call to
252 .BR execve (2)
253 removes any existing alternate
254 signal stack.
255 A child process created via
256 .BR fork (2)
257 inherits a copy of its parent's alternate signal stack settings.
258 The same is also true for a child process created using
259 .BR clone (2),
260 unless the clone flags include
261 .B CLONE_VM
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.
266 .P
267 .BR sigaltstack ()
268 supersedes the older
269 .BR sigstack ()
270 call.
271 For backward compatibility, glibc also provides
272 .BR sigstack ().
273 All new applications should be written using
274 .BR sigaltstack ().
275 .SS History
276 4.2BSD had a
277 .BR sigstack ()
278 system call.
279 It used a slightly
280 different struct, and had the major disadvantage that the caller
281 had to know the direction of stack growth.
282 .SH BUGS
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 .
288 In the lead up to the release of the Linux 2.4 kernel,
289 .\" Linux 2.3.40
290 .\" After quite a bit of web and mail archive searching,
291 .\" I could not find the patch on any mailing list, and I
292 .\" could find no place where the rationale for this change
293 .\" explained -- mtk
294 a change was made to allow
295 .BR sigaltstack ()
296 to allow
297 .I ss.ss_flags==SS_ONSTACK
298 with the same meaning as
299 .I ss.ss_flags==0
300 (i.e., the inclusion of
301 .B SS_ONSTACK
302 in
303 .I ss.ss_flags
304 is a no-op).
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 .
309 On Linux, there is no need ever to specify
310 .B SS_ONSTACK
311 in
312 .IR ss.ss_flags ,
313 and indeed doing so should be avoided on portability grounds:
314 various other systems
315 .\" See the source code of Illumos and FreeBSD, for example.
316 give an error if
317 .B SS_ONSTACK
318 is specified in
319 .IR ss.ss_flags .
320 .SH EXAMPLES
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
327 .B SIGSEGV
328 signal:
329 .P
330 .in +4n
331 .EX
332 stack_t ss;
333 \&
334 ss.ss_sp = malloc(SIGSTKSZ);
335 if (ss.ss_sp == NULL) {
336 perror("malloc");
337 exit(EXIT_FAILURE);
338 }
339 \&
340 ss.ss_size = SIGSTKSZ;
341 ss.ss_flags = 0;
342 if (sigaltstack(&ss, NULL) == \-1) {
343 perror("sigaltstack");
344 exit(EXIT_FAILURE);
345 }
346 \&
347 sa.sa_flags = SA_ONSTACK;
348 sa.sa_handler = handler(); /* Address of a signal handler */
349 sigemptyset(&sa.sa_mask);
350 if (sigaction(SIGSEGV, &sa, NULL) == \-1) {
351 perror("sigaction");
352 exit(EXIT_FAILURE);
353 }
354 .EE
355 .in
356 .SH SEE ALSO
357 .BR execve (2),
358 .BR setrlimit (2),
359 .BR sigaction (2),
360 .BR siglongjmp (3),
361 .BR sigsetjmp (3),
362 .BR signal (7)