AVR Libc Home Page | AVR Libc Development Pages | ||||
Main Page | User Manual | Library Reference | FAQ | Alphabetical Index | Example Projects |
00001 /* Copyright (c) 2002,2007 Marek Michalkiewicz 00002 All rights reserved. 00003 00004 Redistribution and use in source and binary forms, with or without 00005 modification, are permitted provided that the following conditions are met: 00006 00007 * Redistributions of source code must retain the above copyright 00008 notice, this list of conditions and the following disclaimer. 00009 00010 * Redistributions in binary form must reproduce the above copyright 00011 notice, this list of conditions and the following disclaimer in 00012 the documentation and/or other materials provided with the 00013 distribution. 00014 00015 * Neither the name of the copyright holders nor the names of 00016 contributors may be used to endorse or promote products derived 00017 from this software without specific prior written permission. 00018 00019 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 00020 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00021 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00022 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 00023 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 00024 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 00025 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 00026 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 00027 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 00028 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 00029 POSSIBILITY OF SUCH DAMAGE. */ 00030 00031 /* $Id: setjmp.h 1656 2008-03-24 11:29:55Z dmix $ */ 00032 00033 #ifndef __SETJMP_H_ 00034 #define __SETJMP_H_ 1 00035 00036 #ifdef __cplusplus 00037 extern "C" { 00038 #endif 00039 00040 /* 00041 jmp_buf: 00042 offset size description 00043 0 16 call-saved registers (r2-r17) 00044 16 2 frame pointer (r29:r28) 00045 18 2 stack pointer (SPH:SPL) 00046 20 1 status register (SREG) 00047 21 2/3 return address (PC) (2 bytes used for <=128Kw flash) 00048 23/24 = total size 00049 */ 00050 00051 #if !defined(__DOXYGEN__) 00052 00053 #if defined(__AVR_3_BYTE_PC__) && __AVR_3_BYTE_PC__ 00054 # define _JBLEN 24 00055 #else 00056 # define _JBLEN 23 00057 #endif 00058 typedef struct _jmp_buf { unsigned char _jb[_JBLEN]; } jmp_buf[1]; 00059 00060 #endif /* not __DOXYGEN__ */ 00061 00062 /** \file */ 00063 /** \defgroup setjmp <setjmp.h>: Non-local goto 00064 00065 While the C language has the dreaded \c goto statement, it can only be 00066 used to jump to a label in the same (local) function. In order to jump 00067 directly to another (non-local) function, the C library provides the 00068 setjmp() and longjmp() functions. setjmp() and longjmp() are useful for 00069 dealing with errors and interrupts encountered in a low-level subroutine 00070 of a program. 00071 00072 \note setjmp() and longjmp() make programs hard to understand and maintain. 00073 If possible, an alternative should be used. 00074 00075 \note longjmp() can destroy changes made to global register 00076 variables (see \ref faq_regbind). 00077 00078 For a very detailed discussion of setjmp()/longjmp(), see Chapter 7 of 00079 <em>Advanced Programming in the UNIX Environment</em>, by W. Richard 00080 Stevens. 00081 00082 Example: 00083 00084 \code 00085 #include <setjmp.h> 00086 00087 jmp_buf env; 00088 00089 int main (void) 00090 { 00091 if (setjmp (env)) 00092 { 00093 ... handle error ... 00094 } 00095 00096 while (1) 00097 { 00098 ... main processing loop which calls foo() some where ... 00099 } 00100 } 00101 00102 ... 00103 00104 void foo (void) 00105 { 00106 ... blah, blah, blah ... 00107 00108 if (err) 00109 { 00110 longjmp (env, 1); 00111 } 00112 } 00113 \endcode */ 00114 00115 #ifndef __ATTR_NORETURN__ 00116 #define __ATTR_NORETURN__ __attribute__((__noreturn__)) 00117 #endif 00118 00119 /** \ingroup setjmp 00120 \brief Save stack context for non-local goto. 00121 00122 \code #include <setjmp.h>\endcode 00123 00124 setjmp() saves the stack context/environment in \e __jmpb for later use by 00125 longjmp(). The stack context will be invalidated if the function which 00126 called setjmp() returns. 00127 00128 \param __jmpb Variable of type \c jmp_buf which holds the stack 00129 information such that the environment can be restored. 00130 00131 \returns setjmp() returns 0 if returning directly, and 00132 non-zero when returning from longjmp() using the saved context. */ 00133 00134 extern int setjmp(jmp_buf __jmpb); 00135 00136 /** \ingroup setjmp 00137 \brief Non-local jump to a saved stack context. 00138 00139 \code #include <setjmp.h>\endcode 00140 00141 longjmp() restores the environment saved by the last call of setjmp() with 00142 the corresponding \e __jmpb argument. After longjmp() is completed, 00143 program execution continues as if the corresponding call of setjmp() had 00144 just returned the value \e __ret. 00145 00146 \note longjmp() cannot cause 0 to be returned. If longjmp() is invoked 00147 with a second argument of 0, 1 will be returned instead. 00148 00149 \param __jmpb Information saved by a previous call to setjmp(). 00150 \param __ret Value to return to the caller of setjmp(). 00151 00152 \returns This function never returns. */ 00153 00154 extern void longjmp(jmp_buf __jmpb, int __ret) __ATTR_NORETURN__; 00155 00156 #ifdef __cplusplus 00157 } 00158 #endif 00159 00160 #endif /* !__SETJMP_H_ */