AVR Libc Home Page |  | AVR Libc Development Pages
Main Page | User Manual | Library Reference | FAQ | Alphabetical Index | Example Projects

# <setjmp.h>: Non-local goto

## Functions
int | setjmp (jmp_buf __jmpb)
void | longjmp (jmp_buf __jmpb, int __ret) __ATTR_NORETURN__

## Detailed Description

While the C language has the dreaded `goto` statement, it can only be used to jump to a label in the same (local) function. In order to jump directly to another (non-local) function, the C library provides the setjmp() and longjmp() functions. setjmp() and longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program.

Note:
  setjmp() and longjmp() make programs hard to understand and maintain. If possible, an alternative should be used.

  longjmp() can destroy changes made to global register variables (see How to permanently bind a variable to a register?).

For a very detailed discussion of setjmp()/longjmp(), see Chapter 7 of Advanced Programming in the UNIX Environment, by W. Richard Stevens.

Example:

        #include <setjmp.h>

        jmp_buf env;

        int main (void)
        {
            if (setjmp (env))
            {
                ... handle error ...
            }

            while (1)
            {
               ... main processing loop which calls foo() some where ...
            }
        }

        ...

        void foo (void)
        {
            ... blah, blah, blah ...

            if (err)
            {
                longjmp (env, 1);
            }
        }

## Function Documentation

void longjmp | ( | jmp_buf | __jmpb,
|  | int | __ret |
| ) |  |  |

Non-local jump to a saved stack context.

     #include <setjmp.h>

longjmp() restores the environment saved by the last call of setjmp() with the corresponding __jmpb argument. After longjmp() is completed, program execution continues as if the corresponding call of setjmp() had just returned the value __ret.

Note:
  longjmp() cannot cause 0 to be returned. If longjmp() is invoked with a second argument of 0, 1 will be returned instead.

Parameters:

  | __jmpb | Information saved by a previous call to setjmp().
  | __ret | Value to return to the caller of setjmp().

Returns:
  This function never returns.

int setjmp | ( | jmp_buf | __jmpb | ) |

Save stack context for non-local goto.

     #include <setjmp.h>

setjmp() saves the stack context/environment in __jmpb for later use by longjmp(). The stack context will be invalidated if the function which called setjmp() returns.

Parameters:

  | __jmpb | Variable of type `jmp_buf` which holds the stack information such that the environment can be restored.

Returns:
  setjmp() returns 0 if returning directly, and non-zero when returning from longjmp() using the saved context.

Automatically generated by Doxygen 1.5.7 on 6 Nov 2008.