NAME

setjmp, longjmp, sigsetjmp, siglongjmp − 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;

int sigsetjmp (env, savemask)
sigjmp_buf env;
int savemask;

void siglongjmp (env, val)
sigjmp_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 returns 1.  All accessible data have values as of the time longjmp is 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. 

The two pairs of functions, _setjmp and _longjmp and sigsetjmp and siglongjmp behave identically to setjmp and longjmp except in the handling of the process’ signal mask (see sigaction(2) and sigvector(2)). This distinction is only significant for programs which use sigaction(2), sigprocmask(2), sigvector(2), sigblock(2), and/or sigsetmask(2). Setjmp and longjmp always save and restore the signal mask.  _setjmp and _longjmp never manipulate the signal mask.  Sigsetjmp saves the signal mask if and only if savemask is non-zero.  Siglongjmp restores the signal mask if and only if it is saved by sigsetjmp. The names setjmp and longjmp are used in a generic sense to describe all three variants. 

If a longjmp is executed and the environment in which the setjmp is executed no longer exists, errors can occur.  The conditions under which the environment of the setjmp no longer exists include exiting the procedure that contains the setjmp call, and exiting an inner block with temporary storage (such as a block with declarations in C or a with statement in Pascal).  This condition might not be detectable, in which case the longjmp occurs, and if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable.  This condition might 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, passing _longjmp a pointer to a buffer not created by either setjmp or _setjmp, passing siglongjmp a pointer to a buffer not created by sigsetjmp or passing any of these three functions 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 one exists. 

WARNINGS

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

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

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 that has since returned, absolute chaos is guaranteed.

AUTHOR

Setjmp was developed by AT&T and HP. 

SEE ALSO

sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). 

STANDARDS CONFORMANCE

setjmp: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

longjmp: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

siglongjmp: XPG3, POSIX.1, FIPS 151-1

sigsetjmp: XPG3, POSIX.1, FIPS 151-1

Hewlett-Packard Company  —  HP-UX Release 7.0: Sept 1989