-@node Non-Local Exits
+@node Non-Local Exits, Signal Handling, Date and Time, Top
@chapter Non-Local Exits
@cindex non-local exits
@cindex long jumps
functions.
@menu
-* Introduction to Non-Local Exits:: An overview of how and when to use
- these facilities.
-* Functions for Non-Local Exits:: Details of the interface.
-* Non-Local Exits and Blocked Signals:: Portability issues.
+* Intro: Non-Local Intro. When and how to use these facilities.
+* Details: Non-Local Details. Functions for nonlocal exits.
+* Non-Local Exits and Signals:: Portability issues.
@end menu
-@node Introduction to Non-Local Exits
+@node Non-Local Intro, Non-Local Details, , Non-Local Exits
@section Introduction to Non-Local Exits
As an example of a situation where a non-local exit can be useful,
detected by nested calls.
(On the other hand, if each of these phases has to do a substantial
-amount of cleanup when it exits --- such as closing files, deallocating
-buffers or other data structures, and the like --- then it can be more
+amount of cleanup when it exits---such as closing files, deallocating
+buffers or other data structures, and the like---then it can be more
appropriate to do a normal return and have each phase do its own
cleanup, because a non-local exit would bypass the intervening phases and
their associated cleanup code entirely. Alternatively, you could use a
environment in which the call to @code{setjmp} appears in an object of
type @code{jmp_buf}. Execution of the program continues normally after
the call to @code{setjmp}, but if a exit is later made to this return
-point by calling @code{longjmp} with the corresponding @code{jmp_buf}
+point by calling @code{longjmp} with the corresponding @w{@code{jmp_buf}}
object, control is transferred back to the point where @code{setjmp} was
called. The return value from @code{setjmp} is used to distinguish
between an ordinary return and a return made by a call to
@code{longjmp}, so calls to @code{setjmp} usually appear in an @samp{if}
statement.
-Here is how the example program described above might be set up:
+Here is how the example program described above might be set up:
-@example
-#include <setjmp.h>
-#include <stdio.h>
-
-jmp_buf main_loop;
-
-void abort_to_main_loop (void)
-@{
- longjmp (main_loop, -1);
-@}
-
-main ()
-@{
- extern void do_command (void);
- while (1)
- if (setjmp (main_loop))
- printf ("Back at main loop....\n");
- else
- do_command ();
-@}
-@end example
+@smallexample
+@include setjmp.c.texi
+@end smallexample
The function @code{abort_to_main_loop} causes an immediate transfer of
control back to the main loop of the program, no matter where it is
to @code{setjmp} in @code{main} were returning a second time with a value
of @code{-1}.
+@need 250
So, the general pattern for using @code{setjmp} looks something like:
-@example
+@smallexample
if (setjmp (@var{buffer}))
/* @r{Code to clean up after premature return.} */
@dots{}
else
/* @r{Code to be executed normally after setting up the return point.} */
@dots{}
-@end example
+@end smallexample
-@node Functions for Non-Local Exits
-@section Functions for Non-Local Exits
+@node Non-Local Details, Non-Local Exits and Signals, Non-Local Intro, Non-Local Exits
+@section Details of Non-Local Exits
Here are the details on the functions and data structures used for
performing non-local exits. These facilities are declared in
@pindex setjmp.h
@comment setjmp.h
-@comment ANSI
+@comment ISO
@deftp {Data Type} jmp_buf
Objects of type @code{jmp_buf} hold the state information to
be restored by a non-local exit. The contents of a @code{jmp_buf}
@end deftp
@comment setjmp.h
-@comment ANSI
-@deftypefun int setjmp (jmp_buf @var{state})
+@comment ISO
+@deftypefn Macro int setjmp (jmp_buf @var{state})
When called normally, @code{setjmp} stores information about the
execution state of the program in @var{state} and returns zero. If
@code{longjmp} is later used to perform a non-local exit to this
@var{state}, @code{setjmp} returns a nonzero value.
-@end deftypefun
+@end deftypefn
@comment setjmp.h
-@comment ANSI
-@deftypefun void longjmp (jmp_buf @var{state}, int @var{value})
+@comment ISO
+@deftypefun void longjmp (jmp_buf @var{state}, int @var{value})
This function restores current execution to the state saved in
@var{state}, and continues execution from the call to @code{setjmp} that
established that return point. Returning from @code{setjmp} by means of
part of the C compiler and can interact with other parts of the language
in strange ways.
-The @code{setjmp} function may be implemented as a macro without an
-actual function definition, so you shouldn't try to @samp{#undef} it or
-take its address. In addition, calls to @code{setjmp} are safe in only
-the following contexts:
+The @code{setjmp} function is actually a macro without an actual
+function definition, so you shouldn't try to @samp{#undef} it or take
+its address. In addition, calls to @code{setjmp} are safe in only the
+following contexts:
@itemize @bullet
@item
As the test expression of a selection or iteration
-statement (such as @samp{if} or @samp{while}).
+statement (such as @samp{if}, @samp{switch}, or @samp{while}).
@item
As one operand of a equality or comparison operator that appears as the
the call to @code{setjmp} are indeterminate, unless you have declared
them @code{volatile}.
-@node Non-Local Exits and Blocked Signals
-@section Non-Local Exits and Blocked Signals
+@node Non-Local Exits and Signals,, Non-Local Details, Non-Local Exits
+@section Non-Local Exits and Signals
In BSD Unix systems, @code{setjmp} and @code{longjmp} also save and
-restore the set of blocked signals; @pxref{Blocking Signals}. However,
+restore the set of blocked signals; see @ref{Blocking Signals}. However,
the POSIX.1 standard requires @code{setjmp} and @code{longjmp} not to
change the set of blocked signals, and provides an additional pair of
functions (@code{sigsetjmp} and @code{sigsetjmp}) to get the BSD
behavior.
The behavior of @code{setjmp} and @code{longjmp} in the GNU library is
-controlled by feature test macros; @pxref{Feature Test Macros}. The
+controlled by feature test macros; see @ref{Feature Test Macros}. The
default in the GNU system is the POSIX.1 behavior rather than the BSD
behavior.
@comment POSIX.1
@deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value})
This is similar to @code{longjmp} except for the type of its @var{state}
-argument.
+argument. If the @code{sigsetjmp} call that set this @var{state} used a
+nonzero @var{savesigs} flag, @code{siglongjmp} also restores the set of
+blocked signals.
@end deftypefun
-
projects / kopensolaris-gnu / glibc.git / blobdiff