Initial revision
[kopensolaris-gnu/glibc.git] / manual / setjmp.texi
1 @node Non-Local Jumps
2 @chapter Non-Local Jumps
3 @pindex <setjmp.h>
4 @cindex non-local jumps
5
6 Sometimes when your program detects an unusual situation inside a deeply
7 nested set of function calls, you would like to be able to immediately
8 return to an outer level of control instead of having to return a
9 special exit code that each level of function call must check for.  This
10 section describes how you can do such @dfn{non-local jumps}.
11
12 @menu
13 * Introduction to Non-Local Jumps::     An overview of how and when to use
14                                          these facilities.
15 * Functions for Non-Local Jumps::       Details of the interface.
16 @end menu
17
18 @node Introduction to Non-Local Jumps
19 @section Introduction to Non-Local Jumps
20
21 As an example of a situation where a non-local jump can be useful,
22 suppose you have an interactive program that has a ``main loop'' that
23 prompts for and executes commands.  One of the commands might
24 non-interactively read an input file, perhaps doing some lexical
25 analysis and parsing of the input whle processing it.  If a low-level
26 input error is detected, it would be useful to be able to return
27 immediately to the ``main loop'' instead of having to make each of the
28 lexical analysis, parsing, and processing phases all have to explicitly
29 deal with error situations initially detected by nested calls.
30
31 (On the other hand, if each of these phases has to do a substantial
32 amount of cleanup when it exits --- such as closing files, deallocating
33 buffers or other data structures, and the like --- then it can be more
34 appropriate to do a normal return and have each phase do its own
35 cleanup, because a non-local jump would bypass the intervening phases and
36 their associated cleanup code entirely.  Alternatively, you could use a
37 non-local jump but do the cleanup explicitly either before or after
38 jumping.)
39
40 A return point for a non-local jump is established by calling the
41 function @code{setjmp}.  This saves information about the environment in
42 which the call to @code{setjmp} appears in an object of type
43 @code{jmp_buf}.  Execution of the program continues normally after the
44 call to @code{setjmp}, but if a jump is later made to this return point
45 by calling @code{longjmp} with the corresponding @code{jmp_buf} object,
46 control is transferred back to the point where @code{setjmp} was called.
47 The return value from @code{setjmp} is used to distinguish between an
48 ordinary return and a return made by a call to @code{longjmp}, so
49 usually calls to @code{setjmp} appear in a conditional statement.
50
51 Here is how the example program described above might be set up:  
52
53 @example
54 #include <setjmp.h>
55 #include <stdio.h>
56
57 jmp_buf main_loop;
58
59 void abort_to_main_loop (void)
60 @{
61   longjmp (main_loop, -1);
62 @}
63
64 main ()
65 @{
66   extern void do_command (void);
67   while (1)
68     if (setjmp (main_loop))
69       printf ("Back at main loop....\n");
70     else
71       do_command ();
72 @}
73 @end example
74
75 The function @code{abort_to_main_loop} causes an immediate transfer of
76 control back to the main loop of the program, no matter where it is
77 called from.
78
79 The flow of control inside the @code{main} function may appear a little
80 mysterious at first, but it is actually a common idiom with
81 @code{setjmp}.  A normal call to @code{setjmp} returns zero, so the
82 ``else'' clause of the conditional is executed.  If
83 @code{abort_to_main_loop} is called somewhere within the execution of
84 @code{do_command}, then it actually appears as if the @emph{same} call
85 to @code{setjmp} in @code{main} were returning a second time with a value
86 of @code{-1}.  In this particular example, we want both normal and
87 premature return from execution of a command to do the same thing ---
88 just execute the next command.
89
90 So, the general pattern for using @code{setjmp} looks something like:
91
92 @example
93 if (setjmp (@var{buffer}))
94   /* @r{Code to clean up after premature return.} */
95   @dots{}
96 else
97   /* @r{Code to be executed normally after setting up the return point.} */
98   @dots{}
99 @end example
100
101 @node Functions for Non-Local Jumps
102 @section Functions for Non-Local Jumps
103
104 Here are the details on the functions and data structures used for
105 performing non-local jumps.  These facilities are declared in
106 @file{<setjmp.h>}.
107
108 @deftp {Data Type} jmp_buf
109 Objects of type @code{jmp_buf} hold all of the state information which
110 must be restored when performing a non-local jump.
111 @end deftp
112
113 @deftypefun int setjmp (jmp_buf @var{env})
114 When called normally, @code{setjmp} stores the calling environment in
115 @var{env} and returns zero.  If @code{longjmp} is later used to perform
116 a non-local jump to this @var{env}, @code{setjmp} returns a nonzero value.
117 @end deftypefun
118
119 @deftypefun void longjmp (jmp_buf @var{env}, int @var{value}) 
120 This function restores current execution to the environment saved in
121 @var{env}, and continues execution from the call to @code{setjmp} that
122 established that environment.  Returning from @code{setjmp} by means of
123 @code{longjmp} returns the @var{value} argument that was passed to
124 @code{longjmp}, rather than @code{0}.  (If @var{value} is given as
125 @code{0}, @code{setjmp} returns @code{1}).@refill
126 @end deftypefun
127
128 There are a lot of obscure but important restrictions on the use of
129 @code{setjmp} and @code{longjmp}.  Most of these restrictions are
130 present because non-local jumps require a fair amount of magic on the
131 part of the C compiler and can interact with other parts of the language
132 in strange ways.
133
134 The @code{setjmp} function may be implemented as a macro without an
135 actual function definition, so you shouldn't try to @samp{#undef} it or
136 take its address.  In addition, calls to @code{setjmp} can appear
137 portably in only the following contexts:
138
139 @itemize @bullet
140 @item
141 As the controlling expression of a selection or iteration
142 statement (such as @code{if} or @code{while}).
143
144 @item
145 As one operand of a equality or comparison operator that appears as the
146 controlling expression of a selection or iteration statement.  The other
147 operand must be an integer constant expression.
148
149 @item
150 As the operand of a unary @code{!} operator, that appears as the
151 controlling expression of a selection or iteration statement.
152
153 @item
154 As the entire expression of an expression statement.
155 @end itemize
156
157 Exit points are valid only during the dynamic extent of the function
158 that called @code{setjmp} to establish them.  If you @code{longjmp} to
159 a return point that was established in a function that has already
160 returned, random miscellaneous terrible things are likely to happen.
161 This is not likely to produce the behavior you expected of your program,
162 so you should be very careful to be sure you know that the @var{env}
163 argument you give to @code{longjmp} is always valid.
164
165 You should also be careful to give a nonzero @var{value} argument to
166 @code{longjmp}.  While @code{longjmp} refuses to pass back a zero
167 argument as the return value from @code{setjmp}, this is intended more
168 as a safety net against accidental misuse and is not really good
169 programming style.
170
171 When you perform a non-local jump, accessible objects generally retain
172 whatever values they had at the time @code{longjmp} was called.  The
173 exception is that the values of automatic variables local to the
174 function containing the @code{setjmp} call that have been changed since
175 the call to @code{setjmp} are indeterminate, unless you have declared
176 them with the @code{volatile} qualifier.
177
178 The functions @code{setjmp} and @code{longjmp} do nothing to save and
179 restore the set of blocked signals; @pxref{Blocking Signals}.  There are,
180 however, analogous functions, @code{sigsetjmp} and @code{siglongjmp},
181 that do save and restore this information.
182
183 @deftp {Data Type} sigjmp_buf
184 This is similar to @code{jmp_buf}, except that it can also store state
185 information about the set of blocked signals.
186 @end deftp
187
188 @deftypefun int sigsetjmp (sigjmp_buf @var{env}, int @var{savesigs})
189 This is similar to @code{setjmp}.  If @var{savesigs} is nonzero, the set
190 of blocked signals is saved in @var{env} and will be restored if a
191 @code{siglongjmp} is later performed with this @var{env}.
192 @end deftypefun
193
194 @deftypefun void siglongjmp (sigjmp_buf @var{env}, int @var{value})
195 This is similar to @code{longjmp} except for the type of its @var{env}
196 argument.
197 @end deftypefun
198
199 @strong{Portability Note:}  The @code{sigsetjmp} and @code{siglongjmp}
200 functions are specified by the POSIX.1 standard.  But you can expect the
201 @code{setjmp} and @code{longjmp} functions to be available in any ANSI
202 C environment.