GNU Info

(libc.info)Non-Local Details

---

Next: Non-Local Exits and Signals Prev: Non-Local Intro Up: Non-Local Exits

---

Enter node , (file) or (file)node

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