-
Notifications
You must be signed in to change notification settings - Fork 0
/
sigaltstack.html
468 lines (354 loc) · 14 KB
/
sigaltstack.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:25:49 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>SIGALTSTACK</title>
</head>
<body>
<h1 align="center">SIGALTSTACK</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#ATTRIBUTES">ATTRIBUTES</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#EXAMPLE">EXAMPLE</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">sigaltstack -
set and/or get signal stack context</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<signal.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
sigaltstack(const stack_t *</b><i>ss</i><b>, stack_t
*</b><i>old_ss</i><b>);</b></p>
<p style="margin-left:5%; margin-top: 1em">Feature Test
Macro Requirements for glibc (see
<b>feature_test_macros</b>(7)):</p>
<p style="margin-left:11%; margin-top: 1em"><b>sigaltstack</b>():</p>
<p style="margin-left:17%;">_XOPEN_SOURCE >= 500
<br>
|| /* Since glibc 2.12: */
_POSIX_C_SOURCE >= 200809L <br>
|| /* Glibc versions <= 2.19: */ _BSD_SOURCE</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>sigaltstack</b>()
allows a process to define a new alternate signal stack
and/or retrieve the state of an existing alternate signal
stack. An alternate signal stack is used during the
execution of a signal handler if the establishment of that
handler (see <b>sigaction</b>(2)) requested it.</p>
<p style="margin-left:11%; margin-top: 1em">The normal
sequence of events for using an alternate signal stack is
the following:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>1.</p></td>
<td width="1%"></td>
<td width="85%">
<p>Allocate an area of memory to be used for the alternate
signal stack.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>2.</p></td>
<td width="1%"></td>
<td width="85%">
<p>Use <b>sigaltstack</b>() to inform the system of the
existence and location of the alternate signal stack.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p>3.</p></td>
<td width="1%"></td>
<td width="85%">
<p>When establishing a signal handler using
<b>sigaction</b>(2), inform the system that the signal
handler should be executed on the alternate signal stack by
specifying the <b>SA_ONSTACK</b> flag.</p></td></tr>
</table>
<p style="margin-left:11%; margin-top: 1em">The <i>ss</i>
argument is used to specify a new alternate signal stack,
while the <i>old_ss</i> argument is used to retrieve
information about the currently established signal stack. If
we are interested in performing just one of these tasks,
then the other argument can be specified as NULL.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>stack_t</i> type used to type the arguments of this
function is defined as follows:</p>
<p style="margin-left:17%; margin-top: 1em">typedef struct
{ <br>
void *ss_sp; /* Base address of stack */ <br>
int ss_flags; /* Flags */ <br>
size_t ss_size; /* Number of bytes in stack */ <br>
} stack_t;</p>
<p style="margin-left:11%; margin-top: 1em">To establish a
new alternate signal stack, the fields of this structure are
set as follows: <i><br>
ss.ss_flags</i></p>
<p style="margin-left:22%;">This field contains either 0,
or the following flag: <b><br>
SS_AUTODISARM</b> (since Linux 4.7)</p>
<p style="margin-left:32%;">Clear the alternate signal
stack settings on entry to the signal handler. When the
signal handler returns, the previous alternate signal stack
settings are restored.</p>
<p style="margin-left:32%; margin-top: 1em">This flag was
added in order make it safe to switch away from the signal
handler with <b>swapcontext</b>(3). Without this flag, a
subsequently handled signal will corrupt the state of the
switched-away signal handler. On kernels where this flag is
not supported, <b>sigaltstack</b>() fails with the error
<b>EINVAL</b> when this flag is supplied.</p>
<p style="margin-left:11%;"><i>ss.ss_sp</i></p>
<p style="margin-left:22%;">This field specifies the
starting address of the stack. When a signal handler is
invoked on the alternate stack, the kernel automatically
aligns the address given in <i>ss.ss_sp</i> to a suitable
address boundary for the underlying hardware
architecture.</p>
<p style="margin-left:11%;"><i>ss.ss_size</i></p>
<p style="margin-left:22%;">This field specifies the size
of the stack. The constant <b>SIGSTKSZ</b> is defined to be
large enough to cover the usual size requirements for an
alternate signal stack, and the constant <b>MINSIGSTKSZ</b>
defines the minimum size required to execute a signal
handler.</p>
<p style="margin-left:11%; margin-top: 1em">To disable an
existing stack, specify <i>ss.ss_flags</i> as
<b>SS_DISABLE</b>. In this case, the kernel ignores any
other flags in <i>ss.ss_flags</i> and the remaining fields
in <i>ss</i>.</p>
<p style="margin-left:11%; margin-top: 1em">If
<i>old_ss</i> is not NULL, then it is used to return
information about the alternate signal stack which was in
effect prior to the call to <b>sigaltstack</b>(). The
<i>old_ss.ss_sp</i> and <i>old_ss.ss_size</i> fields return
the starting address and size of that stack. The
<i>old_ss.ss_flags</i> may return either of the following
values: <b><br>
SS_ONSTACK</b></p>
<p style="margin-left:22%;">The process is currently
executing on the alternate signal stack. (Note that it is
not possible to change the alternate signal stack if the
process is currently executing on it.)</p>
<p style="margin-left:11%;"><b>SS_DISABLE</b></p>
<p style="margin-left:22%;">The alternate signal stack is
currently disabled.</p>
<p style="margin-left:22%; margin-top: 1em">Alternatively,
this value is returned if the process is currently executing
on an alternate signal stack that was established using the
<b>SS_AUTODISARM</b> flag. In this case, it is safe to
switch away from the signal handler with
<b>swapcontext</b>(3). It is also possible to set up a
different alternative signal stack using a further call to
<b>sigaltstack</b>().</p>
<p style="margin-left:11%;"><b>SS_AUTODISARM</b></p>
<p style="margin-left:22%;">The alternate signal stack has
been marked to be autodisarmed as described above.</p>
<p style="margin-left:11%; margin-top: 1em">By specifying
<i>ss</i> as NULL, and <i>old_ss</i> as a non-NULL value,
one can obtain the current settings for the alternate signal
stack without changing them.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>sigaltstack</b>()
returns 0 on success, or -1 on failure with <i>errno</i> set
to indicate the error.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EFAULT</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">Either <i>ss</i> or
<i>old_ss</i> is not NULL and points to an area outside of
the process’s address space.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><i>ss</i> is not NULL and the <i>ss_flags</i> field
contains an invalid flag.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ENOMEM</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The specified size of the new alternate signal stack
<i>ss.ss_size</i> was less than <b>MINSIGSTKSZ</b>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EPERM</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>An attempt was made to change the alternate signal stack
while it was active (i.e., the process was already executing
on the current alternate signal stack).</p></td></tr>
</table>
<h2>ATTRIBUTES
<a name="ATTRIBUTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">For an
explanation of the terms used in this section, see
<b>attributes</b>(7).</p>
<p align="center" style="margin-top: 1em"><img src="grohtml-494261.png" alt="Image grohtml-494261.png"></p>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">POSIX.1-2001,
POSIX.1-2008, SUSv2, SVr4.</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>SS_AUTODISARM</b> flag is a Linux extension.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The most common
usage of an alternate signal stack is to handle the
<b>SIGSEGV</b> signal that is generated if the space
available for the normal process stack is exhausted: in this
case, a signal handler for <b>SIGSEGV</b> cannot be invoked
on the process stack; if we wish to handle it, we must use
an alternate signal stack.</p>
<p style="margin-left:11%; margin-top: 1em">Establishing an
alternate signal stack is useful if a process expects that
it may exhaust its standard stack. This may occur, for
example, because the stack grows so large that it encounters
the upwardly growing heap, or it reaches a limit established
by a call to <b>setrlimit(RLIMIT_STACK, &rlim)</b>. If
the standard stack is exhausted, the kernel sends the
process a <b>SIGSEGV</b> signal. In these circumstances the
only way to catch this signal is on an alternate signal
stack.</p>
<p style="margin-left:11%; margin-top: 1em">On most
hardware architectures supported by Linux, stacks grow
downward. <b>sigaltstack</b>() automatically takes account
of the direction of stack growth.</p>
<p style="margin-left:11%; margin-top: 1em">Functions
called from a signal handler executing on an alternate
signal stack will also use the alternate signal stack. (This
also applies to any handlers invoked for other signals while
the process is executing on the alternate signal stack.)
Unlike the standard stack, the system does not automatically
extend the alternate signal stack. Exceeding the allocated
size of the alternate signal stack will lead to
unpredictable results.</p>
<p style="margin-left:11%; margin-top: 1em">A successful
call to <b>execve</b>(2) removes any existing alternate
signal stack. A child process created via <b>fork</b>(2)
inherits a copy of its parent’s alternate signal stack
settings.</p>
<p style="margin-left:11%; margin-top: 1em"><b>sigaltstack</b>()
supersedes the older <b>sigstack</b>() call. For backward
compatibility, glibc also provides <b>sigstack</b>(). All
new applications should be written using
<b>sigaltstack</b>().</p>
<p style="margin-left:11%; margin-top: 1em"><b>History</b>
<br>
4.2BSD had a <b>sigstack</b>() system call. It used a
slightly different struct, and had the major disadvantage
that the caller had to know the direction of stack
growth.</p>
<h2>EXAMPLE
<a name="EXAMPLE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The following
code segment demonstrates the use of <b>sigaltstack</b>()
(and <b>sigaction</b>(2)) to install an alternate signal
stack that is employed by a handler for the <b>SIGSEGV</b>
signal:</p>
<p style="margin-left:17%; margin-top: 1em">stack_t ss;</p>
<p style="margin-left:17%; margin-top: 1em">ss.ss_sp =
malloc(SIGSTKSZ); <br>
if (ss.ss_sp == NULL) { <br>
perror("malloc"); <br>
exit(EXIT_FAILURE); <br>
}</p>
<p style="margin-left:17%; margin-top: 1em">ss.ss_size =
SIGSTKSZ; <br>
ss.ss_flags = 0; <br>
if (sigaltstack(&ss, NULL) == -1) { <br>
perror("sigaltstack"); <br>
exit(EXIT_FAILURE); <br>
}</p>
<p style="margin-left:17%; margin-top: 1em">sa.sa_flags =
SA_ONSTACK; <br>
sa.sa_handler = handler(); /* Address of a signal handler */
<br>
sigemptyset(&sa.sa_mask); <br>
if (sigaction(SIGSEGV, &sa, NULL) == -1) { <br>
perror("sigaction"); <br>
exit(EXIT_FAILURE); <br>
}</p>
<h2>BUGS
<a name="BUGS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">In Linux 2.2
and earlier, the only flag that could be specified in
<i>ss.sa_flags</i> was <b>SS_DISABLE</b>. In the lead up to
the release of the Linux 2.4 kernel, a change was made to
allow <b>sigaltstack</b>() to allow
<i>ss.ss_flags==SS_ONSTACK</i> with the same meaning as
<i>ss.ss_flags==0</i> (i.e., the inclusion of
<b>SS_ONSTACK</b> in <i>ss.ss_flags</i> is a no-op). On
other implementations, and according to POSIX.1,
<b>SS_ONSTACK</b> appears only as a reported flag in
<i>old_ss.ss_flags</i>. On Linux, there is no need ever to
specify <b>SS_ONSTACK</b> in <i>ss.ss_flags</i>, and indeed
doing so should be avoided on portability grounds: various
other systems give an error if <b>SS_ONSTACK</b> is
specified in <i>ss.ss_flags</i>.</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>execve</b>(2),
<b>setrlimit</b>(2), <b>sigaction</b>(2),
<b>siglongjmp</b>(3), <b>sigsetjmp</b>(3),
<b>signal</b>(7)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>