]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | '\" t |
305a0578 | 2 | .\" Copyright (c) 2001, Michael Kerrisk (mtk-manpages@gmx.net) |
fea681da MK |
3 | .\" |
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. | |
7 | .\" | |
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. | |
12 | .\" | |
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. | |
17 | .\" | |
18 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
19 | .\" the source, must acknowledge the copyright and authors of this work. | |
20 | .\" | |
21 | .\" aeb, various minor fixes | |
cc4615cc | 22 | .TH SIGALTSTACK 2 2007-07-26 "Linux" "Linux Programmer's Manual" |
fea681da | 23 | .SH NAME |
e9496f74 | 24 | sigaltstack \- set and/or get signal stack context |
fea681da MK |
25 | .SH SYNOPSIS |
26 | .B #include <signal.h> | |
27 | .sp | |
28 | .BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss ); | |
cc4615cc MK |
29 | .sp |
30 | .in -4n | |
31 | Feature Test Macro Requirements for glibc (see | |
32 | .BR feature_test_macros (7)): | |
33 | .in | |
34 | .sp | |
35 | .BR sigaltstack (): | |
36 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 | |
37 | .\" .br | |
38 | .\" .BR sigstack (): | |
39 | .\" _BSD_SOURCE || _XOPEN_SOURCE >= 500 | |
fea681da | 40 | .SH DESCRIPTION |
60a90ecd MK |
41 | .BR sigaltstack () |
42 | allows a process to define a new alternate | |
fea681da | 43 | signal stack and/or retrieve the state of an existing |
c13182ef MK |
44 | alternate signal stack. |
45 | An alternate signal stack is used during the | |
fea681da MK |
46 | execution of a signal handler if the establishment of that handler (see |
47 | .BR sigaction (2)) | |
48 | requested it. | |
49 | ||
50 | The normal sequence of events for using an alternate signal stack | |
51 | is the following: | |
52 | .TP | |
53 | 1. | |
54 | Allocate an area of memory to be used for the alternate | |
55 | signal stack. | |
56 | .TP | |
57 | 2. | |
60a90ecd MK |
58 | Use |
59 | .BR sigaltstack () | |
60 | to inform the system of the existence and | |
fea681da MK |
61 | location of the alternate signal stack. |
62 | .TP | |
63 | 3. | |
60a90ecd MK |
64 | When establishing a signal handler using |
65 | .BR sigaction (2), | |
fea681da MK |
66 | inform the system that the signal handler should be executed |
67 | on the alternate signal stack by | |
68 | specifying the \fBSA_ONSTACK\fP flag. | |
69 | .P | |
70 | The \fIss\fP argument is used to specify a new | |
71 | alternate signal stack, while the \fIoss\fP 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 | Each of these arguments is a structure of the following type: | |
77 | .sp | |
78 | .RS | |
79 | .nf | |
80 | typedef struct { | |
81 | void *ss_sp; /* Base address of stack */ | |
82 | int ss_flags; /* Flags */ | |
83 | size_t ss_size; /* Number of bytes in stack */ | |
84 | } stack_t; | |
85 | .fi | |
86 | .RE | |
87 | ||
88 | To establish a new alternate signal stack, | |
75cad981 | 89 | \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and |
fea681da MK |
90 | \fIss.ss_size\fP specify the starting address and size of |
91 | the stack. | |
92 | The constant \fBSIGSTKSZ\fP is defined to be large enough | |
93 | to cover the usual size requirements for an alternate signal stack, | |
94 | and the constant \fBMINSIGSTKSZ\fP defines the minimum | |
95 | size required to execute a signal handler. | |
96 | ||
c13182ef MK |
97 | When a signal handler is invoked on the alternate stack, |
98 | the kernel automatically aligns the address given in \fIss.ss_sp\fP | |
cd31a0d6 | 99 | to a suitable address boundary for the underlying hardware architecture. |
75cad981 | 100 | |
fea681da | 101 | To disable an existing stack, specify \fIss.ss_flags\fP |
c13182ef MK |
102 | as \fBSS_DISABLE\fP. |
103 | In this case, the remaining fields | |
fea681da MK |
104 | in \fIss\fP are ignored. |
105 | ||
106 | If \fIoss\fP is not NULL, then it is used to return information about | |
107 | the alternate signal stack which was in effect prior to the | |
60a90ecd MK |
108 | call to |
109 | .BR sigaltstack (). | |
fea681da MK |
110 | The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting |
111 | address and size of that stack. | |
112 | The \fIoss.ss_flags\fP may return either of the following values: | |
fea681da MK |
113 | .TP |
114 | .B SS_ONSTACK | |
c13182ef MK |
115 | The process is currently executing on the alternate signal stack. |
116 | (Note that it is not possible | |
fea681da MK |
117 | to change the alternate signal stack if the process is |
118 | currently executing on it.) | |
119 | .TP | |
120 | .B SS_DISABLE | |
121 | The alternate signal stack is currently disabled. | |
fea681da | 122 | .SH "RETURN VALUE" |
60a90ecd MK |
123 | .BR sigaltstack () |
124 | returns 0 on success, or \-1 on failure with | |
fea681da | 125 | \fIerrno\fP set to indicate the error. |
fea681da MK |
126 | .SH ERRORS |
127 | .TP | |
128 | .B EFAULT | |
129 | Either \fIss\fP or \fIoss\fP is not NULL and points to an area | |
130 | outside of the process's address space. | |
131 | .TP | |
132 | .B EINVAL | |
133 | \fIss\fP is not NULL and the \fPss_flags\fP field contains | |
2f0af33b MK |
134 | a non-zero value other than |
135 | .BR SS_DISABLE . | |
fea681da MK |
136 | .TP |
137 | .B ENOMEM | |
138 | The specified size of the new alternate signal stack | |
139 | (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP. | |
140 | .TP | |
141 | .B EPERM | |
142 | An attempt was made to change the alternate signal stack while | |
143 | it was active (i.e., the process was already executing | |
144 | on the current alternate signal stack). | |
2dd578fd MK |
145 | .SH "CONFORMING TO" |
146 | SUSv2, SVr4, POSIX.1-2001. | |
889829be MK |
147 | .SH NOTES |
148 | The most common usage of an alternate signal stack is to handle the | |
149 | .B SIGSEGV | |
150 | signal that is generated if the space available for the | |
151 | normal process stack is exhausted: in this case, a signal handler for | |
152 | .B SIGSEGV | |
153 | cannot be invoked on the process stack; if we wish to handle it, | |
154 | we must use an alternate signal stack. | |
fea681da MK |
155 | .P |
156 | Establishing an alternate signal stack is useful if a process | |
157 | expects that it may exhaust its standard stack. | |
158 | This may occur, for example, because the stack grows so large | |
159 | that it encounters the upwardly growing heap, or it reaches a | |
160 | limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP. | |
161 | If the standard stack is exhausted, the kernel sends | |
162 | the process a \fBSIGSEGV\fP signal. | |
163 | In these circumstances the only way to catch this signal is | |
164 | on an alternate signal stack. | |
165 | .P | |
166 | On most hardware architectures supported by Linux, stacks grow | |
0bfa087b | 167 | downwards. |
60a90ecd MK |
168 | .BR sigaltstack () |
169 | automatically takes account | |
fea681da MK |
170 | of the direction of stack growth. |
171 | .P | |
172 | Functions called from a signal handler executing on an alternate | |
173 | signal stack will also use the alternate signal stack. | |
174 | (This also applies to any handlers invoked for other signals while | |
175 | the process is executing on the alternate signal stack.) | |
176 | Unlike the standard stack, the system does not | |
177 | automatically extend the alternate signal stack. | |
178 | Exceeding the allocated size of the alternate signal stack will | |
179 | lead to unpredictable results. | |
180 | .P | |
60a90ecd MK |
181 | A successful call to |
182 | .BR execve (2) | |
183 | removes any existing alternate | |
fea681da MK |
184 | signal stack. |
185 | .P | |
60a90ecd MK |
186 | .BR sigaltstack () |
187 | supersedes the older | |
188 | .BR sigstack () | |
189 | call. | |
190 | For backwards compatibility, glibc also provides | |
191 | .BR sigstack (). | |
192 | All new applications should be written using | |
193 | .BR sigaltstack (). | |
889829be | 194 | .SS History |
d9c1ae64 MK |
195 | 4.2BSD had a |
196 | .BR sigstack () | |
197 | system call. | |
c13182ef | 198 | It used a slightly |
75cad981 | 199 | different struct, and had the major disadvantage that the caller |
fea681da | 200 | had to know the direction of stack growth. |
2b2581ee MK |
201 | .SH EXAMPLE |
202 | The following code segment demonstrates the use of | |
203 | .BR sigaltstack (): | |
204 | ||
205 | .RS | |
206 | .nf | |
207 | stack_t ss; | |
208 | ||
209 | ss.ss_sp = malloc(SIGSTKSZ); | |
210 | if (ss.ss_sp == NULL) | |
211 | /* Handle error */; | |
212 | ss.ss_size = SIGSTKSZ; | |
213 | ss.ss_flags = 0; | |
214 | if (sigaltstack(&ss, NULL) == \-1) | |
215 | /* Handle error */; | |
216 | .fi | |
217 | .RE | |
fea681da MK |
218 | .SH "SEE ALSO" |
219 | .BR execve (2), | |
220 | .BR setrlimit (2), | |
221 | .BR sigaction (2), | |
222 | .BR siglongjmp (3), | |
223 | .BR sigsetjmp (3), | |
224 | .BR signal (7) |