]>
Commit | Line | Data |
---|---|---|
5ce8f203 | 1 | @node Non-Local Exits, Signal Handling, Resource Usage And Limitation, Top |
7a68c94a | 2 | @c %MENU% Jumping out of nested function calls |
28f540f4 RM |
3 | @chapter Non-Local Exits |
4 | @cindex non-local exits | |
5 | @cindex long jumps | |
6 | ||
7 | Sometimes when your program detects an unusual situation inside a deeply | |
8 | nested set of function calls, you would like to be able to immediately | |
9 | return to an outer level of control. This section describes how you can | |
10 | do such @dfn{non-local exits} using the @code{setjmp} and @code{longjmp} | |
11 | functions. | |
12 | ||
13 | @menu | |
14 | * Intro: Non-Local Intro. When and how to use these facilities. | |
eacde9d0 | 15 | * Details: Non-Local Details. Functions for non-local exits. |
28f540f4 | 16 | * Non-Local Exits and Signals:: Portability issues. |
eacde9d0 | 17 | * System V contexts:: Complete context control a la System V. |
28f540f4 RM |
18 | @end menu |
19 | ||
20 | @node Non-Local Intro, Non-Local Details, , Non-Local Exits | |
21 | @section Introduction to Non-Local Exits | |
22 | ||
23 | As an example of a situation where a non-local exit can be useful, | |
24 | suppose you have an interactive program that has a ``main loop'' that | |
25 | prompts for and executes commands. Suppose the ``read'' command reads | |
26 | input from a file, doing some lexical analysis and parsing of the input | |
27 | while processing it. If a low-level input error is detected, it would | |
28 | be useful to be able to return immediately to the ``main loop'' instead | |
29 | of having to make each of the lexical analysis, parsing, and processing | |
30 | phases all have to explicitly deal with error situations initially | |
31 | detected by nested calls. | |
32 | ||
33 | (On the other hand, if each of these phases has to do a substantial | |
34 | amount of cleanup when it exits---such as closing files, deallocating | |
35 | buffers or other data structures, and the like---then it can be more | |
36 | appropriate to do a normal return and have each phase do its own | |
37 | cleanup, because a non-local exit would bypass the intervening phases and | |
38 | their associated cleanup code entirely. Alternatively, you could use a | |
39 | non-local exit but do the cleanup explicitly either before or after | |
40 | returning to the ``main loop''.) | |
41 | ||
42 | In some ways, a non-local exit is similar to using the @samp{return} | |
43 | statement to return from a function. But while @samp{return} abandons | |
44 | only a single function call, transferring control back to the point at | |
45 | which it was called, a non-local exit can potentially abandon many | |
46 | levels of nested function calls. | |
47 | ||
76c23bac | 48 | You identify return points for non-local exits by calling the function |
28f540f4 RM |
49 | @code{setjmp}. This function saves information about the execution |
50 | environment in which the call to @code{setjmp} appears in an object of | |
51 | type @code{jmp_buf}. Execution of the program continues normally after | |
76c23bac | 52 | the call to @code{setjmp}, but if an exit is later made to this return |
28f540f4 RM |
53 | point by calling @code{longjmp} with the corresponding @w{@code{jmp_buf}} |
54 | object, control is transferred back to the point where @code{setjmp} was | |
55 | called. The return value from @code{setjmp} is used to distinguish | |
56 | between an ordinary return and a return made by a call to | |
57 | @code{longjmp}, so calls to @code{setjmp} usually appear in an @samp{if} | |
58 | statement. | |
59 | ||
f65fd747 | 60 | Here is how the example program described above might be set up: |
28f540f4 RM |
61 | |
62 | @smallexample | |
63 | @include setjmp.c.texi | |
64 | @end smallexample | |
65 | ||
66 | The function @code{abort_to_main_loop} causes an immediate transfer of | |
67 | control back to the main loop of the program, no matter where it is | |
68 | called from. | |
69 | ||
70 | The flow of control inside the @code{main} function may appear a little | |
71 | mysterious at first, but it is actually a common idiom with | |
72 | @code{setjmp}. A normal call to @code{setjmp} returns zero, so the | |
73 | ``else'' clause of the conditional is executed. If | |
74 | @code{abort_to_main_loop} is called somewhere within the execution of | |
75 | @code{do_command}, then it actually appears as if the @emph{same} call | |
76 | to @code{setjmp} in @code{main} were returning a second time with a value | |
77 | of @code{-1}. | |
78 | ||
79 | @need 250 | |
80 | So, the general pattern for using @code{setjmp} looks something like: | |
81 | ||
82 | @smallexample | |
83 | if (setjmp (@var{buffer})) | |
84 | /* @r{Code to clean up after premature return.} */ | |
85 | @dots{} | |
86 | else | |
87 | /* @r{Code to be executed normally after setting up the return point.} */ | |
88 | @dots{} | |
89 | @end smallexample | |
90 | ||
91 | @node Non-Local Details, Non-Local Exits and Signals, Non-Local Intro, Non-Local Exits | |
92 | @section Details of Non-Local Exits | |
93 | ||
94 | Here are the details on the functions and data structures used for | |
95 | performing non-local exits. These facilities are declared in | |
96 | @file{setjmp.h}. | |
97 | @pindex setjmp.h | |
98 | ||
28f540f4 | 99 | @deftp {Data Type} jmp_buf |
d08a7e4c | 100 | @standards{ISO, setjmp.h} |
28f540f4 RM |
101 | Objects of type @code{jmp_buf} hold the state information to |
102 | be restored by a non-local exit. The contents of a @code{jmp_buf} | |
103 | identify a specific place to return to. | |
104 | @end deftp | |
105 | ||
28f540f4 | 106 | @deftypefn Macro int setjmp (jmp_buf @var{state}) |
d08a7e4c | 107 | @standards{ISO, setjmp.h} |
542210fb AO |
108 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
109 | @c _setjmp ok | |
110 | @c __sigsetjmp(!savemask) ok | |
111 | @c __sigjmp_save(!savemask) ok, does not call sigprocmask | |
28f540f4 RM |
112 | When called normally, @code{setjmp} stores information about the |
113 | execution state of the program in @var{state} and returns zero. If | |
114 | @code{longjmp} is later used to perform a non-local exit to this | |
115 | @var{state}, @code{setjmp} returns a nonzero value. | |
116 | @end deftypefn | |
117 | ||
f65fd747 | 118 | @deftypefun void longjmp (jmp_buf @var{state}, int @var{value}) |
d08a7e4c | 119 | @standards{ISO, setjmp.h} |
542210fb AO |
120 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @asucorrupt{} @asulock{/hurd}}@acunsafe{@acucorrupt{} @aculock{/hurd}}} |
121 | @c __libc_siglongjmp @ascuplugin @asucorrupt @asulock/hurd @acucorrupt @aculock/hurd | |
122 | @c _longjmp_unwind @ascuplugin @asucorrupt @acucorrupt | |
123 | @c __pthread_cleanup_upto @ascuplugin @asucorrupt @acucorrupt | |
124 | @c plugins may be unsafe themselves, but even if they weren't, this | |
125 | @c function isn't robust WRT async signals and cancellation: | |
126 | @c cleanups aren't taken off the stack right away, only after all | |
127 | @c cleanups have been run. This means that async-cancelling | |
128 | @c longjmp, or interrupting longjmp with an async signal handler | |
129 | @c that calls longjmp may run the same cleanups multiple times. | |
130 | @c _JMPBUF_UNWINDS_ADJ ok | |
131 | @c *cleanup_buf->__routine @ascuplugin | |
132 | @c sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd | |
133 | @c __longjmp ok | |
28f540f4 RM |
134 | This function restores current execution to the state saved in |
135 | @var{state}, and continues execution from the call to @code{setjmp} that | |
136 | established that return point. Returning from @code{setjmp} by means of | |
137 | @code{longjmp} returns the @var{value} argument that was passed to | |
138 | @code{longjmp}, rather than @code{0}. (But if @var{value} is given as | |
0005e54f | 139 | @code{0}, @code{setjmp} returns @code{1}). |
28f540f4 RM |
140 | @end deftypefun |
141 | ||
142 | There are a lot of obscure but important restrictions on the use of | |
143 | @code{setjmp} and @code{longjmp}. Most of these restrictions are | |
144 | present because non-local exits require a fair amount of magic on the | |
145 | part of the C compiler and can interact with other parts of the language | |
146 | in strange ways. | |
147 | ||
148 | The @code{setjmp} function is actually a macro without an actual | |
149 | function definition, so you shouldn't try to @samp{#undef} it or take | |
150 | its address. In addition, calls to @code{setjmp} are safe in only the | |
151 | following contexts: | |
152 | ||
153 | @itemize @bullet | |
154 | @item | |
155 | As the test expression of a selection or iteration | |
156 | statement (such as @samp{if}, @samp{switch}, or @samp{while}). | |
157 | ||
158 | @item | |
9dcc8f11 | 159 | As one operand of an equality or comparison operator that appears as the |
28f540f4 RM |
160 | test expression of a selection or iteration statement. The other |
161 | operand must be an integer constant expression. | |
162 | ||
163 | @item | |
164 | As the operand of a unary @samp{!} operator, that appears as the | |
165 | test expression of a selection or iteration statement. | |
166 | ||
167 | @item | |
168 | By itself as an expression statement. | |
169 | @end itemize | |
170 | ||
171 | Return points are valid only during the dynamic extent of the function | |
172 | that called @code{setjmp} to establish them. If you @code{longjmp} to | |
173 | a return point that was established in a function that has already | |
174 | returned, unpredictable and disastrous things are likely to happen. | |
175 | ||
176 | You should use a nonzero @var{value} argument to @code{longjmp}. While | |
177 | @code{longjmp} refuses to pass back a zero argument as the return value | |
178 | from @code{setjmp}, this is intended as a safety net against accidental | |
179 | misuse and is not really good programming style. | |
180 | ||
181 | When you perform a non-local exit, accessible objects generally retain | |
182 | whatever values they had at the time @code{longjmp} was called. The | |
183 | exception is that the values of automatic variables local to the | |
184 | function containing the @code{setjmp} call that have been changed since | |
185 | the call to @code{setjmp} are indeterminate, unless you have declared | |
186 | them @code{volatile}. | |
187 | ||
eacde9d0 | 188 | @node Non-Local Exits and Signals, System V contexts, Non-Local Details, Non-Local Exits |
28f540f4 RM |
189 | @section Non-Local Exits and Signals |
190 | ||
191 | In BSD Unix systems, @code{setjmp} and @code{longjmp} also save and | |
192 | restore the set of blocked signals; see @ref{Blocking Signals}. However, | |
193 | the POSIX.1 standard requires @code{setjmp} and @code{longjmp} not to | |
194 | change the set of blocked signals, and provides an additional pair of | |
d07e37e2 | 195 | functions (@code{sigsetjmp} and @code{siglongjmp}) to get the BSD |
28f540f4 RM |
196 | behavior. |
197 | ||
1f77f049 | 198 | The behavior of @code{setjmp} and @code{longjmp} in @theglibc{} is |
28f540f4 | 199 | controlled by feature test macros; see @ref{Feature Test Macros}. The |
a7a93d50 | 200 | default in @theglibc{} is the POSIX.1 behavior rather than the BSD |
28f540f4 RM |
201 | behavior. |
202 | ||
203 | The facilities in this section are declared in the header file | |
204 | @file{setjmp.h}. | |
205 | @pindex setjmp.h | |
206 | ||
28f540f4 | 207 | @deftp {Data Type} sigjmp_buf |
d08a7e4c | 208 | @standards{POSIX.1, setjmp.h} |
28f540f4 RM |
209 | This is similar to @code{jmp_buf}, except that it can also store state |
210 | information about the set of blocked signals. | |
211 | @end deftp | |
212 | ||
28f540f4 | 213 | @deftypefun int sigsetjmp (sigjmp_buf @var{state}, int @var{savesigs}) |
d08a7e4c | 214 | @standards{POSIX.1, setjmp.h} |
542210fb AO |
215 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}} |
216 | @c sigsetjmp @asulock/hurd @aculock/hurd | |
217 | @c __sigsetjmp(savemask) @asulock/hurd @aculock/hurd | |
218 | @c __sigjmp_save(savemask) @asulock/hurd @aculock/hurd | |
219 | @c sigprocmask(SIG_BLOCK probe) dup @asulock/hurd @aculock/hurd | |
28f540f4 RM |
220 | This is similar to @code{setjmp}. If @var{savesigs} is nonzero, the set |
221 | of blocked signals is saved in @var{state} and will be restored if a | |
222 | @code{siglongjmp} is later performed with this @var{state}. | |
223 | @end deftypefun | |
224 | ||
28f540f4 | 225 | @deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value}) |
d08a7e4c | 226 | @standards{POSIX.1, setjmp.h} |
542210fb AO |
227 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @asucorrupt{} @asulock{/hurd}}@acunsafe{@acucorrupt{} @aculock{/hurd}}} |
228 | @c Alias to longjmp. | |
28f540f4 RM |
229 | This is similar to @code{longjmp} except for the type of its @var{state} |
230 | argument. If the @code{sigsetjmp} call that set this @var{state} used a | |
231 | nonzero @var{savesigs} flag, @code{siglongjmp} also restores the set of | |
232 | blocked signals. | |
233 | @end deftypefun | |
eacde9d0 UD |
234 | |
235 | @node System V contexts,, Non-Local Exits and Signals, Non-Local Exits | |
236 | @section Complete Context Control | |
237 | ||
67f60a26 AJ |
238 | The Unix standard provides one more set of functions to control the |
239 | execution path and these functions are more powerful than those | |
a96ce75c | 240 | discussed in this chapter so far. These functions were part of the |
67f60a26 | 241 | original @w{System V} API and by this route were added to the Unix |
a96ce75c | 242 | API. Besides on branded Unix implementations these interfaces are not |
67f60a26 AJ |
243 | widely available. Not all platforms and/or architectures @theglibc{} |
244 | is available on provide this interface. Use @file{configure} to | |
245 | detect the availability. | |
eacde9d0 UD |
246 | |
247 | Similar to the @code{jmp_buf} and @code{sigjmp_buf} types used for the | |
248 | variables to contain the state of the @code{longjmp} functions the | |
249 | interfaces of interest here have an appropriate type as well. Objects | |
250 | of this type are normally much larger since more information is | |
251 | contained. The type is also used in a few more places as we will see. | |
252 | The types and functions described in this section are all defined and | |
253 | declared respectively in the @file{ucontext.h} header file. | |
254 | ||
eacde9d0 | 255 | @deftp {Data Type} ucontext_t |
d08a7e4c | 256 | @standards{SVID, ucontext.h} |
eacde9d0 | 257 | |
6349768c | 258 | The @code{ucontext_t} type is defined as a structure with at least the |
eacde9d0 UD |
259 | following elements: |
260 | ||
261 | @table @code | |
262 | @item ucontext_t *uc_link | |
263 | This is a pointer to the next context structure which is used if the | |
264 | context described in the current structure returns. | |
265 | ||
266 | @item sigset_t uc_sigmask | |
267 | Set of signals which are blocked when this context is used. | |
268 | ||
269 | @item stack_t uc_stack | |
270 | Stack used for this context. The value need not be (and normally is | |
271 | not) the stack pointer. @xref{Signal Stack}. | |
272 | ||
273 | @item mcontext_t uc_mcontext | |
274 | This element contains the actual state of the process. The | |
275 | @code{mcontext_t} type is also defined in this header but the definition | |
276 | should be treated as opaque. Any use of knowledge of the type makes | |
277 | applications less portable. | |
278 | ||
279 | @end table | |
280 | @end deftp | |
281 | ||
282 | Objects of this type have to be created by the user. The initialization | |
283 | and modification happens through one of the following functions: | |
284 | ||
eacde9d0 | 285 | @deftypefun int getcontext (ucontext_t *@var{ucp}) |
d08a7e4c | 286 | @standards{SVID, ucontext.h} |
542210fb AO |
287 | @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}} |
288 | @c Linux-only implementations in assembly, including sigprocmask | |
289 | @c syscall. A few cases call the sigprocmask function, but that's safe | |
290 | @c too. The ppc case is implemented in terms of a swapcontext syscall. | |
eacde9d0 UD |
291 | The @code{getcontext} function initializes the variable pointed to by |
292 | @var{ucp} with the context of the calling thread. The context contains | |
293 | the content of the registers, the signal mask, and the current stack. | |
294 | Executing the contents would start at the point where the | |
295 | @code{getcontext} call just returned. | |
296 | ||
9995c839 AZ |
297 | @strong{Compatibility Note:} Depending on the operating system, |
298 | information about the current context's stack may be in the | |
299 | @code{uc_stack} field of @var{ucp}, or it may instead be in | |
300 | architecture-specific subfields of the @code{uc_mcontext} field. | |
301 | ||
0bc93a2f | 302 | The function returns @code{0} if successful. Otherwise it returns |
010fe231 | 303 | @code{-1} and sets @code{errno} accordingly. |
eacde9d0 UD |
304 | @end deftypefun |
305 | ||
306 | The @code{getcontext} function is similar to @code{setjmp} but it does | |
6f918f36 WN |
307 | not provide an indication of whether @code{getcontext} is returning for |
308 | the first time or whether an initialized context has just been restored. | |
309 | If this is necessary the user has to determine this herself. This must | |
310 | be done carefully since the context contains registers which might contain | |
311 | register variables. This is a good situation to define variables with | |
312 | @code{volatile}. | |
eacde9d0 UD |
313 | |
314 | Once the context variable is initialized it can be used as is or it can | |
6f918f36 WN |
315 | be modified using the @code{makecontext} function. The latter is normally |
316 | done when implementing co-routines or similar constructs. | |
eacde9d0 | 317 | |
eacde9d0 | 318 | @deftypefun void makecontext (ucontext_t *@var{ucp}, void (*@var{func}) (void), int @var{argc}, @dots{}) |
d08a7e4c | 319 | @standards{SVID, ucontext.h} |
542210fb AO |
320 | @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}} |
321 | @c Linux-only implementations mostly in assembly, nothing unsafe. | |
eacde9d0 | 322 | |
6f918f36 | 323 | The @var{ucp} parameter passed to @code{makecontext} shall be |
eacde9d0 | 324 | initialized by a call to @code{getcontext}. The context will be |
6349768c | 325 | modified in a way such that if the context is resumed it will start by |
eacde9d0 UD |
326 | calling the function @code{func} which gets @var{argc} integer arguments |
327 | passed. The integer arguments which are to be passed should follow the | |
328 | @var{argc} parameter in the call to @code{makecontext}. | |
329 | ||
330 | Before the call to this function the @code{uc_stack} and @code{uc_link} | |
331 | element of the @var{ucp} structure should be initialized. The | |
332 | @code{uc_stack} element describes the stack which is used for this | |
333 | context. No two contexts which are used at the same time should use the | |
334 | same memory region for a stack. | |
335 | ||
336 | The @code{uc_link} element of the object pointed to by @var{ucp} should | |
337 | be a pointer to the context to be executed when the function @var{func} | |
338 | returns or it should be a null pointer. See @code{setcontext} for more | |
339 | information about the exact use. | |
340 | @end deftypefun | |
341 | ||
342 | While allocating the memory for the stack one has to be careful. Most | |
343 | modern processors keep track of whether a certain memory region is | |
344 | allowed to contain code which is executed or not. Data segments and | |
6349768c | 345 | heap memory are normally not tagged to allow this. The result is that |
eacde9d0 UD |
346 | programs would fail. Examples for such code include the calling |
347 | sequences the GNU C compiler generates for calls to nested functions. | |
348 | Safe ways to allocate stacks correctly include using memory on the | |
a96ce75c | 349 | original thread's stack or explicitly allocating memory tagged for |
eacde9d0 UD |
350 | execution using (@pxref{Memory-mapped I/O}). |
351 | ||
352 | @strong{Compatibility note}: The current Unix standard is very imprecise | |
353 | about the way the stack is allocated. All implementations seem to agree | |
354 | that the @code{uc_stack} element must be used but the values stored in | |
1f77f049 | 355 | the elements of the @code{stack_t} value are unclear. @Theglibc{} |
eacde9d0 UD |
356 | and most other Unix implementations require the @code{ss_sp} value of |
357 | the @code{uc_stack} element to point to the base of the memory region | |
358 | allocated for the stack and the size of the memory region is stored in | |
a96ce75c | 359 | @code{ss_size}. There are implementations out there which require |
eacde9d0 | 360 | @code{ss_sp} to be set to the value the stack pointer will have (which |
6349768c | 361 | can, depending on the direction the stack grows, be different). This |
eacde9d0 UD |
362 | difference makes the @code{makecontext} function hard to use and it |
363 | requires detection of the platform at compile time. | |
364 | ||
eacde9d0 | 365 | @deftypefun int setcontext (const ucontext_t *@var{ucp}) |
d08a7e4c | 366 | @standards{SVID, ucontext.h} |
542210fb AO |
367 | @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} |
368 | @c Linux-only implementations mostly in assembly. Some ports use | |
369 | @c sigreturn or swapcontext syscalls; others restore the signal mask | |
370 | @c first and then proceed restore other registers in userland, which | |
371 | @c leaves a window for cancellation or async signals with misaligned or | |
372 | @c otherwise corrupt stack. ??? Switching to a different stack, or even | |
373 | @c to an earlier state on the same stack, may conflict with pthread | |
374 | @c cleanups. This is not quite MT-Unsafe, it's a different kind of | |
375 | @c safety issue. | |
eacde9d0 UD |
376 | |
377 | The @code{setcontext} function restores the context described by | |
378 | @var{ucp}. The context is not modified and can be reused as often as | |
379 | wanted. | |
380 | ||
381 | If the context was created by @code{getcontext} execution resumes with | |
382 | the registers filled with the same values and the same stack as if the | |
383 | @code{getcontext} call just returned. | |
384 | ||
385 | If the context was modified with a call to @code{makecontext} execution | |
386 | continues with the function passed to @code{makecontext} which gets the | |
387 | specified parameters passed. If this function returns execution is | |
388 | resumed in the context which was referenced by the @code{uc_link} | |
389 | element of the context structure passed to @code{makecontext} at the | |
390 | time of the call. If @code{uc_link} was a null pointer the application | |
dc97c227 TS |
391 | terminates normally with an exit status value of @code{EXIT_SUCCESS} |
392 | (@pxref{Program Termination}). | |
eacde9d0 | 393 | |
7c677662 WN |
394 | If the context was created by a call to a signal handler or from any |
395 | other source then the behaviour of @code{setcontext} is unspecified. | |
396 | ||
eacde9d0 UD |
397 | Since the context contains information about the stack no two threads |
398 | should use the same context at the same time. The result in most cases | |
399 | would be disastrous. | |
400 | ||
401 | The @code{setcontext} function does not return unless an error occurred | |
402 | in which case it returns @code{-1}. | |
403 | @end deftypefun | |
404 | ||
405 | The @code{setcontext} function simply replaces the current context with | |
406 | the one described by the @var{ucp} parameter. This is often useful but | |
407 | there are situations where the current context has to be preserved. | |
408 | ||
eacde9d0 | 409 | @deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp}) |
d08a7e4c | 410 | @standards{SVID, ucontext.h} |
542210fb AO |
411 | @safety{@prelim{}@mtsafe{@mtsrace{:oucp} @mtsrace{:ucp}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} |
412 | @c Linux-only implementations mostly in assembly. Some ports call or | |
413 | @c inline getcontext and/or setcontext, adjusting the saved context in | |
414 | @c between, so we inherit the potential issues of both. | |
eacde9d0 UD |
415 | |
416 | The @code{swapcontext} function is similar to @code{setcontext} but | |
417 | instead of just replacing the current context the latter is first saved | |
418 | in the object pointed to by @var{oucp} as if this was a call to | |
419 | @code{getcontext}. The saved context would resume after the call to | |
420 | @code{swapcontext}. | |
421 | ||
422 | Once the current context is saved the context described in @var{ucp} is | |
423 | installed and execution continues as described in this context. | |
424 | ||
425 | If @code{swapcontext} succeeds the function does not return unless the | |
426 | context @var{oucp} is used without prior modification by | |
427 | @code{makecontext}. The return value in this case is @code{0}. If the | |
010fe231 | 428 | function fails it returns @code{-1} and sets @code{errno} accordingly. |
eacde9d0 UD |
429 | @end deftypefun |
430 | ||
431 | @heading Example for SVID Context Handling | |
432 | ||
433 | The easiest way to use the context handling functions is as a | |
434 | replacement for @code{setjmp} and @code{longjmp}. The context contains | |
6f918f36 | 435 | on most platforms more information which may lead to fewer surprises |
6349768c | 436 | but this also means using these functions is more expensive (besides |
eacde9d0 UD |
437 | being less portable). |
438 | ||
439 | @smallexample | |
440 | int | |
441 | random_search (int n, int (*fp) (int, ucontext_t *)) | |
442 | @{ | |
443 | volatile int cnt = 0; | |
444 | ucontext_t uc; | |
445 | ||
446 | /* @r{Safe current context.} */ | |
447 | if (getcontext (&uc) < 0) | |
448 | return -1; | |
449 | ||
450 | /* @r{If we have not tried @var{n} times try again.} */ | |
451 | if (cnt++ < n) | |
452 | /* @r{Call the function with a new random number} | |
453 | @r{and the context}. */ | |
454 | if (fp (rand (), &uc) != 0) | |
455 | /* @r{We found what we were looking for.} */ | |
456 | return 1; | |
457 | ||
458 | /* @r{Not found.} */ | |
459 | return 0; | |
460 | @} | |
461 | @end smallexample | |
462 | ||
463 | Using contexts in such a way enables emulating exception handling. The | |
464 | search functions passed in the @var{fp} parameter could be very large, | |
465 | nested, and complex which would make it complicated (or at least would | |
466 | require a lot of code) to leave the function with an error value which | |
467 | has to be passed down to the caller. By using the context it is | |
468 | possible to leave the search function in one step and allow restarting | |
469 | the search which also has the nice side effect that it can be | |
470 | significantly faster. | |
471 | ||
472 | Something which is harder to implement with @code{setjmp} and | |
473 | @code{longjmp} is to switch temporarily to a different execution path | |
474 | and then resume where execution was stopped. | |
475 | ||
476 | @smallexample | |
477 | @include swapcontext.c.texi | |
478 | @end smallexample | |
479 | ||
480 | This an example how the context functions can be used to implement | |
481 | co-routines or cooperative multi-threading. All that has to be done is | |
482 | to call every once in a while @code{swapcontext} to continue running a | |
7c677662 WN |
483 | different context. It is not recommended to do the context switching from |
484 | the signal handler directly since leaving the signal handler via | |
485 | @code{setcontext} if the signal was delivered during code that was not | |
486 | asynchronous signal safe could lead to problems. Setting a variable in | |
487 | the signal handler and checking it in the body of the functions which | |
488 | are executed is a safer approach. Since @code{swapcontext} is saving the | |
489 | current context it is possible to have multiple different scheduling points | |
490 | in the code. Execution will always resume where it was left. |