Add --enable-hardcoded-path-in-tests configure option
[glibc.git] / manual / setjmp.texi
blobf13ac7b00e0a1cfe092d3eb0afd0b696fa9a8fc8
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
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.
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
20 @node Non-Local Intro, Non-Local Details,  , Non-Local Exits
21 @section Introduction to Non-Local Exits
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.
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''.)
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.
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.
60 Here is how the example program described above might be set up:
62 @smallexample
63 @include setjmp.c.texi
64 @end smallexample
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.
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}.
79 @need 250
80 So, the general pattern for using @code{setjmp} looks something like:
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
91 @node Non-Local Details, Non-Local Exits and Signals, Non-Local Intro, Non-Local Exits
92 @section Details of Non-Local Exits
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
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
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
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
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.
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:
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}).
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.
148 @item
149 As the operand of a unary @samp{!} operator, that appears as the
150 test expression of a selection or iteration statement.
152 @item
153 By itself as an expression statement.
154 @end itemize
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.
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.
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}.
173 @node Non-Local Exits and Signals, System V contexts, Non-Local Details, Non-Local Exits
174 @section Non-Local Exits and Signals
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.
183 The behavior of @code{setjmp} and @code{longjmp} in @theglibc{} is
184 controlled by feature test macros; see @ref{Feature Test Macros}.  The
185 default in @theglibc{} is the POSIX.1 behavior rather than the BSD
186 behavior.
188 The facilities in this section are declared in the header file
189 @file{setjmp.h}.
190 @pindex setjmp.h
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
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
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
216 @node System V contexts,, Non-Local Exits and Signals, Non-Local Exits
217 @section Complete Context Control
219 The Unix standard provides one more set of functions to control the
220 execution path and these functions are more powerful than those
221 discussed in this chapter so far.  These function were part of the
222 original @w{System V} API and by this route were added to the Unix
223 API.  Beside on branded Unix implementations these interfaces are not
224 widely available.  Not all platforms and/or architectures @theglibc{}
225 is available on provide this interface.  Use @file{configure} to
226 detect the availability.
228 Similar to the @code{jmp_buf} and @code{sigjmp_buf} types used for the
229 variables to contain the state of the @code{longjmp} functions the
230 interfaces of interest here have an appropriate type as well.  Objects
231 of this type are normally much larger since more information is
232 contained.  The type is also used in a few more places as we will see.
233 The types and functions described in this section are all defined and
234 declared respectively in the @file{ucontext.h} header file.
236 @comment ucontext.h
237 @comment SVID
238 @deftp {Data Type} ucontext_t
240 The @code{ucontext_t} type is defined as a structure with as least the
241 following elements:
243 @table @code
244 @item ucontext_t *uc_link
245 This is a pointer to the next context structure which is used if the
246 context described in the current structure returns.
248 @item sigset_t uc_sigmask
249 Set of signals which are blocked when this context is used.
251 @item stack_t uc_stack
252 Stack used for this context.  The value need not be (and normally is
253 not) the stack pointer.  @xref{Signal Stack}.
255 @item mcontext_t uc_mcontext
256 This element contains the actual state of the process.  The
257 @code{mcontext_t} type is also defined in this header but the definition
258 should be treated as opaque.  Any use of knowledge of the type makes
259 applications less portable.
261 @end table
262 @end deftp
264 Objects of this type have to be created by the user.  The initialization
265 and modification happens through one of the following functions:
267 @comment ucontext.h
268 @comment SVID
269 @deftypefun int getcontext (ucontext_t *@var{ucp})
270 The @code{getcontext} function initializes the variable pointed to by
271 @var{ucp} with the context of the calling thread.  The context contains
272 the content of the registers, the signal mask, and the current stack.
273 Executing the contents would start at the point where the
274 @code{getcontext} call just returned.
276 The function returns @code{0} if successful.  Otherwise it returns
277 @code{-1} and sets @var{errno} accordingly.
278 @end deftypefun
280 The @code{getcontext} function is similar to @code{setjmp} but it does
281 not provide an indication of whether the function returns for the first
282 time or whether the initialized context was used and the execution is
283 resumed at just that point.  If this is necessary the user has to take
284 determine this herself.  This must be done carefully since the context
285 contains registers which might contain register variables.  This is a
286 good situation to define variables with @code{volatile}.
288 Once the context variable is initialized it can be used as is or it can
289 be modified.  The latter is normally done to implement co-routines or
290 similar constructs.  The @code{makecontext} function is what has to be
291 used to do that.
293 @comment ucontext.h
294 @comment SVID
295 @deftypefun void makecontext (ucontext_t *@var{ucp}, void (*@var{func}) (void), int @var{argc}, @dots{})
297 The @var{ucp} parameter passed to the @code{makecontext} shall be
298 initialized by a call to @code{getcontext}.  The context will be
299 modified to in a way so that if the context is resumed it will start by
300 calling the function @code{func} which gets @var{argc} integer arguments
301 passed.  The integer arguments which are to be passed should follow the
302 @var{argc} parameter in the call to @code{makecontext}.
304 Before the call to this function the @code{uc_stack} and @code{uc_link}
305 element of the @var{ucp} structure should be initialized.  The
306 @code{uc_stack} element describes the stack which is used for this
307 context.  No two contexts which are used at the same time should use the
308 same memory region for a stack.
310 The @code{uc_link} element of the object pointed to by @var{ucp} should
311 be a pointer to the context to be executed when the function @var{func}
312 returns or it should be a null pointer.  See @code{setcontext} for more
313 information about the exact use.
314 @end deftypefun
316 While allocating the memory for the stack one has to be careful.  Most
317 modern processors keep track of whether a certain memory region is
318 allowed to contain code which is executed or not.  Data segments and
319 heap memory is normally not tagged to allow this.  The result is that
320 programs would fail.  Examples for such code include the calling
321 sequences the GNU C compiler generates for calls to nested functions.
322 Safe ways to allocate stacks correctly include using memory on the
323 original threads stack or explicitly allocate memory tagged for
324 execution using (@pxref{Memory-mapped I/O}).
326 @strong{Compatibility note}: The current Unix standard is very imprecise
327 about the way the stack is allocated.  All implementations seem to agree
328 that the @code{uc_stack} element must be used but the values stored in
329 the elements of the @code{stack_t} value are unclear.  @Theglibc{}
330 and most other Unix implementations require the @code{ss_sp} value of
331 the @code{uc_stack} element to point to the base of the memory region
332 allocated for the stack and the size of the memory region is stored in
333 @code{ss_size}.  There are implements out there which require
334 @code{ss_sp} to be set to the value the stack pointer will have (which
335 can depending on the direction the stack grows be different).  This
336 difference makes the @code{makecontext} function hard to use and it
337 requires detection of the platform at compile time.
339 @comment ucontext.h
340 @comment SVID
341 @deftypefun int setcontext (const ucontext_t *@var{ucp})
343 The @code{setcontext} function restores the context described by
344 @var{ucp}.  The context is not modified and can be reused as often as
345 wanted.
347 If the context was created by @code{getcontext} execution resumes with
348 the registers filled with the same values and the same stack as if the
349 @code{getcontext} call just returned.
351 If the context was modified with a call to @code{makecontext} execution
352 continues with the function passed to @code{makecontext} which gets the
353 specified parameters passed.  If this function returns execution is
354 resumed in the context which was referenced by the @code{uc_link}
355 element of the context structure passed to @code{makecontext} at the
356 time of the call.  If @code{uc_link} was a null pointer the application
357 terminates normally with an exit status value of @code{EXIT_SUCCESS}
358 (@pxref{Program Termination}).
360 Since the context contains information about the stack no two threads
361 should use the same context at the same time.  The result in most cases
362 would be disastrous.
364 The @code{setcontext} function does not return unless an error occurred
365 in which case it returns @code{-1}.
366 @end deftypefun
368 The @code{setcontext} function simply replaces the current context with
369 the one described by the @var{ucp} parameter.  This is often useful but
370 there are situations where the current context has to be preserved.
372 @comment ucontext.h
373 @comment SVID
374 @deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp})
376 The @code{swapcontext} function is similar to @code{setcontext} but
377 instead of just replacing the current context the latter is first saved
378 in the object pointed to by @var{oucp} as if this was a call to
379 @code{getcontext}.  The saved context would resume after the call to
380 @code{swapcontext}.
382 Once the current context is saved the context described in @var{ucp} is
383 installed and execution continues as described in this context.
385 If @code{swapcontext} succeeds the function does not return unless the
386 context @var{oucp} is used without prior modification by
387 @code{makecontext}.  The return value in this case is @code{0}.  If the
388 function fails it returns @code{-1} and set @var{errno} accordingly.
389 @end deftypefun
391 @heading Example for SVID Context Handling
393 The easiest way to use the context handling functions is as a
394 replacement for @code{setjmp} and @code{longjmp}.  The context contains
395 on most platforms more information which might lead to less surprises
396 but this also means using these functions is more expensive (beside
397 being less portable).
399 @smallexample
401 random_search (int n, int (*fp) (int, ucontext_t *))
403   volatile int cnt = 0;
404   ucontext_t uc;
406   /* @r{Safe current context.}  */
407   if (getcontext (&uc) < 0)
408     return -1;
410   /* @r{If we have not tried @var{n} times try again.}  */
411   if (cnt++ < n)
412     /* @r{Call the function with a new random number}
413        @r{and the context}.  */
414     if (fp (rand (), &uc) != 0)
415       /* @r{We found what we were looking for.}  */
416       return 1;
418   /* @r{Not found.}  */
419   return 0;
421 @end smallexample
423 Using contexts in such a way enables emulating exception handling.  The
424 search functions passed in the @var{fp} parameter could be very large,
425 nested, and complex which would make it complicated (or at least would
426 require a lot of code) to leave the function with an error value which
427 has to be passed down to the caller.  By using the context it is
428 possible to leave the search function in one step and allow restarting
429 the search which also has the nice side effect that it can be
430 significantly faster.
432 Something which is harder to implement with @code{setjmp} and
433 @code{longjmp} is to switch temporarily to a different execution path
434 and then resume where execution was stopped.
436 @smallexample
437 @include swapcontext.c.texi
438 @end smallexample
440 This an example how the context functions can be used to implement
441 co-routines or cooperative multi-threading.  All that has to be done is
442 to call every once in a while @code{swapcontext} to continue running a
443 different context.  It is not allowed to do the context switching from
444 the signal handler directly since neither @code{setcontext} nor
445 @code{swapcontext} are functions which can be called from a signal
446 handler.  But setting a variable in the signal handler and checking it
447 in the body of the functions which are executed.  Since
448 @code{swapcontext} is saving the current context it is possible to have
449 multiple different scheduling points in the code.  Execution will always
450 resume where it was left.