VMS Help  —  CRTL  longjmp
    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);

1  –  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.

2  –  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
    C RTL specified signal and allowing the OpenVMS condition-
    handling facility to unwind back to the desired destination.
    The C RTL must be in control of signal handling for any
    VSI C image.

    For VSI 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).

                                   NOTE

       The C RTL provides nonstandard decc$setjmp and decc$fast_
       longjmp functions for Alpha and Integrity server systems.
       To use these nonstandard functions instead of the standard
       ones, a program must be compiled with the __FAST_SETJMP or
       __UNIX_SETJMP macros defined.

       Unlike the standard longjmp function, the decc$fast_longjmp
       function does not convert its second argument from 0 to 1.
       After a call to decc$fast_longjmp, a corresponding setjmp
       function returns with the exact value of the second argument
       specified in the decc$fast_longjmp call.

3  –  Restrictions

    You cannot invoke the longjmp function from an OpenVMS condition
    handler. However, you may invoke longjmp from a signal handler
    that has been established for any signal supported by the
    C RTL, subject to the following nesting restrictions:

    o  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.

    o  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.

    o  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.

    o  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.
Close Help