longjmp()

QNX SDP8.0C Library ReferenceAPIDeveloper

Restore the environment saved by setjmp()

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.

In QNX OS, 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.

Warning:

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.

CAUTION:

Using longjmp() to jump out of a signal handler can cause unpredictable behavior, unless the signal was generated by the raise() function.
In addition to the situation explained in the note above, the following condition also results in undefined behavior:
- The jmp_buf object represents an execution context that no longer exists (i.e., the block scope containing the setjmp() call that populated the object has ended).
QNX OS attempts to detect the cases listed below, and when it does, the OS outputs a diagnostic message and terminates the program abnormally via a SIGABRT signal:
- The jmp_buf object was not populated by a call to setjmp() or sigsetjmp().
- The object was populated via setjmp() or sigsetjmp() but subsequently corrupted.

In the restored environment, all components (data types, status flags, and open files) have state and values, except for data objects with automatic storage duration. For these objects, their values are unspecified if all of the following conditions hold:

They are local to the function containing the corresponding setjmp() invocation.
They do not have a volatile-qualified type.
They are changed between the setjmp() invocation and longjmp() call.

Returns:

A call to longjmp() does not return. After this function restores the environment, program execution continues as if the corresponding call to setjmp() had just returned the value specified by return_value. If 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 )
{
    switch( setjmp( env ) ) {
    case 0:
        printf( "after setjmp()\n" );
        rtn();
        printf( "back from rtn() (UNEXPECTED!)\n" );
        break;
    case 14:
        printf( "back from longjmp()\n" );
        break;
    default:
        printf( "setjmp() returned something UNEXPECTED!\n" );
        break;
    }

    return EXIT_SUCCESS;
}

produces the following output:

after setjmp()
about to longjmp()
back from longjmp()

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.

Page updated: December 04, 2024