NAME

       setjmp

SYNOPSIS

   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.

Author

       Generated automatically by Doxygen for avr-libc from the source code.