Provided by: avr-libc_1.2.3-3_all bug


       Setjmp and Longjmp -

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.

           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.


           #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);

       int setjmp (jmp_buf __jmpb)
       void longjmp (jmp_buf __jmpb, int __ret) __ATTR_NORETURN__

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.

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

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

           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.

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

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