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

setjmp.h

Go to the documentation of this file.
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_ */

Automatically generated by Doxygen 1.7.3 on Thu May 19 2011.