AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page User Manual Reference FAQ Example Projects

setjmp.h

Go to the documentation of this file. 
01	1 Copyright (c) 2002,2007 Marek Michalkiewicz
	022All rights reserved.
	033
044Redistribution and use in source and binary forms, with or without 055modification, are permitted provided that the following conditions are met: 066 077* Redistributions of source code must retain the above copyright 088notice, this list of conditions and the following disclaimer. 099 1010* Redistributions in binary form must reproduce the above copyright 1111notice, this list of conditions and the following disclaimer in 1212the documentation and/or other materials provided with the 1313distribution. 1414 1515* Neither the name of the copyright holders nor the names of 1616contributors may be used to endorse or promote products derived 1717from this software without specific prior written permission. 1818 1919THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 2020AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 2121IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 2222ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 2323LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 2424CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 2525SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 2626INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 2727CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 2828ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 2929POSSIBILITY OF SUCH DAMAGE. */ 3030 3131/* $Id: setjmp.h 2503 2016-02-07 22:59:47Z joerg_wunsch $ */ 3232 3333#ifndef __SETJMP_H_ 3434#define __SETJMP_H_ 1 3535 3636#ifdef __cplusplus 3737extern "C" { 3838#endif 3939 4040/* 4141jmp_buf: 4242offset size description 43430 16/2 call-saved registers (r2-r17) 4444(AVR_TINY arch has only 2 call saved registers (r18,r19)) 454516/2 2 frame pointer (r29:r28) 464618/4 2 stack pointer (SPH:SPL) 474720/6 1 status register (SREG) 484821/7 2/3 return address (PC) (2 bytes used for <=128Kw flash) 494923/24/9 = total size (AVR_TINY arch always has 2 bytes PC) 5050*/ 5151 5252#if !defined(__DOXYGEN__) 5353 5454#if defined(__AVR_TINY__) 5555# define _JBLEN 9 5656#elif defined(__AVR_3_BYTE_PC__) && __AVR_3_BYTE_PC__ 5757# define _JBLEN 24 5858#else 5959# define _JBLEN 23 6060#endif 6161typedef struct _jmp_buf { unsigned char _jb[_JBLEN]; } jmp_buf[1]; 6262 6363#endif /* not __DOXYGEN__ */ 6464 6565/** \file */ 6666/** \defgroup setjmp <setjmp.h>: Non-local goto 6767 6868While the C language has the dreaded \c goto statement, it can only be 6969used to jump to a label in the same (local) function. In order to jump 7070directly to another (non-local) function, the C library provides the 7171setjmp() and longjmp() functions. setjmp() and longjmp() are useful for 7272dealing with errors and interrupts encountered in a low-level subroutine 7373of a program. 7474 7575\note setjmp() and longjmp() make programs hard to understand and maintain. 7676If possible, an alternative should be used. 7777 7878\note longjmp() can destroy changes made to global register 7979variables (see \ref faq_regbind). 8080 8181For a very detailed discussion of setjmp()/longjmp(), see Chapter 7 of 8282<em>Advanced Programming in the UNIX Environment</em>, by W. Richard 8383Stevens. 8484 8585Example: 8686 8787\code 8888#include <setjmp.h> 8989 9090jmp_buf env; 9191 9292int main (void) 9393{ 9494if (setjmp (env)) 9595{ 9696... handle error ... 9797} 9898 9999while (1) 100100{ 101101... main processing loop which calls foo() some where ... 102102} 103103} 104104 105105... 106106 107107void foo (void) 108108{ 109109... blah, blah, blah ... 110110 111111if (err) 112112{ 113113longjmp (env, 1); 114114} 115115} 116116\endcode */ 117117 118118#if !(defined(__ATTR_NORETURN__) || defined(__DOXYGEN__)) 119119#define __ATTR_NORETURN__ __attribute__((__noreturn__)) 120120#endif 121121 122122/** \ingroup setjmp 123123\brief Save stack context for non-local goto. 124124 125125\code #include <setjmp.h>\endcode 126126 127127setjmp() saves the stack context/environment in \e __jmpb for later use by 128128longjmp(). The stack context will be invalidated if the function which 129129called setjmp() returns. 130130 131131\param __jmpb Variable of type \c jmp_buf which holds the stack 132132information such that the environment can be restored. 133133 134134\returns setjmp() returns 0 if returning directly, and 135135non-zero when returning from longjmp() using the saved context. */ 136136 137137extern int setjmp(jmp_buf __jmpb); 138138 139139/** \ingroup setjmp 140140\brief Non-local jump to a saved stack context. 141141 142142\code #include <setjmp.h>\endcode 143143 144144longjmp() restores the environment saved by the last call of setjmp() with 145145the corresponding \e __jmpb argument. After longjmp() is completed, 146146program execution continues as if the corresponding call of setjmp() had 147147just returned the value \e __ret. 148148 149149\note longjmp() cannot cause 0 to be returned. If longjmp() is invoked 150150with a second argument of 0, 1 will be returned instead. 151151 152152\param __jmpb Information saved by a previous call to setjmp(). 153153\param __ret Value to return to the caller of setjmp(). 154154 155155\returns This function never returns. */ 156156 157157extern void longjmp(jmp_buf __jmpb, int __ret) __ATTR_NORETURN__; 158158 159159#ifdef __cplusplus 160160} 161161#endif 162162 163163#endif /* !__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.