HPUX setjmp[3c]
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 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 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
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
setjmp(3C) setjmp(3C)
which use sigaction(), sigprocmask(), sigvector(), 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 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.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
setjmp(3C) setjmp(3C)
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.
AUTHOR
setjmp() was developed by AT&T and HP.
SEE ALSO
sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2),
sigspace(2), sigsuspend(2), sigvector(2).
STANDARDS CONFORMANCE
setjmp(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
longjmp(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
siglongjmp(): AES, XPG3, XPG4, FIPS 151-2, POSIX.1
sigsetjmp(): AES, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992