]>
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 | |
22 | .TH SIGALTSTACK 2 2001-09-27 "Linux 2.4" "Linux Programmer's Manual" | |
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 ); | |
29 | .SH DESCRIPTION | |
60a90ecd MK |
30 | .BR sigaltstack () |
31 | allows a process to define a new alternate | |
fea681da | 32 | signal stack and/or retrieve the state of an existing |
c13182ef MK |
33 | alternate signal stack. |
34 | An alternate signal stack is used during the | |
fea681da MK |
35 | execution of a signal handler if the establishment of that handler (see |
36 | .BR sigaction (2)) | |
37 | requested it. | |
38 | ||
39 | The normal sequence of events for using an alternate signal stack | |
40 | is the following: | |
41 | .TP | |
42 | 1. | |
43 | Allocate an area of memory to be used for the alternate | |
44 | signal stack. | |
45 | .TP | |
46 | 2. | |
60a90ecd MK |
47 | Use |
48 | .BR sigaltstack () | |
49 | to inform the system of the existence and | |
fea681da MK |
50 | location of the alternate signal stack. |
51 | .TP | |
52 | 3. | |
60a90ecd MK |
53 | When establishing a signal handler using |
54 | .BR sigaction (2), | |
fea681da MK |
55 | inform the system that the signal handler should be executed |
56 | on the alternate signal stack by | |
57 | specifying the \fBSA_ONSTACK\fP flag. | |
58 | .P | |
59 | The \fIss\fP argument is used to specify a new | |
60 | alternate signal stack, while the \fIoss\fP argument | |
61 | is used to retrieve information about the currently | |
62 | established signal stack. | |
63 | If we are interested in performing just one | |
64 | of these tasks then the other argument can be specified as NULL. | |
65 | Each of these arguments is a structure of the following type: | |
66 | .sp | |
67 | .RS | |
68 | .nf | |
69 | typedef struct { | |
70 | void *ss_sp; /* Base address of stack */ | |
71 | int ss_flags; /* Flags */ | |
72 | size_t ss_size; /* Number of bytes in stack */ | |
73 | } stack_t; | |
74 | .fi | |
75 | .RE | |
76 | ||
77 | To establish a new alternate signal stack, | |
75cad981 | 78 | \fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and |
fea681da MK |
79 | \fIss.ss_size\fP specify the starting address and size of |
80 | the stack. | |
81 | The constant \fBSIGSTKSZ\fP is defined to be large enough | |
82 | to cover the usual size requirements for an alternate signal stack, | |
83 | and the constant \fBMINSIGSTKSZ\fP defines the minimum | |
84 | size required to execute a signal handler. | |
85 | ||
c13182ef MK |
86 | When a signal handler is invoked on the alternate stack, |
87 | the kernel automatically aligns the address given in \fIss.ss_sp\fP | |
cd31a0d6 | 88 | to a suitable address boundary for the underlying hardware architecture. |
75cad981 | 89 | |
fea681da | 90 | To disable an existing stack, specify \fIss.ss_flags\fP |
c13182ef MK |
91 | as \fBSS_DISABLE\fP. |
92 | In this case, the remaining fields | |
fea681da MK |
93 | in \fIss\fP are ignored. |
94 | ||
95 | If \fIoss\fP is not NULL, then it is used to return information about | |
96 | the alternate signal stack which was in effect prior to the | |
60a90ecd MK |
97 | call to |
98 | .BR sigaltstack (). | |
fea681da MK |
99 | The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting |
100 | address and size of that stack. | |
101 | The \fIoss.ss_flags\fP may return either of the following values: | |
fea681da MK |
102 | .TP |
103 | .B SS_ONSTACK | |
c13182ef MK |
104 | The process is currently executing on the alternate signal stack. |
105 | (Note that it is not possible | |
fea681da MK |
106 | to change the alternate signal stack if the process is |
107 | currently executing on it.) | |
108 | .TP | |
109 | .B SS_DISABLE | |
110 | The alternate signal stack is currently disabled. | |
fea681da | 111 | .SH "RETURN VALUE" |
60a90ecd MK |
112 | .BR sigaltstack () |
113 | returns 0 on success, or \-1 on failure with | |
fea681da | 114 | \fIerrno\fP set to indicate the error. |
fea681da MK |
115 | .SH ERRORS |
116 | .TP | |
117 | .B EFAULT | |
118 | Either \fIss\fP or \fIoss\fP is not NULL and points to an area | |
119 | outside of the process's address space. | |
120 | .TP | |
121 | .B EINVAL | |
122 | \fIss\fP is not NULL and the \fPss_flags\fP field contains | |
123 | a non-zero value other than SS_DISABLE. | |
124 | .TP | |
125 | .B ENOMEM | |
126 | The specified size of the new alternate signal stack | |
127 | (\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP. | |
128 | .TP | |
129 | .B EPERM | |
130 | An attempt was made to change the alternate signal stack while | |
131 | it was active (i.e., the process was already executing | |
132 | on the current alternate signal stack). | |
889829be | 133 | .SH EXAMPLE |
60a90ecd MK |
134 | The following code segment demonstrates the use of |
135 | .BR sigaltstack (): | |
fea681da MK |
136 | |
137 | .RS | |
138 | .nf | |
139 | stack_t ss; | |
140 | ||
141 | ss.ss_sp = malloc(SIGSTKSZ); | |
142 | if (ss.ss_sp == NULL) | |
143 | /* Handle error */; | |
144 | ss.ss_size = SIGSTKSZ; | |
145 | ss.ss_flags = 0; | |
2bc2f479 | 146 | if (sigaltstack(&ss, NULL) == \-1) |
fea681da MK |
147 | /* Handle error */; |
148 | .fi | |
149 | .RE | |
889829be MK |
150 | .SH NOTES |
151 | The most common usage of an alternate signal stack is to handle the | |
152 | .B SIGSEGV | |
153 | signal that is generated if the space available for the | |
154 | normal process stack is exhausted: in this case, a signal handler for | |
155 | .B SIGSEGV | |
156 | cannot be invoked on the process stack; if we wish to handle it, | |
157 | we must use an alternate signal stack. | |
fea681da MK |
158 | .P |
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. | |
168 | .P | |
169 | On most hardware architectures supported by Linux, stacks grow | |
0bfa087b | 170 | downwards. |
60a90ecd MK |
171 | .BR sigaltstack () |
172 | automatically takes account | |
fea681da MK |
173 | of the direction of stack growth. |
174 | .P | |
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. | |
183 | .P | |
60a90ecd MK |
184 | A successful call to |
185 | .BR execve (2) | |
186 | removes any existing alternate | |
fea681da MK |
187 | signal stack. |
188 | .P | |
60a90ecd MK |
189 | .BR sigaltstack () |
190 | supersedes the older | |
191 | .BR sigstack () | |
192 | call. | |
193 | For backwards compatibility, glibc also provides | |
194 | .BR sigstack (). | |
195 | All new applications should be written using | |
196 | .BR sigaltstack (). | |
889829be | 197 | .SS History |
d9c1ae64 MK |
198 | 4.2BSD had a |
199 | .BR sigstack () | |
200 | system call. | |
c13182ef | 201 | It used a slightly |
75cad981 | 202 | different struct, and had the major disadvantage that the caller |
fea681da | 203 | had to know the direction of stack growth. |
fea681da | 204 | .SH "CONFORMING TO" |
97c1eac8 | 205 | SUSv2, SVr4, POSIX.1-2001. |
fea681da MK |
206 | .SH "SEE ALSO" |
207 | .BR execve (2), | |
208 | .BR setrlimit (2), | |
209 | .BR sigaction (2), | |
210 | .BR siglongjmp (3), | |
211 | .BR sigsetjmp (3), | |
212 | .BR signal (7) |