NAME

setjmp, longjmp − non-local goto

SYNOPSIS

#include <setjmp.h>

val = setjmp(env)
jmp_buf env;

longjmp(env, val)
jmp_buf env;

val = _setjmp(env)
jmp_buf env;

_longjmp(env, val)
jmp_buf env;

DESCRIPTION

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

Setjmp saves its stack environment in env for later use by longjmp. Setjmp also saves the register environment.  If a longjmp call will be made, the routine which called setjmp should not return until after the longjmp has returned control (see below). 

Longjmp restores the environment saved by the last call of setjmp, and then returns in such a way that execution continues as if the call of setjmp had just returned the value val to the function that invoked setjmp. The calling function must not itself have returned in the interim, otherwise longjmp will be returning control to a possibly non-existent environment.  All memory-bound data have values as of the time longjmp was called.  The machine registers are restored to the values they had at the time that setjmp was called.  But, because the register storage class is only a hint to the C compiler, variables declared as register variables may not necessarily be assigned to machine registers, so their values are unpredictable after a longjmp. This is especially a problem for programmers trying to write machine-independent C routines.

The following code fragment indicates the flow of control of the setjmp and longjmp combination:

$. . . . function declaration
jmp_bufmy_environment;
 $. . . . code . . .
if (setjmp(my_environment))  {
this is the code after the return from longjmp
$. . . . more code . . . .
register variables have unpredictable values
$. . . . more code . . . .
} else  {
this is the return from setjmp
$. . . . more code . . . .
Do not modify register variables
in this leg of the code
$. . . . more code  . . . .
}

Setjmp and longjmp save and restore the signal mask sigsetmask(2), while _setjmp and _longjmp manipulate only the C stack and registers. 

SEE ALSO

sigsetmask(2), sigvec(2), signal(3)

BUGS

Setjmp does not save current notion of whether the process is executing on the signal stack.  The result is that a longjmp to some place on the signal stack leaves the signal stack state incorrect. 

longjmp never returns zero in the Sun implementation. 

Sun Release 3.2  —  Last change: 17 February 1986