oracular (3) setjmp.3avr.gz

NAME

       setjmp - <setjmp.h>: Non-local goto

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) [extern]
       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) [extern]
       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.