setjmp.3c (2010 09)

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()
cannot 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)). This distinction is only significant for programs which use
sigaction(), sigprocmask(), sigblock()
,and/orsigsetmask().
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 tem-
porary 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
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1