longjmp()

Synopsis:

#include <setjmp.h>

void longjmp( jmp_buf env, 
              int return_value );

Arguments:

env: The environment saved by a previous call to setjmp().
return_value: The value that you want setjmp() to return.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The longjmp() function restores the environment saved in env by a previous call to the setjmp() function.

CAUTION:

Using longjmp() to jump out of a signal handler can cause unpredictable behavior, unless the signal was generated by the raise() function.
The following conditions result in undefined behavior:
- The jmp_buf object passed to longjmp() was not populated by a previous call to setjmp() made from the same thread.
- The jmp_buf object represents an execution context that no longer exists (i.e., the block scope containing the setjmp() call that populated the jmp_buf object has ended).
QNX OS outputs a diagnostic message and terminates the program abnormally via a SIGABRT signal if:
- You call longjmp() on a jmp_buf object that has not been populated by a call to setjmp() or sigsetjmp(), or
- the jmp_buf was populated via setjmp() or sigsetjmp() but subsequently corrupted.
The setjmp() function does not save the thread's signal mask and longjmp() does not restore it. If you need to save and restore the thread's signal mask, use sigsetjmp() and siglongjmp() instead.

Returns:

After the longjmp() function restores the environment, program execution continues as if the corresponding call to setjmp() had just returned the value specified by return_value. If the value of return_value is 0, the value returned is 1.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <setjmp.h>

jmp_buf env;

void rtn( void )
{
    printf( "about to longjmp\n" );
    longjmp( env, 14 );
}

int main( void )
{
    int ret_val = 293;

    if( 0 == ( ret_val = setjmp( env ) ) ) {
        printf( "after setjmp %d\n", ret_val );
        rtn();
        printf( "back from rtn %d\n", ret_val );
    } else {
        printf( "back from longjmp %d\n", ret_val );
    }
    
    return EXIT_SUCCESS;
}

produces the following output:

after setjmp 0
about to longjmp
back from longjmp 14

Classification:

ANSI, POSIX 1003.1


Safety:
Cancellation point	No
Signal handler	Yes
Thread	Yes

Caveats:

A strictly-conforming POSIX application can't assume that the longjmp() function is signal-safe on other platforms.

DANGER:

Don't use longjmp() or siglongjmp() to restore an environment saved by a call to setjmp() or sigsetjmp() in another thread. If you're lucky, your application will crash; if not, it'll look as if it works for a while, until random scribbling on the stack causes it to crash.