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

avr-libc 2.0.0 Standard C library for AVR-GCC |

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

Functions
<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

## ◆ longjmp()

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.

## ◆ setjmp()

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.

setjmp.h
setjmp
int setjmp(jmp_buf __jmpb)
Save stack context for non-local goto.
longjmp
void longjmp(jmp_buf __jmpb, int __ret) __ATTR_NORETURN__
Non-local jump to a saved stack context.