longjmp()

Updated: October 28, 2024

Restore the environment saved by setjmp()

Synopsis:

#include <setjmp.h>

void longjmp( jmp_buf env, 
              int return_value );

Arguments:

env
The environment saved by the most recent 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 the most recent call to the setjmp() function.

Note: Using longjmp() to jump out of a signal handler can cause unpredictable behavior, unless the signal was generated by the raise() function.

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
Interrupt handler 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.