Fix typos.
[kopensolaris-gnu/glibc.git] / manual / setjmp.texi
1 @node Non-Local Exits, Signal Handling, Resource Usage And Limitation, Top
2 @c %MENU% Jumping out of nested function calls
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.
15 * Details: Non-Local Details.    Functions for non-local exits.
16 * Non-Local Exits and Signals::  Portability issues.
17 * System V contexts::            Complete context control a la System V.
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
48 You identify return points for non-local exits by calling the function
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
52 the call to @code{setjmp}, but if an exit is later made to this return
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
60 Here is how the example program described above might be set up:
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
99 @comment setjmp.h
100 @comment ISO
101 @deftp {Data Type} jmp_buf
102 Objects of type @code{jmp_buf} hold the state information to
103 be restored by a non-local exit.  The contents of a @code{jmp_buf}
104 identify a specific place to return to.
105 @end deftp
106
107 @comment setjmp.h
108 @comment ISO
109 @deftypefn Macro int setjmp (jmp_buf @var{state})
110 When called normally, @code{setjmp} stores information about the
111 execution state of the program in @var{state} and returns zero.  If
112 @code{longjmp} is later used to perform a non-local exit to this
113 @var{state}, @code{setjmp} returns a nonzero value.
114 @end deftypefn
115
116 @comment setjmp.h
117 @comment ISO
118 @deftypefun void longjmp (jmp_buf @var{state}, int @var{value})
119 This function restores current execution to the state saved in
120 @var{state}, and continues execution from the call to @code{setjmp} that
121 established that return point.  Returning from @code{setjmp} by means of
122 @code{longjmp} returns the @var{value} argument that was passed to
123 @code{longjmp}, rather than @code{0}.  (But if @var{value} is given as
124 @code{0}, @code{setjmp} returns @code{1}).@refill
125 @end deftypefun
126
127 There are a lot of obscure but important restrictions on the use of
128 @code{setjmp} and @code{longjmp}.  Most of these restrictions are
129 present because non-local exits require a fair amount of magic on the
130 part of the C compiler and can interact with other parts of the language
131 in strange ways.
132
133 The @code{setjmp} function is actually a macro without an actual
134 function definition, so you shouldn't try to @samp{#undef} it or take
135 its address.  In addition, calls to @code{setjmp} are safe in only the
136 following contexts:
137
138 @itemize @bullet
139 @item
140 As the test expression of a selection or iteration
141 statement (such as @samp{if}, @samp{switch}, or @samp{while}).
142
143 @item
144 As one operand of a equality or comparison operator that appears as the
145 test expression of a selection or iteration statement.  The other
146 operand must be an integer constant expression.
147
148 @item
149 As the operand of a unary @samp{!} operator, that appears as the
150 test expression of a selection or iteration statement.
151
152 @item
153 By itself as an expression statement.
154 @end itemize
155
156 Return points are valid only during the dynamic extent of the function
157 that called @code{setjmp} to establish them.  If you @code{longjmp} to
158 a return point that was established in a function that has already
159 returned, unpredictable and disastrous things are likely to happen.
160
161 You should use a nonzero @var{value} argument to @code{longjmp}.  While
162 @code{longjmp} refuses to pass back a zero argument as the return value
163 from @code{setjmp}, this is intended as a safety net against accidental
164 misuse and is not really good programming style.
165
166 When you perform a non-local exit, accessible objects generally retain
167 whatever values they had at the time @code{longjmp} was called.  The
168 exception is that the values of automatic variables local to the
169 function containing the @code{setjmp} call that have been changed since
170 the call to @code{setjmp} are indeterminate, unless you have declared
171 them @code{volatile}.
172
173 @node Non-Local Exits and Signals, System V contexts, Non-Local Details, Non-Local Exits
174 @section Non-Local Exits and Signals
175
176 In BSD Unix systems, @code{setjmp} and @code{longjmp} also save and
177 restore the set of blocked signals; see @ref{Blocking Signals}.  However,
178 the POSIX.1 standard requires @code{setjmp} and @code{longjmp} not to
179 change the set of blocked signals, and provides an additional pair of
180 functions (@code{sigsetjmp} and @code{siglongjmp}) to get the BSD
181 behavior.
182
183 The behavior of @code{setjmp} and @code{longjmp} in the GNU library is
184 controlled by feature test macros; see @ref{Feature Test Macros}.  The
185 default in the GNU system is the POSIX.1 behavior rather than the BSD
186 behavior.
187
188 The facilities in this section are declared in the header file
189 @file{setjmp.h}.
190 @pindex setjmp.h
191
192 @comment setjmp.h
193 @comment POSIX.1
194 @deftp {Data Type} sigjmp_buf
195 This is similar to @code{jmp_buf}, except that it can also store state
196 information about the set of blocked signals.
197 @end deftp
198
199 @comment setjmp.h
200 @comment POSIX.1
201 @deftypefun int sigsetjmp (sigjmp_buf @var{state}, int @var{savesigs})
202 This is similar to @code{setjmp}.  If @var{savesigs} is nonzero, the set
203 of blocked signals is saved in @var{state} and will be restored if a
204 @code{siglongjmp} is later performed with this @var{state}.
205 @end deftypefun
206
207 @comment setjmp.h
208 @comment POSIX.1
209 @deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value})
210 This is similar to @code{longjmp} except for the type of its @var{state}
211 argument.  If the @code{sigsetjmp} call that set this @var{state} used a
212 nonzero @var{savesigs} flag, @code{siglongjmp} also restores the set of
213 blocked signals.
214 @end deftypefun
215
216 @node System V contexts,, Non-Local Exits and Signals, Non-Local Exits
217 @section Complete Context Control
218
219 The Unix standard one more set of function to control the execution path
220 and these functions are more powerful than those discussed in this
221 chapter so far.  These function were part of the original @w{System V}
222 API and by this route were added to the Unix API.  Beside on branded
223 Unix implementations these interfaces are not widely available.  Not all
224 platforms and/or architectures the GNU C Library is available on provide
225 this interface.  Use @file{configure} to detect the availability.
226
227 Similar to the @code{jmp_buf} and @code{sigjmp_buf} types used for the
228 variables to contain the state of the @code{longjmp} functions the
229 interfaces of interest here have an appropriate type as well.  Objects
230 of this type are normally much larger since more information is
231 contained.  The type is also used in a few more places as we will see.
232 The types and functions described in this section are all defined and
233 declared respectively in the @file{ucontext.h} header file.
234
235 @comment ucontext.h
236 @comment SVID
237 @deftp {Data Type} ucontext_t
238
239 The @code{ucontext_t} type is defined as a structure with as least the
240 following elements:
241
242 @table @code
243 @item ucontext_t *uc_link
244 This is a pointer to the next context structure which is used if the
245 context described in the current structure returns.
246
247 @item sigset_t uc_sigmask
248 Set of signals which are blocked when this context is used.
249
250 @item stack_t uc_stack
251 Stack used for this context.  The value need not be (and normally is
252 not) the stack pointer.  @xref{Signal Stack}.
253
254 @item mcontext_t uc_mcontext
255 This element contains the actual state of the process.  The
256 @code{mcontext_t} type is also defined in this header but the definition
257 should be treated as opaque.  Any use of knowledge of the type makes
258 applications less portable.
259
260 @end table
261 @end deftp
262
263 Objects of this type have to be created by the user.  The initialization
264 and modification happens through one of the following functions:
265
266 @comment ucontext.h
267 @comment SVID
268 @deftypefun int getcontext (ucontext_t *@var{ucp})
269 The @code{getcontext} function initializes the variable pointed to by
270 @var{ucp} with the context of the calling thread.  The context contains
271 the content of the registers, the signal mask, and the current stack.
272 Executing the contents would start at the point where the
273 @code{getcontext} call just returned.
274
275 The function returns @code{0} if successful.  Otherwise it returns
276 @code{-1} and sets @var{errno} accordingly.
277 @end deftypefun
278
279 The @code{getcontext} function is similar to @code{setjmp} but it does
280 not provide an indication of whether the function returns for the first
281 time or whether the initialized context was used and the execution is
282 resumed at just that point.  If this is necessary the user has to take
283 determine this herself.  This must be done carefully since the context
284 contains registers which might contain register variables.  This is a
285 good situation to define variables with @code{volatile}.
286
287 Once the context variable is initialized it can be used as is or it can
288 be modified.  The latter is normally done to implement co-routines or
289 similar constructs.  The @code{makecontext} function is what has to be
290 used to do that.
291
292 @comment ucontext.h
293 @comment SVID
294 @deftypefun void makecontext (ucontext_t *@var{ucp}, void (*@var{func}) (void), int @var{argc}, @dots{})
295
296 The @var{ucp} parameter passed to the @code{makecontext} shall be
297 initialized by a call to @code{getcontext}.  The context will be
298 modified to in a way so that if the context is resumed it will start by
299 calling the function @code{func} which gets @var{argc} integer arguments
300 passed.  The integer arguments which are to be passed should follow the
301 @var{argc} parameter in the call to @code{makecontext}.
302
303 Before the call to this function the @code{uc_stack} and @code{uc_link}
304 element of the @var{ucp} structure should be initialized.  The
305 @code{uc_stack} element describes the stack which is used for this
306 context.  No two contexts which are used at the same time should use the
307 same memory region for a stack.
308
309 The @code{uc_link} element of the object pointed to by @var{ucp} should
310 be a pointer to the context to be executed when the function @var{func}
311 returns or it should be a null pointer.  See @code{setcontext} for more
312 information about the exact use.
313 @end deftypefun
314
315 While allocating the memory for the stack one has to be careful.  Most
316 modern processors keep track of whether a certain memory region is
317 allowed to contain code which is executed or not.  Data segments and
318 heap memory is normally not tagged to allow this.  The result is that
319 programs would fail.  Examples for such code include the calling
320 sequences the GNU C compiler generates for calls to nested functions.
321 Safe ways to allocate stacks correctly include using memory on the
322 original threads stack or explicitly allocate memory tagged for
323 execution using (@pxref{Memory-mapped I/O}).
324
325 @strong{Compatibility note}: The current Unix standard is very imprecise
326 about the way the stack is allocated.  All implementations seem to agree
327 that the @code{uc_stack} element must be used but the values stored in
328 the elements of the @code{stack_t} value are unclear.  The GNU C library
329 and most other Unix implementations require the @code{ss_sp} value of
330 the @code{uc_stack} element to point to the base of the memory region
331 allocated for the stack and the size of the memory region is stored in
332 @code{ss_size}.  There are implements out there which require
333 @code{ss_sp} to be set to the value the stack pointer will have (which
334 can depending on the direction the stack grows be different).  This
335 difference makes the @code{makecontext} function hard to use and it
336 requires detection of the platform at compile time.
337
338 @comment ucontext.h
339 @comment SVID
340 @deftypefun int setcontext (const ucontext_t *@var{ucp})
341
342 The @code{setcontext} function restores the context described by
343 @var{ucp}.  The context is not modified and can be reused as often as
344 wanted.
345
346 If the context was created by @code{getcontext} execution resumes with
347 the registers filled with the same values and the same stack as if the
348 @code{getcontext} call just returned.
349
350 If the context was modified with a call to @code{makecontext} execution
351 continues with the function passed to @code{makecontext} which gets the
352 specified parameters passed.  If this function returns execution is
353 resumed in the context which was referenced by the @code{uc_link}
354 element of the context structure passed to @code{makecontext} at the
355 time of the call.  If @code{uc_link} was a null pointer the application
356 terminates in this case.
357
358 Since the context contains information about the stack no two threads
359 should use the same context at the same time.  The result in most cases
360 would be disastrous.
361
362 The @code{setcontext} function does not return unless an error occurred
363 in which case it returns @code{-1}.
364 @end deftypefun
365
366 The @code{setcontext} function simply replaces the current context with
367 the one described by the @var{ucp} parameter.  This is often useful but
368 there are situations where the current context has to be preserved.
369
370 @comment ucontext.h
371 @comment SVID
372 @deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp})
373
374 The @code{swapcontext} function is similar to @code{setcontext} but
375 instead of just replacing the current context the latter is first saved
376 in the object pointed to by @var{oucp} as if this was a call to
377 @code{getcontext}.  The saved context would resume after the call to
378 @code{swapcontext}.
379
380 Once the current context is saved the context described in @var{ucp} is
381 installed and execution continues as described in this context.
382
383 If @code{swapcontext} succeeds the function does not return unless the
384 context @var{oucp} is used without prior modification by
385 @code{makecontext}.  The return value in this case is @code{0}.  If the
386 function fails it returns @code{-1} and set @var{errno} accordingly.
387 @end deftypefun
388
389 @heading Example for SVID Context Handling
390
391 The easiest way to use the context handling functions is as a
392 replacement for @code{setjmp} and @code{longjmp}.  The context contains
393 on most platforms more information which might lead to less surprises
394 but this also means using these functions is more expensive (beside
395 being less portable).
396
397 @smallexample
398 int
399 random_search (int n, int (*fp) (int, ucontext_t *))
400 @{
401   volatile int cnt = 0;
402   ucontext_t uc;
403
404   /* @r{Safe current context.}  */
405   if (getcontext (&uc) < 0)
406     return -1;
407
408   /* @r{If we have not tried @var{n} times try again.}  */
409   if (cnt++ < n)
410     /* @r{Call the function with a new random number}
411        @r{and the context}.  */
412     if (fp (rand (), &uc) != 0)
413       /* @r{We found what we were looking for.}  */
414       return 1;
415
416   /* @r{Not found.}  */
417   return 0;
418 @}
419 @end smallexample
420
421 Using contexts in such a way enables emulating exception handling.  The
422 search functions passed in the @var{fp} parameter could be very large,
423 nested, and complex which would make it complicated (or at least would
424 require a lot of code) to leave the function with an error value which
425 has to be passed down to the caller.  By using the context it is
426 possible to leave the search function in one step and allow restarting
427 the search which also has the nice side effect that it can be
428 significantly faster.
429
430 Something which is harder to implement with @code{setjmp} and
431 @code{longjmp} is to switch temporarily to a different execution path
432 and then resume where execution was stopped.
433
434 @smallexample
435 @include swapcontext.c.texi
436 @end smallexample
437
438 This an example how the context functions can be used to implement
439 co-routines or cooperative multi-threading.  All that has to be done is
440 to call every once in a while @code{swapcontext} to continue running a
441 different context.  It is not allowed to do the context switching from
442 the signal handler directly since neither @code{setcontext} nor
443 @code{swapcontext} are functions which can be called from a signal
444 handler.  But setting a variable in the signal handler and checking it
445 in the body of the functions which are executed.  Since
446 @code{swapcontext} is saving the current context it is possible to have
447 multiple different scheduling points in the code.  Execution will always
448 resume where it was left.