_longjmp() — Nonlocal goto

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <setjmp.h>

void _longjmp(jmp_buf env, int value);

General description

The _longjmp() function restores a stack environment previously saved in env by _setjmp(). 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 the current stack environment to be saved in env.

A subsequent call to _longjmp() restores the saved environment and returns control to a point in the program corresponding to the _setjmp() call. Execution resumes as if the _setjmp() call had just returned the given value of the value argument. All variables that are accessible to the function that receives 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 X/Open standard states that _longjmp() and _setjmp() are functionally identical to longjmp() and setjmp(), respectively, with the addition restriction that _longjmp() and _setjmp() do not manipulate the signal mask. However, on this implementation longjmp() and setjmp() do not manipulate the signal mask. So on this implementation _longjmp() and _setjmp() 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:
  1. 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.
  2. 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.
  3. If _longjmp() is used to jump back into an XPLink routine, any alloca() requests issued by the XPLink routine after the earlier _setjmp() (or setjmp(), sigsetjmp(), getcontext() and so on) was called and before _longjmp() is called are backed out. All storage obtained by these alloca() requests is freed before the XPLink routine is resumed.
  4. If _longjmp() is used to jump back into a non-XPLink routine, alloca() requests made after _setjmp() (and so on) and before _longjmp() are not backed out.
The value argument passed to _longjmp() must be nonzero. If you give a zero argument for value, _longjmp() substitutes a 1 in its place.
env
An address for a jmp_buf structure
value
The return value from _setjmp()

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. Additionally, if any automatic objects would be destroyed by a thrown exception transferring control to another (destination) point in the program, then a call to _longjmp() at the throw point that transfers control to the same (destination) point has undefined behavior. 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:
  1. All XPLINK programs compiled with the Release 10 or later C compilers that are to run with Language Environment Release 10 or later libraries and use the jmp_buf, sigjmp_buf or ucontext_t types must not be compiled with C headers from Language Environment® 2.9 or earlier.
  2. Non-XPLINK functions compiled with any level of Language Environment headers must not definejmp_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.
  3. When __XPLINK__ is defined, the Release 10 and later headers define a larger jmp_buf, sigjmp_buf or ucontext_tarea that is required by setjmp(), getcontext(), and related functions when they are called from an XPLINK routine. If __XPLINK__ is not defined, the Release 10 and later headers define a shorter jmp_buf, sigjmp_buf or ucontext_t area. The Language Environment headers before Release 10 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

_longjmp() does not use the normal function call and return mechanisms; it returns no values. When _longjmp() completes, program execution continues as if the corresponding invocation of _setjmp() had just returned the value specified by value.

Related information

Parent topic: Library functions