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