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