HP-UX Reference (11i v1 05/09) - 3 Library Functions N-Z (vol 7)

s
setjmp(3C) 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 execu-
tion continues as if the corresponding call of
setjmp() (which must not itself
have returned in the interim) had just returned the value val.
longjmp() can-
not cause setjmp() to return the value 0.Iflongjmp() 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) and sigvector(2)). This distinction is only significant for programs
which use
sigaction() , sigprocmask()
, sigvector() , sigblock() ,and/orsigset-
mask()
.
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 detect-
able, 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.
Section 3−−876 Hewlett-Packard Company − 1 − HP-UX 11i Version 1: September 2005