NAME

setjmp, longjmp, _setjmp, _longjmp, sigsetjmp, siglongjmp − non-local goto

SYNOPSIS

/usr/ucb/cc [ flag ... ] file ...

#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. 

setjmp() saves its stack environment in env for later use by longjmp().  A normal call to setjmp() returns zero.  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(); however, if val were zero, execution would continue as if the call of setjmp() had returned one.  This ensures that a “return” from setjmp() caused by a call to longjmp() can be distinguished from a regular return from 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 CPU and floating-point data 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. 

setjmp() and longjmp() save and restore the signal mask while _setjmp() and _longjmp() manipulate only the C stack and registers.  If the savemask flag to sigsetjmp() is non-zero, the signal mask is saved, and a subsequent siglongjmp() using the same env will restore the signal mask.  If the savemask flag is zero, the signal mask is not saved, and a subsequent siglongjmp() using the same env will not restore the signal mask.  In all other ways, _setjmp() and sigsetjmp() function in the same way that setjmp() does, and _longjmp() and siglongjmp() function in the same way that longjmp() does. 

None of these functions save or restore any floating-point status or control registers. 

EXAMPLE

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

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

SEE ALSO

cc(1B), signal(2), setjmp(3C), sigvec(3B)

BUGS

setjmp() does not save the 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. 

On some systems setjmp() also saves the register environment.  Therefore, all data that are bound to registers are restored to the values they had at the time that setjmp() was called.  All memory-bound data have values as of the time longjmp() was called.  However, 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().  When using compiler options that specify automatic register allocation (see cc(1B)), the compiler will not attempt to assign variables to registers in routines that call setjmp(). 

longjmp() never causes setjmp() to return zero, so programmers should not depend on longjmp() being able to cause setjmp() to return zero. 

NOTES

In contrast to setjmp(3B), setjmp(3C) does save its stack environment in env for later use by longjmp(). And, in contrast to sigsetjmp(), saves the calling process’s registers and stack environment (see sigaltstack(2)) in env for later use by siglongjmp().

SunOS 5.1/x86  —  Last change: 6 Jun 1991