AVR Libc Home Page 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
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_8h_source.html,v 1.1.1.4 2012/01/03 16:04:22 joerg_wunsch Exp$ */
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
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().