Provides a way to transfer control from a nested series of function
invocations back to a predefined point without returning normally;
that is, by not using a series of return statements. The longjmp
function restores the context of the environment buffer.
Format
#include <setjmp.h>
void longjmp (jmp_buf env, int value);
Arguments
- env
- The environment buffer, which must be an array of integers long
enough to hold the register context of the calling function. The
type jmp_buf is defined in the <setjmp.h> header file. The contents
of the general-purpose registers, including the program counter
(PC), are stored in the buffer.
- value
- Passed from longjmp to setjmp, and then becomes the subsequent
return value of the setjmp call. If value is passed as 0,
it is converted to 1.
Description
When setjmp is first called, it returns the value 0. If
longjmp is then called, naming the same environment as the call to
setjmp, control is returned to the setjmp call as if it had returned
normally a second time. The return value of setjmp in this second
return is the value you supply in the longjmp call. To
preserve the true value of setjmp, the function calling setjmp must
not be called again until the associated longjmp is called.
The setjmp function preserves the hardware general purpose
registers, and the longjmp function restores them. After a longjmp,
all variables have their values as of the time of the longjmp except
for local automatic variables not marked volatile. These variables
have indeterminate values.
The setjmp and longjmp functions rely on the OpenVMS condition-
handling facility to effect a nonlocal goto with a signal
handler. The longjmp function is implemented by generating a DEC C RTL specified signal and allowing the
OpenVMS condition-handling facility to unwind back to the desired
destination. The DEC C RTL must be in
control of signal handling for any DEC C
image.
For DEC C to be in control of signal
handling, you must establish all exception handlers through a
call to the VAXC$ESTABLISH function (rather than LIB$ESTABLISH).
See Section 4.2.5 and the
VAXC$ESTABLISH function in this section for more information.
Restrictions
You cannot invoke the longjmp function from a OpenVMS
condition handler. However, you may invoke longjmp from a signal
handler that has been established for any signal supported by the
DEC C RTL, subject to the following nesting
restrictions:
- The longjmp function will not work if invoked from nested
signal handlers. The result of the longjmp function, when invoked
from a signal handler that has been entered as a result of an
exception generated in another signal handler, is undefined.
- Do not invoke the setjmp function from a signal handler
unless the associated longjmp is to be issued before the handling
of that signal is completed.
- Do not invoke the longjmp function from within an exit
handler (established with atexit or SYS$DCLEXH). Exit handlers
are invoked after image tear-down, so the destination address of
the longjmp no longer exists.
- Invoking longjmp from within a signal handler to return
to the main thread of execution might leave your program in an
inconsistent state. Possible side effects include the inability
to perform I/O or to receive any more UNIX signals.
Previous Page | Next Page | Table of Contents | Index