]>
Commit | Line | Data |
---|---|---|
efc626f8 | 1 | .\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
1dd72f9c | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8 | .\" | |
9 | .\" The GNU General Public License's references to "object code" | |
10 | .\" and "executables" are to be interpreted as the output of any | |
11 | .\" document formatting or typesetting system, including | |
12 | .\" intermediate and printed output. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
20 | .\" License along with this manual; if not, see |
21 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 22 | .\" %%%LICENSE_END |
fea681da MK |
23 | .\" |
24 | .\" Added sigsetjmp, Sun Mar 2 22:03:05 EST 1997, jrv@vanzandt.mv.com | |
25 | .\" Modifications, Sun Feb 26 14:39:45 1995, faith@cs.unc.edu | |
26 | .\" " | |
97986708 | 27 | .TH SETJMP 3 2016-03-15 "" "Linux Programmer's Manual" |
fea681da | 28 | .SH NAME |
efc626f8 | 29 | setjmp, sigsetjmp, longjmp, siglongjmp \- performing a nonlocal goto |
fea681da | 30 | .SH SYNOPSIS |
fea681da MK |
31 | .B #include <setjmp.h> |
32 | .sp | |
33 | .nf | |
34 | .BI "int setjmp(jmp_buf " env ); | |
35 | .BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs ); | |
efc626f8 MK |
36 | |
37 | .BI "void longjmp(jmp_buf " env ", int " val ); | |
38 | .BI "void siglongjmp(sigjmp_buf " env ", int " val ); | |
fea681da | 39 | .fi |
cc4615cc MK |
40 | .sp |
41 | .in -4n | |
42 | Feature Test Macro Requirements for glibc (see | |
43 | .BR feature_test_macros (7)): | |
44 | .in | |
45 | .sp | |
e739a268 | 46 | .BR setjmp (): |
efc626f8 | 47 | see NOTES. |
e739a268 | 48 | .br |
cff459de MK |
49 | .BR sigsetjmp (): |
50 | _POSIX_C_SOURCE | |
fea681da | 51 | .SH DESCRIPTION |
efc626f8 MK |
52 | The functions described on this page are used for performing "nonlocal gotos": |
53 | transferring execution from one function to a predetermined location | |
54 | in another function. | |
55 | The | |
60a90ecd | 56 | .BR setjmp () |
efc626f8 MK |
57 | function dynamically establishes the target to which control |
58 | will later be transferred, and | |
59 | .BR longjmp () | |
60 | performs the transfer of execution. | |
61 | ||
62 | The | |
60a90ecd | 63 | .BR setjmp () |
efc626f8 MK |
64 | function saves various information about the calling environment |
65 | (typically, the stack pointer, the instruction pointer, | |
66 | possibly the values of other registers and the signal mask) | |
67 | in the buffer | |
68 | .IR env | |
69 | for later use by | |
70 | .BR longjmp (). | |
71 | In this case, | |
72 | .BR setjmp () | |
73 | returns 0. | |
57f79036 | 74 | |
efc626f8 MK |
75 | The |
76 | .BR longjmp () | |
77 | function uses the information saved in | |
78 | .IR env | |
79 | to transfer control back to the point where | |
60a90ecd | 80 | .BR setjmp () |
efc626f8 MK |
81 | was called and to restore ("rewind") the stack to its state at the time of the |
82 | .BR setjmp () | |
83 | call. | |
84 | In addition, and depending on the implementation (see NOTES), | |
85 | the values of some other registers and the process signal mask | |
86 | may be restored to their state at the time of the | |
87 | .BR setjmp () | |
88 | call. | |
89 | ||
90 | Following a successful | |
91 | .BR longjmp (), | |
92 | execution continues as if | |
93 | .BR setjmp () | |
94 | had returned for a second time. | |
95 | This "fake" return can be distinguished from a true | |
96 | .BR setjmp () | |
97 | call because the "fake" return returns the value provided in | |
98 | .IR val . | |
99 | If the programmer mistakenly passes the value 0 in | |
100 | .IR val , | |
101 | the "fake" return will instead return 1. | |
102 | ||
103 | .SS sigsetjmp() and siglongjmp() | |
60a90ecd | 104 | .BR sigsetjmp () |
efc626f8 MK |
105 | and |
106 | .BR siglongjmp () | |
107 | also perform nonlocal gotos, but provide predictable handling of | |
108 | the process signal mask. | |
109 | ||
110 | If, and only if, the | |
c6fa0841 | 111 | .I savesigs |
efc626f8 MK |
112 | argument provided to |
113 | .BR sigsetjmp () | |
114 | is nonzero, the process's current signal mask is saved in | |
c6fa0841 | 115 | .I env |
1192ed94 | 116 | and will be restored if a |
efc626f8 | 117 | .BR siglongjmp () |
c6fa0841 MK |
118 | is later performed with this |
119 | .IR env . | |
47297adb | 120 | .SH RETURN VALUE |
60a90ecd MK |
121 | .BR setjmp () |
122 | and | |
123 | .BR sigsetjmp () | |
efc626f8 MK |
124 | return 0 when called directly; |
125 | on the "fake" return that occurs after | |
126 | .BR longjmp () | |
c07a3ca3 | 127 | or |
efc626f8 MK |
128 | .BR siglongjmp (), |
129 | the nonzero value specified in | |
130 | .I val | |
131 | is returned. | |
132 | ||
133 | The | |
134 | .BR longjmp () | |
135 | or | |
136 | .BR siglongjmp () | |
137 | functions do not return. | |
7855ffa4 ZL |
138 | .SH ATTRIBUTES |
139 | For an explanation of the terms used in this section, see | |
140 | .BR attributes (7). | |
141 | .TS | |
142 | allbox; | |
efc626f8 | 143 | lbw23 lb lb |
7855ffa4 ZL |
144 | l l l. |
145 | Interface Attribute Value | |
146 | T{ | |
147 | .BR setjmp (), | |
148 | .BR sigsetjmp () | |
149 | T} Thread safety MT-Safe | |
efc626f8 MK |
150 | T{ |
151 | .BR longjmp (), | |
152 | .BR siglongjmp () | |
153 | T} Thread safety MT-Safe | |
7855ffa4 ZL |
154 | .TE |
155 | ||
47297adb | 156 | .SH CONFORMING TO |
efc626f8 MK |
157 | .BR setjmp (), |
158 | .BR longjmp (): | |
55d3f6e3 MK |
159 | POSIX.1-2001, POSIX.1-2008, C89, C99. |
160 | ||
efc626f8 MK |
161 | .BR sigsetjmp (), |
162 | .BR siglongjmp (): | |
55d3f6e3 | 163 | POSIX.1-2001, POSIX.1-2008. |
fea681da | 164 | .SH NOTES |
60a90ecd MK |
165 | POSIX does not specify whether |
166 | .BR setjmp () | |
dbb73b9a MK |
167 | will save the signal mask |
168 | (to be later restored during | |
efc626f8 | 169 | .BR longjmp (). |
e739a268 | 170 | In System V it will not. |
c13182ef | 171 | In 4.3BSD it will, and there |
c6fa0841 MK |
172 | is a function |
173 | .B _setjmp | |
174 | that will not. | |
dbb73b9a | 175 | On Linux with glibc versions before 2.19, |
a896b353 | 176 | .BR setjmp () |
dbb73b9a | 177 | follows the System V behavior by default, |
e739a268 MK |
178 | but the BSD behavior is provided if the |
179 | .BR _BSD_SOURCE | |
180 | feature test macro is defined and none of | |
181 | .BR _POSIX_SOURCE , | |
182 | .BR _POSIX_C_SOURCE , | |
183 | .BR _XOPEN_SOURCE , | |
3dd87b7c | 184 | .\" .BR _XOPEN_SOURCE_EXTENDED , |
e739a268 MK |
185 | .BR _GNU_SOURCE , |
186 | or | |
187 | .B _SVID_SOURCE | |
188 | is defined. | |
dbb73b9a MK |
189 | Since glibc 2.19, |
190 | .IR <setjmp.h> | |
191 | exposes only the System V version of | |
192 | .BR setjmp (). | |
193 | Programs that need the BSD semantics should replace calls to | |
194 | .BR setjmp () | |
195 | with calls to | |
196 | .BR sigsetjmp () | |
197 | with a nonzero | |
198 | .I savesigs | |
199 | argument. | |
e739a268 | 200 | |
efc626f8 MK |
201 | .BR setjmp () |
202 | and | |
203 | .BR longjmp (3) | |
204 | can be useful for dealing with errors inside deeply nested function calls | |
205 | or to allow a signal handler to pass control to | |
206 | a specific point in the program, | |
207 | rather than returning to the point where the handler interrupted | |
208 | the main program. | |
209 | In the latter case, | |
210 | if you want to portably save and restore signal masks, use | |
1192ed94 MK |
211 | .BR sigsetjmp () |
212 | and | |
efc626f8 MK |
213 | .BR siglongjmp (). |
214 | See also the discussion of program readability below. | |
40518066 | 215 | |
efc626f8 MK |
216 | The compiler may optimize variables into registers, and |
217 | .BR longjmp () | |
218 | may restore the values of other registers in addition to the | |
219 | stack pointer and program counter. | |
220 | Consequently, the values of automatic variables are unspecified | |
221 | after a call to | |
222 | .BR longjmp () | |
223 | if they meet all the following criteria: | |
224 | .IP \(bu 3 | |
225 | they are local to the function that made the corresponding | |
226 | .BR setjmp (3) | |
227 | call; | |
228 | .IP \(bu | |
229 | their values are changed between the calls to | |
230 | .BR setjmp (3) | |
231 | and | |
232 | .BR longjmp (); | |
233 | and | |
234 | .IP \(bu | |
235 | they are not declared as | |
236 | .IR volatile . | |
237 | .P | |
238 | Analogous remarks apply for | |
239 | .BR siglongjmp (). | |
240 | .\" | |
241 | .SS Nonlocal gotos and program readability | |
40518066 MK |
242 | While it can be abused, |
243 | the traditional C "goto" statement at least has the benefit that lexical cues | |
244 | (the goto statement and the target label) | |
efc626f8 | 245 | allow the programmer to easily perceive the flow of control. |
40518066 | 246 | Nonlocal gotos provide no such cues: multiple |
efc626f8 | 247 | .BR setjmp () |
40518066 MK |
248 | calls might employ the same |
249 | .IR jmp_buf | |
250 | variable so that the content of the variable may change | |
251 | over the lifetime of the application. | |
252 | Consequently, the programmer may be forced to perform detailed | |
efc626f8 MK |
253 | reading of the code to determine the dynamic target of a particular |
254 | .BR longjmp () | |
40518066 MK |
255 | call. |
256 | (To make the programmer's life easier, each | |
60a90ecd | 257 | .BR setjmp () |
40518066 MK |
258 | call should employ a unique |
259 | .IR jmp_buf | |
260 | variable.) | |
efc626f8 MK |
261 | |
262 | Adding further difficulty, the | |
263 | .BR setjmp () | |
264 | and | |
265 | .BR longjmp () | |
266 | calls may not even be in the same source code module. | |
267 | ||
268 | In summary, nonlocal gotos can make programs harder to understand | |
269 | and maintain, and an alternative should be used if possible. | |
270 | .\" | |
271 | .SS Caveats | |
272 | If the function which called | |
273 | .BR setjmp () | |
274 | returns before | |
275 | .BR longjmp () | |
276 | is called, the behavior is undefined. | |
277 | Some kind of subtle or unsubtle chaos is sure to result. | |
278 | ||
279 | If, in a multithreaded program, a | |
280 | .BR longjmp () | |
281 | call employs an | |
282 | .I env | |
283 | buffer that was initialized by a call to | |
284 | .BR setjmp () | |
285 | in a different thread, the behavior is undefined. | |
286 | .\" | |
287 | .\" The following statement appeared in versions up to POSIX.1-2008 TC1, | |
288 | .\" but is set to be removed in POSIX.1-2008 TC2: | |
289 | .\" | |
290 | .\" According to POSIX.1, if a | |
291 | .\" .BR longjmp () | |
292 | .\" call is performed from a nested signal handler | |
293 | .\" (i.e., from a handler that was invoked in response to a signal that was | |
294 | .\" generated while another signal was already in the process of being | |
295 | .\" handled), the behavior is undefined. | |
f1d6ee62 MK |
296 | |
297 | POSIX.1-2008 Technical Corrigendum 2 adds | |
298 | .\" http://austingroupbugs.net/view.php?id=516#c1195 | |
299 | .BR longjmp () | |
300 | and | |
082efcce | 301 | .BR siglongjmp () |
f1d6ee62 MK |
302 | to the list of async-signal-safe functions. |
303 | However, the standard recommends avoiding the use of these functions | |
304 | from signal handlers and goes on to point out that | |
305 | if these functions are called from a signal handler that interrupted | |
306 | a call to a non-async-signal-safe function (or some equivalent, | |
307 | such as the steps equivalent to | |
308 | .BR exit (3) | |
309 | that occur upon a return from the initial call to | |
310 | .IR main ()), | |
311 | the behavior is undefined if the program subsequently makes a call to | |
332aaf19 | 312 | a non-async-signal-safe function. |
f1d6ee62 MK |
313 | The only way of avoiding undefined behavior is to ensure one of the following: |
314 | .IP * 3 | |
315 | After long jumping from the signal handler, | |
316 | the program does not call any non-async-signal-safe functions | |
317 | and does not return from the initial call to | |
318 | .IR main (). | |
319 | .IP * | |
320 | Any signal whose handler performs a long jump must be blocked during | |
321 | .I every | |
322 | call to a non-async-signal-safe function and | |
323 | no non-async-signal-safe functions are called after | |
324 | returning from the initial call to | |
325 | .IR main (). | |
47297adb | 326 | .SH SEE ALSO |
efc626f8 | 327 | .BR signal (7) |