2 .\" Copyright (c) 2001, Michael Kerrisk (mtk.manpages@gmail.com)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" aeb, various minor fixes
25 .TH SIGALTSTACK 2 2008-10-04 "Linux" "Linux Programmer's Manual"
27 sigaltstack \- set and/or get signal stack context
29 .B #include <signal.h>
31 .BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
34 Feature Test Macro Requirements for glibc (see
35 .BR feature_test_macros (7)):
39 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
42 .\" _BSD_SOURCE || _XOPEN_SOURCE >= 500
45 allows a process to define a new alternate
46 signal stack and/or retrieve the state of an existing
47 alternate signal stack.
48 An alternate signal stack is used during the
49 execution of a signal handler if the establishment of that handler (see
53 The normal sequence of events for using an alternate signal stack
57 Allocate an area of memory to be used for the alternate
63 to inform the system of the existence and
64 location of the alternate signal stack.
67 When establishing a signal handler using
69 inform the system that the signal handler should be executed
70 on the alternate signal stack by
71 specifying the \fBSA_ONSTACK\fP flag.
73 The \fIss\fP argument is used to specify a new
74 alternate signal stack, while the \fIoss\fP argument
75 is used to retrieve information about the currently
76 established signal stack.
77 If we are interested in performing just one
78 of these tasks then the other argument can be specified as NULL.
79 Each of these arguments is a structure of the following type:
84 void *ss_sp; /* Base address of stack */
85 int ss_flags; /* Flags */
86 size_t ss_size; /* Number of bytes in stack */
91 To establish a new alternate signal stack,
92 \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
93 \fIss.ss_size\fP specify the starting address and size of
95 The constant \fBSIGSTKSZ\fP is defined to be large enough
96 to cover the usual size requirements for an alternate signal stack,
97 and the constant \fBMINSIGSTKSZ\fP defines the minimum
98 size required to execute a signal handler.
100 When a signal handler is invoked on the alternate stack,
101 the kernel automatically aligns the address given in \fIss.ss_sp\fP
102 to a suitable address boundary for the underlying hardware architecture.
104 To disable an existing stack, specify \fIss.ss_flags\fP
106 In this case, the remaining fields
107 in \fIss\fP are ignored.
109 If \fIoss\fP is not NULL, then it is used to return information about
110 the alternate signal stack which was in effect prior to the
113 The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
114 address and size of that stack.
115 The \fIoss.ss_flags\fP may return either of the following values:
118 The process is currently executing on the alternate signal stack.
119 (Note that it is not possible
120 to change the alternate signal stack if the process is
121 currently executing on it.)
124 The alternate signal stack is currently disabled.
127 returns 0 on success, or \-1 on failure with
128 \fIerrno\fP set to indicate the error.
132 Either \fIss\fP or \fIoss\fP is not NULL and points to an area
133 outside of the process's address space.
136 \fIss\fP is not NULL and the \fIss_flags\fP field contains
137 a nonzero value other than
141 The specified size of the new alternate signal stack
142 (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP.
145 An attempt was made to change the alternate signal stack while
146 it was active (i.e., the process was already executing
147 on the current alternate signal stack).
149 SUSv2, SVr4, POSIX.1-2001.
151 The most common usage of an alternate signal stack is to handle the
153 signal that is generated if the space available for the
154 normal process stack is exhausted: in this case, a signal handler for
156 cannot be invoked on the process stack; if we wish to handle it,
157 we must use an alternate signal stack.
159 Establishing an alternate signal stack is useful if a process
160 expects that it may exhaust its standard stack.
161 This may occur, for example, because the stack grows so large
162 that it encounters the upwardly growing heap, or it reaches a
163 limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
164 If the standard stack is exhausted, the kernel sends
165 the process a \fBSIGSEGV\fP signal.
166 In these circumstances the only way to catch this signal is
167 on an alternate signal stack.
169 On most hardware architectures supported by Linux, stacks grow
172 automatically takes account
173 of the direction of stack growth.
175 Functions called from a signal handler executing on an alternate
176 signal stack will also use the alternate signal stack.
177 (This also applies to any handlers invoked for other signals while
178 the process is executing on the alternate signal stack.)
179 Unlike the standard stack, the system does not
180 automatically extend the alternate signal stack.
181 Exceeding the allocated size of the alternate signal stack will
182 lead to unpredictable results.
186 removes any existing alternate
188 A child process created via
190 inherits a copy of its parent's alternate signal stack settings.
196 For backwards compatibility, glibc also provides
198 All new applications should be written using
205 different struct, and had the major disadvantage that the caller
206 had to know the direction of stack growth.
208 The following code segment demonstrates the use of
215 ss.ss_sp = malloc(SIGSTKSZ);
216 if (ss.ss_sp == NULL)
218 ss.ss_size = SIGSTKSZ;
220 if (sigaltstack(&ss, NULL) == \-1)