setjmp() — Preserve stack environment

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <setjmp.h>

int setjmp(jmp_buf env);

General description

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 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).

Note: 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 POSIX C: To save and restore a stack environment that includes a signal mask, use sigsetjmp() and siglongjmp(), instead of setjmp().

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 only be restored 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. 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 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. On this implementation, these calls are functionally identical to setjmp()—longjmp(). Therefore it is possible, but not recommended, to intermix the setjmp()—longjmp() pair with the _setjmp()—_longjmp() pair.

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 the value 1 if the value argument of longjmp() is equal to 0.

Example

This example stores the stack environment at the 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 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 program then performs the statements in the block and prints: longjmp has been called. Finally, the program calls the recover function and exits.

/* This example shows the effect of having set the stack environment.  */
#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)
{
⋮
}