1sigaltstack(2) System Calls Manual sigaltstack(2)
2
6 sigaltstack - set and/or get signal stack context
7
9 Standard C library (libc, -lc)
10
12 #include <signal.h>
13 int sigaltstack(const stack_t *_Nullable restrict ss,
15 stack_t *_Nullable restrict old_ss);
16 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18 sigaltstack():
20 _XOPEN_SOURCE >= 500
21 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
22 || /* glibc <= 2.19: */ _BSD_SOURCE
23
25 sigaltstack() allows a thread to define a new alternate signal stack
26 and/or retrieve the state of an existing alternate signal stack. An
27 alternate signal stack is used during the execution of a signal handler
28 if the establishment of that handler (see sigaction(2)) requested it.
29 The normal sequence of events for using an alternate signal stack is
31 the following:
32 1. Allocate an area of memory to be used for the alternate signal
34 stack.
35 2. Use sigaltstack() to inform the system of the existence and location
37 of the alternate signal stack.
38 3. When establishing a signal handler using sigaction(2), inform the
40 system that the signal handler should be executed on the alternate
41 signal stack by specifying the SA_ONSTACK flag.
42 The ss argument is used to specify a new alternate signal stack, while
44 the old_ss argument is used to retrieve information about the currently
45 established signal stack. If we are interested in performing just one
46 of these tasks, then the other argument can be specified as NULL.
47 The stack_t type used to type the arguments of this function is defined
49 as follows:
50 typedef struct {
52 void *ss_sp; /* Base address of stack */
53 int ss_flags; /* Flags */
54 size_t ss_size; /* Number of bytes in stack */
55 } stack_t;
56 To establish a new alternate signal stack, the fields of this structure
58 are set as follows:
59 ss.ss_flags
61 This field contains either 0, or the following flag:
62 SS_AUTODISARM (since Linux 4.7)
64 Clear the alternate signal stack settings on entry to the
65 signal handler. When the signal handler returns, the
66 previous alternate signal stack settings are restored.
67 This flag was added in order to make it safe to switch
69 away from the signal handler with swapcontext(3). With‐
70 out this flag, a subsequently handled signal will corrupt
71 the state of the switched-away signal handler. On ker‐
72 nels where this flag is not supported, sigaltstack()
73 fails with the error EINVAL when this flag is supplied.
74 ss.ss_sp
76 This field specifies the starting address of the stack. When a
77 signal handler is invoked on the alternate stack, the kernel au‐
78 tomatically aligns the address given in ss.ss_sp to a suitable
79 address boundary for the underlying hardware architecture.
80 ss.ss_size
82 This field specifies the size of the stack. The constant
83 SIGSTKSZ is defined to be large enough to cover the usual size
84 requirements for an alternate signal stack, and the constant
85 MINSIGSTKSZ defines the minimum size required to execute a sig‐
86 nal handler.
87 To disable an existing stack, specify ss.ss_flags as SS_DISABLE. In
89 this case, the kernel ignores any other flags in ss.ss_flags and the
90 remaining fields in ss.
91 If old_ss is not NULL, then it is used to return information about the
93 alternate signal stack which was in effect prior to the call to sigalt‐
94 stack(). The old_ss.ss_sp and old_ss.ss_size fields return the start‐
95 ing address and size of that stack. The old_ss.ss_flags may return ei‐
96 ther of the following values:
97 SS_ONSTACK
99 The thread is currently executing on the alternate signal stack.
100 (Note that it is not possible to change the alternate signal
101 stack if the thread is currently executing on it.)
102 SS_DISABLE
104 The alternate signal stack is currently disabled.
105 Alternatively, this value is returned if the thread is currently
107 executing on an alternate signal stack that was established us‐
108 ing the SS_AUTODISARM flag. In this case, it is safe to switch
109 away from the signal handler with swapcontext(3). It is also
110 possible to set up a different alternative signal stack using a
111 further call to sigaltstack().
112 SS_AUTODISARM
114 The alternate signal stack has been marked to be autodisarmed as
115 described above.
116 By specifying ss as NULL, and old_ss as a non-NULL value, one can ob‐
118 tain the current settings for the alternate signal stack without chang‐
119 ing them.
120
122 sigaltstack() returns 0 on success, or -1 on failure with errno set to
123 indicate the error.
124
126 EFAULT Either ss or old_ss is not NULL and points to an area outside of
127 the process's address space.
128 EINVAL ss is not NULL and the ss_flags field contains an invalid flag.
130 ENOMEM The specified size of the new alternate signal stack ss.ss_size
132 was less than MINSIGSTKSZ.
133 EPERM An attempt was made to change the alternate signal stack while
135 it was active (i.e., the thread was already executing on the
136 current alternate signal stack).
137
139 For an explanation of the terms used in this section, see at‐
140 tributes(7).
141 ┌────────────────────────────────────────────┬───────────────┬─────────┐
143 │Interface │ Attribute │ Value │
144 ├────────────────────────────────────────────┼───────────────┼─────────┤
145 │sigaltstack() │ Thread safety │ MT-Safe │
146 └────────────────────────────────────────────┴───────────────┴─────────┘
147
149 POSIX.1-2008.
150 SS_AUTODISARM is a Linux extension.
152
154 POSIX.1-2001, SUSv2, SVr4.
155
157 The most common usage of an alternate signal stack is to handle the
158 SIGSEGV signal that is generated if the space available for the stan‐
159 dard stack is exhausted: in this case, a signal handler for SIGSEGV
160 cannot be invoked on the standard stack; if we wish to handle it, we
161 must use an alternate signal stack.
162 Establishing an alternate signal stack is useful if a thread expects
164 that it may exhaust its standard stack. This may occur, for example,
165 because the stack grows so large that it encounters the upwardly grow‐
166 ing heap, or it reaches a limit established by a call to setrlim‐
167 it(RLIMIT_STACK, &rlim). If the standard stack is exhausted, the ker‐
168 nel sends the thread a SIGSEGV signal. In these circumstances the only
169 way to catch this signal is on an alternate signal stack.
170 On most hardware architectures supported by Linux, stacks grow down‐
172 ward. sigaltstack() automatically takes account of the direction of
173 stack growth.
174 Functions called from a signal handler executing on an alternate signal
176 stack will also use the alternate signal stack. (This also applies to
177 any handlers invoked for other signals while the thread is executing on
178 the alternate signal stack.) Unlike the standard stack, the system
179 does not automatically extend the alternate signal stack. Exceeding
180 the allocated size of the alternate signal stack will lead to unpre‐
181 dictable results.
182 A successful call to execve(2) removes any existing alternate signal
184 stack. A child process created via fork(2) inherits a copy of its par‐
185 ent's alternate signal stack settings. The same is also true for a
186 child process created using clone(2), unless the clone flags include
187 CLONE_VM and do not include CLONE_VFORK, in which case any alternate
188 signal stack that was established in the parent is disabled in the
189 child process.
190 sigaltstack() supersedes the older sigstack() call. For backward com‐
192 patibility, glibc also provides sigstack(). All new applications
193 should be written using sigaltstack().
194 History
196 4.2BSD had a sigstack() system call. It used a slightly different
197 struct, and had the major disadvantage that the caller had to know the
198 direction of stack growth.
199
201 In Linux 2.2 and earlier, the only flag that could be specified in
202 ss.sa_flags was SS_DISABLE. In the lead up to the release of the Linux
203 2.4 kernel, a change was made to allow sigaltstack() to allow
204 ss.ss_flags==SS_ONSTACK with the same meaning as ss.ss_flags==0 (i.e.,
205 the inclusion of SS_ONSTACK in ss.ss_flags is a no-op). On other im‐
206 plementations, and according to POSIX.1, SS_ONSTACK appears only as a
207 reported flag in old_ss.ss_flags. On Linux, there is no need ever to
208 specify SS_ONSTACK in ss.ss_flags, and indeed doing so should be avoid‐
209 ed on portability grounds: various other systems give an error if
210 SS_ONSTACK is specified in ss.ss_flags.
211
213 The following code segment demonstrates the use of sigaltstack() (and
214 sigaction(2)) to install an alternate signal stack that is employed by
215 a handler for the SIGSEGV signal:
216 stack_t ss;
218 ss.ss_sp = malloc(SIGSTKSZ);
220 if (ss.ss_sp == NULL) {
221 perror("malloc");
222 exit(EXIT_FAILURE);
223 }
224 ss.ss_size = SIGSTKSZ;
226 ss.ss_flags = 0;
227 if (sigaltstack(&ss, NULL) == -1) {
228 perror("sigaltstack");
229 exit(EXIT_FAILURE);
230 }
231 sa.sa_flags = SA_ONSTACK;
233 sa.sa_handler = handler(); /* Address of a signal handler */
234 sigemptyset(&sa.sa_mask);
235 if (sigaction(SIGSEGV, &sa, NULL) == -1) {
236 perror("sigaction");
237 exit(EXIT_FAILURE);
238 }
239
241 execve(2), setrlimit(2), sigaction(2), siglongjmp(3), sigsetjmp(3),
242 signal(7)
243Linux man-pages 6.04 2023-03-30 sigaltstack(2)