<!-- HTML header for doxygen 1.8.7-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.6.3"/>
<!--BEGIN PROJECT_NAME--><title>avr-libc: avr-libc: &lt;setjmp.h&gt;: Non-local goto</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>avr-libc: &lt;setjmp.h&gt;: Non-local goto</title><!--END !PROJECT_NAME-->
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
$extrastylesheet
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->

<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <!--BEGIN PROJECT_LOGO-->
  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
  <!--END PROJECT_LOGO-->
  <!--BEGIN PROJECT_NAME-->
  <td style="padding-left: 0.5em;">
   <div id="projectname">avr-libc
   <!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">2.0.0</span><!--END PROJECT_NUMBER-->
   </div>
   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
  </td>
  <!--END PROJECT_NAME-->
  <!--BEGIN !PROJECT_NAME-->
   <!--BEGIN PROJECT_BRIEF-->
    <td style="padding-left: 0.5em;">
    <div id="projectbrief">$projectbrief</div>
    </td>
   <!--END PROJECT_BRIEF-->
  <!--END !PROJECT_NAME-->
  <!--BEGIN DISABLE_INDEX-->
   <!--BEGIN SEARCHENGINE-->
   <td>$searchbox</td>
   <!--END SEARCHENGINE-->
  <!--END DISABLE_INDEX-->
 </tr>
 </tbody>
</table>
<table>
  <tr>
    <td align="left"><a href="http://www.nongnu.org/avr-libc/"><h2>AVR Libc Home Page</h2></a></td>
    <td align="center" colspan=4><img src="avrs.png" alt="AVRs" align="middle" border="0"></td>
    <td align="right"><a href="https://savannah.nongnu.org/projects/avr-libc/"><h2>AVR Libc Development Pages</h2></a></td>
  </tr>
  <tr>
    <td align="center" width="20%"><a href="index.html"><h2>Main Page</h2></a></td>
    <td align="center" width="20%"><a href="pages.html"><h2>User Manual</h2></a></td>
    <td align="center" width="20%"><a href="modules.html"><h2>Library Reference</h2></a></td>
    <td align="center" width="20%"><a href="FAQ.html"><h2>FAQ</h2></a></td>
    <td align="center" width="20%"><a href="group__demos.html"><h2>Example Projects</h2></a></td>
  </tr>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->
<!-- Generated by Doxygen 1.6.3 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="contents">
<h1>&lt;setjmp.h&gt;: Non-local goto</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6">setjmp</a> (jmp_buf __jmpb)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf">longjmp</a> (jmp_buf __jmpb, int __ret) __ATTR_NORETURN__</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>While the C language has the dreaded <code>goto</code> 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 <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> and <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> functions. <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> and <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program.</p>
<dl class="note"><dt><b>Note:</b></dt><dd><a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> and <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> make programs hard to understand and maintain. If possible, an alternative should be used.</dd>
<dd>
<a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> can destroy changes made to global register variables (see <a class="el" href="FAQ.html#faq_regbind">How to permanently bind a variable to a register?</a>).</dd></dl>
<p>For a very detailed discussion of <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a>/longjmp(), see Chapter 7 of <em>Advanced Programming in the UNIX Environment</em>, by W. Richard Stevens.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">    #include &lt;<a class="code" href="setjmp_8h.html">setjmp.h</a>&gt;</span>

    jmp_buf env;

    <span class="keywordtype">int</span> main (<span class="keywordtype">void</span>)
    {
        <span class="keywordflow">if</span> (<a class="code" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp</a> (env))
        {
            ... handle error ...
        }

        <span class="keywordflow">while</span> (1)
        {
           ... main processing loop which calls foo() some where ...
        }
    }

    ...

    <span class="keywordtype">void</span> foo (<span class="keywordtype">void</span>)
    {
        ... blah, blah, blah ...

        <span class="keywordflow">if</span> (err)
        {
            <a class="code" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp</a> (env, 1);
        }
    }
</pre></div> <hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga87f44eafaab5ec0ef8f5a11a8b853acf"></a><!-- doxytag: member="setjmp.h::longjmp" ref="ga87f44eafaab5ec0ef8f5a11a8b853acf" args="(jmp_buf __jmpb, int __ret) __ATTR_NORETURN__" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void longjmp </td>
          <td>(</td>
          <td class="paramtype">jmp_buf&nbsp;</td>
          <td class="paramname"> <em>__jmpb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&nbsp;</td>
          <td class="paramname"> <em>__ret</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>Non-local jump to a saved stack context. </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;<a class="code" href="setjmp_8h.html">setjmp.h</a>&gt;</span>
</pre></div><p><a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> restores the environment saved by the last call of <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> with the corresponding <em>__jmpb</em> argument. After <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> is completed, program execution continues as if the corresponding call of <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> had just returned the value <em>__ret</em>.</p>
<dl class="note"><dt><b>Note:</b></dt><dd><a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> cannot cause 0 to be returned. If <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> is invoked with a second argument of 0, 1 will be returned instead.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>__jmpb</em>&nbsp;</td><td>Information saved by a previous call to <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a>. </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>__ret</em>&nbsp;</td><td>Value to return to the caller of <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a>.</td></tr>
  </table>
  </dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>This function never returns. </dd></dl>

</div>
</div>
<a class="anchor" id="ga2687c5ef7a3f376db90908999a9a7fc6"></a><!-- doxytag: member="setjmp.h::setjmp" ref="ga2687c5ef7a3f376db90908999a9a7fc6" args="(jmp_buf __jmpb)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int setjmp </td>
          <td>(</td>
          <td class="paramtype">jmp_buf&nbsp;</td>
          <td class="paramname"> <em>__jmpb</em></td>
          <td>&nbsp;)&nbsp;</td>
          <td></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>Save stack context for non-local goto. </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;<a class="code" href="setjmp_8h.html">setjmp.h</a>&gt;</span>
</pre></div><p><a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> saves the stack context/environment in <em>__jmpb</em> for later use by <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a>. The stack context will be invalidated if the function which called <a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> returns.</p>
<dl><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>__jmpb</em>&nbsp;</td><td>Variable of type <code>jmp_buf</code> which holds the stack information such that the environment can be restored.</td></tr>
  </table>
  </dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="group__setjmp.html#ga2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> returns 0 if returning directly, and non-zero when returning from <a class="el" href="group__setjmp.html#ga87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> using the saved context. </dd></dl>

</div>
</div>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&nbsp;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&nbsp;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&nbsp;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&nbsp;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&nbsp;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&nbsp;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&nbsp;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&nbsp;</span>Defines</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<!-- HTML footer for doxygen 1.8.7-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    $navpath
    <li class="footer">$generatedby
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> 1.6.3 </li>
  </ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
</a> 1.6.3
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>