Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
XPG4.2
Single UNIX Specification, Version 3
|
both |
|
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <setjmp.h>
int _setjmp(jmp_buf env);
General description
The _setjmp()
function saves a stack environment that can subsequently be restored
by _longjmp(). The _setjmp() and _longjmp() functions provide a way
to perform a nonlocal goto. They are often used
in signal handlers.
A call to _setjmp() causes it to save the
current stack environment in env. A subsequent
call to _longjmp() restores the saved environment and returns control
to a point corresponding to the _setjmp() call. The values of all
variables, except register variables, and except nonvolatile automatic
variables, accessible to the function receiving control contain the
values they had when _longjmp() was called. The values of register
variables are unpredictable. Nonvolatile auto variables
that are changed between calls to _setjmp() and _longjmp() are also
unpredictable.
An invocation of _setjmp() must appear in one
of the following contexts only:
- The entire controlling expression of a selection or iteration
statement.
- One operand of a relational or equality operator with the other
operand an integral constant expression, with the resulting expression
being the entire controlling expression of a selection or iteration
statement.
- The operand of a unary "!" operator with the resulting expression
being the entire controlling expression of a selection or iteration.
- The entire expression of an expression statement (possibly cast
to void).
The X/Open standard states that _setjmp() and _longjmp()
are functionally identical to longjmp() and setjmp(), respectively,
with the addition restriction that _setjmp() and _longjmp() do not
manipulate the signal mask. However, on this implementation longjmp()
and setjmp() do not manipulate the signal mask. So on this implementation
_setjmp() and _longjmp() are literally identical to longjmp() and
setjmp(), respectively.
To save and restore a stack environment,
including the current signal mask, use sigsetjmp() and siglongjmp()
instead of _setjmp() and _longjmp(), or setjmp() and longjmp().
The
_setjmp()—_longjmp() pair, the setjmp()—longjmp() pair, the sigsetjmp()—siglongjmp()
pair, and the getcontext()—setcontext() pair cannot be intermixed.
A stack environment saved by _setjmp() can be restored only by _longjmp().
Notes: - However, on this implementation, since the _setjmp()—_longjmp()
pair are functionally identical to the setjmp()—longjmp() pair it
is possible to intermix them, but it is not recommended.
- Ensure that the function that calls _setjmp() does not return
before you call the corresponding _longjmp() function. Calling _longjmp()
after the function calling _setjmp() returns causes unpredictable
program behavior.
Special behavior for C++: If
_setjmp() and _longjmp() are used to transfer control in a z/OS® XL C++ program,
the behavior in terms of the destruction of automatic objects is undefined.
This applies both to z/OS XL C++ and z/OS XL C/C++ ILC modules.
The use of _setjmp() and _longjmp() in conjunction with try(), catch(),
and throw() is also undefined.
Special
behavior for XPLINK-compiled C++: Restrictions
concerning setjmp.h and ucontext.h:
- All XPLINK programs
compiled with the V2R10 or later C compilers that are to run with Language Environment V2R10
or later libraries and use the jmp_buf, sigjmp_buf or ucontext_t types
must not be compiled with C headers from Language Environment V2R9 or
earlier.
- Non-XPLINK functions
compiled with any level of Language Environment headers
must not define jmp_buf, sigjmp_buf or ucontext_t data
items and pass them to XPLINK functions
that call getcontext(), longjmp(), _longjmp(), setjmp(), _setjmp(),
setcontext(), sigsetjmp(), or swapcontext() with these passed-in data
items.
- When __XPLINK__
is defined, the Language Environment V2R10
and later headers define a larger jmp_buf, sigjmp_buf or ucontext_t area
that is required by setjmp(), getcontext(), and related functions
when they are called from an XPLINK routine.
If __XPLINK__
is not defined, the Language Environment V2R10
and later headers define a shorter jmp_buf, sigjmp_buf or ucontext_t
area. The Language Environment headers
before V2R10 also define the shorter version of these data areas.
If an XPLINK function
calls setjmp(), getcontext() or similar functions with a short jmp_buf, sigjmp_buf or ucontext_t area,
a storage overlay or program check may occur when the C library tries
to store past the end of the passed-in (too short) data area.
Returned value
_setjmp() returns 0 after
saving the stack environment.
If _setjmp() returns as a result
of a _longjmp() call, it returns the value argument
of _longjmp(), or 1 if the value argument
of _longjmp() was 0.