Non-Local Details (The GNU C Library)

### 24.2 Details of Non-Local Exits ¶

Here are the details on the functions and data structures used for performing non-local exits. These facilities are declared in `setjmp.h`.

Data Type: jmp_buf ¶

  Objects of type `jmp_buf` hold the state information to be restored by a non-local exit. The contents of a `jmp_buf` identify a specific place to return to.

Macro: `int` setjmp `(jmp_buf state)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  When called normally, `setjmp` stores information about the execution state of the program in state and returns zero. If `longjmp` is later used to perform a non-local exit to this state, `setjmp` returns a nonzero value.

Function: `void` longjmp `(jmp_buf state, int value)` ¶

  Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd | AC-Unsafe corrupt lock/hurd | See POSIX Safety Concepts.

  This function restores current execution to the state saved in state, and continues execution from the call to `setjmp` that established that return point. Returning from `setjmp` by means of `longjmp` returns the value argument that was passed to `longjmp`, rather than `0`. (But if value is given as `0`, `setjmp` returns `1`).

There are a lot of obscure but important restrictions on the use of `setjmp` and `longjmp`. Most of these restrictions are present because non-local exits require a fair amount of magic on the part of the C compiler and can interact with other parts of the language in strange ways.

The `setjmp` function is actually a macro without an actual function definition, so you shouldn’t try to ‘`#undef`’ it or take its address. In addition, calls to `setjmp` are safe in only the following contexts:

- As the test expression of a selection or iteration statement (such as ‘`if`’, ‘`switch`’, or ‘`while`’).
- As one operand of an equality or comparison operator that appears as the test expression of a selection or iteration statement. The other operand must be an integer constant expression.
- As the operand of a unary ‘`!`’ operator, that appears as the test expression of a selection or iteration statement.
- By itself as an expression statement.

Return points are valid only during the dynamic extent of the function that called `setjmp` to establish them. If you `longjmp` to a return point that was established in a function that has already returned, unpredictable and disastrous things are likely to happen.

You should use a nonzero value argument to `longjmp`. While `longjmp` refuses to pass back a zero argument as the return value from `setjmp`, this is intended as a safety net against accidental misuse and is not really good programming style.

When you perform a non-local exit, accessible objects generally retain whatever values they had at the time `longjmp` was called. The exception is that the values of automatic variables local to the function containing the `setjmp` call that have been changed since the call to `setjmp` are indeterminate, unless you have declared them `volatile`.