_setjmp() — Set jump point for a nonlocal goto
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
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.
- 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().
- 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.
- 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.
Related information
- setjmp.h
- getcontext() — Get user context
- longjmp() — Restore stack environment
- _longjmp() — Nonlocal goto
- setcontext() — Restore user context
- setjmp() — Preserve stack environment
- siglongjmp() — Restore the stack environment and signal mask
- sigsetjmp() — Save stack environment and signal mask
- swapcontext() — Save and restore user context