Standards / Extensions | C or C++ | Dependencies |
---|---|---|
ISO C |
both |
#include <setjmp.h>
__noreturn__ void longjmp(jmp_buf env, int value);
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.
Special behavior for POSIX: In a POSIX program, the signal mask is not saved. Thus, to save and restore a stack environment that includes the current signal mask, use sigsetjmp() and siglongjmp() instead of setjmp() and longjmp(). The sigsetjmp()—siglongjmp() pair, the setjmp()—longjmp() pair, the _setjmp()—_longjmp() pair, and the getcontext()—setcontext() pair cannot be intermixed. A stack environment saved by setjmp() can be restored only by longjmp().
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 to both 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 XPG4.2: In a program that was compiled with the feature test macro, _XOPEN_SOURCE_EXTENDED, defined, another pair of functions, _setjmp()—_longjmp() are available. These functions are, on this implementation, functionally identical to setjmp()—longjmp(). Therefore it is possible, but not recommended, to intermix the setjmp()—longjmp() pair with the _setjmp()—_longjmp() pair.
longjmp() does not use the normal function call and return mechanisms; it returns no values.
This example provides for saving the stack environment at this statement: if(setjmp(mark) != 0) …
When the system first performs the if statement, it saves the environment in mark and sets the condition to FALSE because setjmp() returns a 0 when it saves the environment. The program prints the message: setjmp has been called
The subsequent call to function p tests for a local error condition, which can cause it to perform the longjmp() function. Then, control returns to the original setjmp() function using the environment saved in mark. This time the condition is TRUE because -1 is the returned value from the longjmp() function. The example then performs the statements in the block and prints: longjmp has been called
/* Illustration of longjmp(). */
#include <stdio.h>
#include <setjmp.h>
jmp_buf mark;
void p(void);
void recover(void);
int main(void)
{
if (setjmp(mark) != 0)
{
printf("longjmp has been called\n");
recover();
exit(1);
}
printf("setjmp has been called\n");
⋮
p();
⋮
}
void p(void)
{
int error = 0;
⋮
error = 9;
⋮
if (error != 0)
longjmp(mark, -1);
⋮
}
void recover(void)
{
⋮
}