setjmp(3)setjmp(3)NAME
setjmp, _setjmp, longjmp, _longjmp - Save and restores the current exe‐
cution context
SYNOPSIS
#include <setjmp.h>
int setjmp(
jmp_buf environment ); void longjmp(
jmp_buf environment,
int value ); int _setjmp(
jmp_buf environment ); void _longjmp(
jmp_buf environment,
int value );
LIBRARY
Standard C Library (libc)
System V Library (libsys5.a, libsys5.so)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
setjmp(), longjmp(): XSH4.2
_setjmp(), _longjmp(): XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies an address for a jmp_buf structure. Specifies the value you
want written to the execution context as the return value of the
setjmp() or _setjmp() function. If you specify 0 (zero) in this parame‐
ter, the execution context contains a value of 1 as the setjmp() or
_setjmp() return value. See the RETURN VALUES section for more infor‐
mation.
DESCRIPTION
The setjmp() and longjmp() functions are useful when handling errors
and interrupts encountered in low-level functions of a program.
The setjmp() function saves the current stack context and signal mask
in the buffer specified by the environment parameter. You then use the
buffer in a later call to the longjmp() function. The longjmp() func‐
tion restores the stack context and signal mask that were saved by the
setjmp() function.
After the longjmp() function runs, program execution continues as
though the corresponding call to the setjmp() function had just
returned the value of the value parameter. The function that called
the setjmp() function must not have returned before the completion of
the longjmp() function.
The _setjmp() and _longjmp() functions operate identically to the
setjmp() and longjmp() functions, respectively, except that _setjmp()
and _longjmp() manipulate only the stack context. These functions do
not restore the signal mask.
All accessible objects have values at the time longjmp() is called,
except for some objects of automatic storage duration. Objects of auto‐
matic storage duration will have indeterminant values if they meet all
of the following conditions: They are local to the function containing
the corresponding setjmp() invocation. They do not have volatile-qual‐
ified type. They are changed between the setjmp() and the longjmp()
call.
Because it bypasses the usual function call and return mechanisms, the
longjmp() function executes correctly in contexts of interrupts, sig‐
nals, and any of their associated functions. However, if the longjmp()
function is invoked from a nested signal handler (that is, from a func‐
tion invoked as a result of a signal raised during the handling of
another signal), the behavior is undefined.
NOTES
[Tru64 UNIX] For compatibility, the System V versions of the setjmp()
and longjmp() functions, which are equivalent to _setjmp() and
_longjmp(), respectively, are also supported. To use the System V ver‐
sions of setjmp() and longjmp(), you must link with the libsys5 library
before you link with libc.
RETURN VALUES
After the longjmp() function is finished executing, program execution
continues as though the corresponding call of the setjmp() function
just returned. In other words, the execution context saved by the cor‐
responding setjmp() function is in place and execution continues at the
statement immediately following the call to the setjmp() function.
Part of that execution context is the return value from the setjmp()
function. When the setjmp() function actually returns (before the call
to the longjmp() function), that return value is 0 (zero). When the
longjmp() function returns, the execution context contains a non-zero
value as the return value from the setjmp() function.
The value you specify in the value parameter to the longjmp() function
is written to the execution context as the return value for the
setjmp() function. You cannot cause the execution context to contain a
0 (zero) value for the setjmp() return value. If you specify 0 in the
value parameter, the execution context contains a 1 as the setjmp()
return value.
CAUTION
The results of the longjmp() function are undefined in the following
situations: The longjmp() function is called with an environment param‐
eter that was not previously set by the setjmp() function. The func‐
tion that made the corresponding call to the setjmp() function has
already returned.
If the longjmp() function detects one of these conditions, it calls the
longjmperror() function. If longjmperror() returns, the program is
aborted. The default version of longjmperror() displays an error mes‐
sage to standard error and returns. If you want your program to exit
more gracefully, you can write your own version of the longjmperror()
program.
SEE ALSO
Routines: siglongjmp(3), sigsetjmp(3)
Standards: standards(5)setjmp(3)