setjmp(3C)

NAME

setjmp(), longjmp(), sigsetjmp(), siglongjmp() — non-local goto

SYNOPSIS

#include <setjmp.h>

int setjmp(jmp_buf env);

void longjmp(jmp_buf env, int val);

int _setjmp(jmp_buf env);

void _longjmp(jmp_buf env, int val);

int sigsetjmp(sigjmp_buf env, int savemask);

void siglongjmp(sigjmp_buf env, int val);

DESCRIPTION

setjmp() and longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: setjmp() and longjmp(); _setjmp() and _longjmp(); sigsetjmp() and siglongjmp(). Unless indicated otherwise, references to setjmp() and longjmp() apply to all three versions.

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 values are valid as of the time longjmp() is called.

Upon the return from a setjmp() call caused by a longjmp(), the values of any non-static or non-volatile 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.

Variant Forms

The following functions behave the same as setjmp() and longjmp() except in the handling of the process' signal mask (see sigaction(2)). This distinction is only significant for programs which use sigaction(), sigprocmask(), sigblock(), and/or sigsetmask().

setjmp()
longjmp(): These always save and restore the signal mask.
_setjmp()
_longjmp(): These never manipulate the signal mask.
sigsetjmp(): Saves the signal mask of the calling thread if and only if savemask is non-zero.
siglongjmp(): Restores the signal mask if and only if it is saved by sigsetjmp().

Programming Considerations

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() 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, total chaos is guaranteed.

The effect of a call to longjmp() where the initialization of the jmp_buf argument was not performed in the calling thread is undefined. The effect of a call to siglongjmp() where the initialization of the sigjmp_buf argument was not performed in the calling thread is undefined.

The contents of the jmp_buf buffer are architecture and compilation environment specific. Thus, objects built using these functions may not be supported across architectures.

AUTHOR

setjmp() was developed by AT&T and HP.

STANDARDS CONFORMANCE

setjmp(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

longjmp(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

siglongjmp(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1

sigsetjmp(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1

setjmp(3C)

Technical documentation

» Table of Contents

» Index