NAME

setjmp, longjmp − non-local goto

SYNOPSIS

#include <setjmp.h>

int setjmp (env)
jmp_buf env;

void longjmp (env, val)
jmp_buf env;
int val;

int _setjmp(env)
jmp_buf env;

void _longjmp(env, val)
jmp_buf env;
int val;

DESCRIPTION

These functions are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. 

Setjmp saves its stack environment in env (whose type, jmp_buf, is defined in the <setjmp.h> header file) for later use by longjmp. It returns the value 0.

Longjmp restores the environment saved by the last call of setjmp with the corresponding env argument.  After longjmp is completed, program execution continues as if the corresponding call of setjmp (which must not itself have returned in the interim) had just returned the value val. Longjmp cannot cause setjmp to return the value 0.  If longjmp is invoked with a second argument of 0, setjmp will return 1.  All accessible data have values as of the time longjmp was called. 

Upon the return from a setjmp call caused by a longjmp, the values of any non-static local variables belonging to the routine from which setjmp was called are undefined.  Code which depends on such values is not guaranteed to be portable. 

Setjmp and longjmp save and restore the signal mask (see sigvector(2)), while _setjmp and _longjmp manipulate only the stack and registers.  This distinction is only significant for programs which use sigvector(2), sigblock(2), and/or sigsetmask(2).

If a longjmp is executed and the environment in which the setjmp was executed no longer exists, errors can occur.  The conditions under which the environment of the setjmp no longer exists include: exiting the procedure which contains the setjmp call, and exiting an inner block with temporary storage (e.g. a block with declarations in C, a with statement in Pascal).  This condition may or may not be detectable.  An attempt is made by determining if the stack frame pointer in env points to a location not in the currently active stack.  If this is the case, longjmp will return a -1.  Otherwise, the longjmp will occur, and if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable.  This condition may also cause unexpected process termination.  If the procedure has been exited the results are unpredictable. 

Passing longjmp a pointer to a buffer not created by setjmp, or a buffer that has been modified by the user, can cause all the problems listed above, and more. 

Some implementations of Pascal support a try/recover mechanism, which also creates stack marker information.  If a longjmp operation occurs in a scope which is nested inside a try/recover, and the corresponding setjmp is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the setjmp (if there is one). 

NOTES

A call to longjmp to leave the guaranteed stack space reserved by sigspace(2) may remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space.  It may also cause the program to forever loose its ability to automatically increase the stack size, and the program may then be limited to the guaranteed space.

The result of using setjmp within an expression may be unpredictable. 

SEE ALSO

sigblock(2), signal(2), sigsetmask(2), sigspace(2), sigvector(2). 

WARNING

If longjmp is called even though env was never primed by a call to setjmp, or when the last such call was in a function which has since returned, absolute chaos is guaranteed.

Hewlett-Packard Company  —  May 11, 2021