You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
154 lines
9.9 KiB
HTML
154 lines
9.9 KiB
HTML
15 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
|
||
|
|
<title>avr-libc: <setjmp.h>: Non-local goto</title>
|
||
|
|
<link href="dox.css" rel="stylesheet" type="text/css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<center>
|
||
|
|
<table width="80%">
|
||
|
|
<tr>
|
||
|
|
<td align="left"><a href="http://www.nongnu.org/avr-libc/">AVR Libc Home Page</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/">AVR Libc Development Pages</a></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td align="center" width="13%"><a href="index.html">Main Page</a></td>
|
||
|
|
<td align="center" width="13%"><a href="pages.html">User Manual</a></td>
|
||
|
|
<td align="center" width="13%"><a href="modules.html">Library Reference</a></td>
|
||
|
|
<td align="center" width="13%"><a href="FAQ.html">FAQ</a></td>
|
||
|
|
<td align="center" width="13%"><a href="globals.html">Alphabetical Index</a></td>
|
||
|
|
<td align="center" width="13%"><a href="group__demos.html">Example Projects</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
<hr width="80%">
|
||
|
|
<!-- Generated by Doxygen 1.5.6 -->
|
||
|
|
<div class="contents">
|
||
|
|
<h1><setjmp.h>: Non-local goto</h1><hr><a name="_details"></a><h2>Detailed Description</h2>
|
||
|
|
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#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> and <a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> functions. <a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> and <a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf" 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" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> and <a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf" 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.<p>
|
||
|
|
<a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf" 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>
|
||
|
|
For a very detailed discussion of <a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" 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>
|
||
|
|
Example:<p>
|
||
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <<a class="code" href="setjmp_8h.html">setjmp.h</a>></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#g2687c5ef7a3f376db90908999a9a7fc6" 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#g87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp</a> (env, 1);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
<p>
|
||
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
||
|
|
<tr><td></td></tr>
|
||
|
|
<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
|
||
|
|
<tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6">setjmp</a> (jmp_buf __jmpb)</td></tr>
|
||
|
|
|
||
|
|
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf">longjmp</a> (jmp_buf __jmpb, int __ret) __ATTR_NORETURN__</td></tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<hr><h2>Function Documentation</h2>
|
||
|
|
<a class="anchor" name="g87f44eafaab5ec0ef8f5a11a8b853acf"></a><!-- doxytag: member="setjmp.h::longjmp" ref="g87f44eafaab5ec0ef8f5a11a8b853acf" 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 </td>
|
||
|
|
<td class="paramname"> <em>__jmpb</em>, </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="paramkey"></td>
|
||
|
|
<td></td>
|
||
|
|
<td class="paramtype">int </td>
|
||
|
|
<td class="paramname"> <em>__ret</em></td><td> </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 <<a class="code" href="setjmp_8h.html">setjmp.h</a>></span>
|
||
|
|
</pre></div><p>
|
||
|
|
<a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf" 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#g2687c5ef7a3f376db90908999a9a7fc6" 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#g87f44eafaab5ec0ef8f5a11a8b853acf" 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#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> had just returned the value <em>__ret</em>.<p>
|
||
|
|
<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__setjmp.html#g87f44eafaab5ec0ef8f5a11a8b853acf" 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#g87f44eafaab5ec0ef8f5a11a8b853acf" 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 compact><dt><b>Parameters:</b></dt><dd>
|
||
|
|
<table border="0" cellspacing="2" cellpadding="0">
|
||
|
|
<tr><td valign="top"></td><td valign="top"><em>__jmpb</em> </td><td>Information saved by a previous call to <a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a>. </td></tr>
|
||
|
|
<tr><td valign="top"></td><td valign="top"><em>__ret</em> </td><td>Value to return to the caller of <a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a>.</td></tr>
|
||
|
|
</table>
|
||
|
|
</dl>
|
||
|
|
<dl class="return" compact><dt><b>Returns:</b></dt><dd>This function never returns. </dd></dl>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div><p>
|
||
|
|
<a class="anchor" name="g2687c5ef7a3f376db90908999a9a7fc6"></a><!-- doxytag: member="setjmp.h::setjmp" ref="g2687c5ef7a3f376db90908999a9a7fc6" 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 </td>
|
||
|
|
<td class="paramname"> <em>__jmpb</em> </td>
|
||
|
|
<td> ) </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 <<a class="code" href="setjmp_8h.html">setjmp.h</a>></span>
|
||
|
|
</pre></div><p>
|
||
|
|
<a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" 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#g87f44eafaab5ec0ef8f5a11a8b853acf" 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#g2687c5ef7a3f376db90908999a9a7fc6" title="Save stack context for non-local goto.">setjmp()</a> returns.<p>
|
||
|
|
<dl compact><dt><b>Parameters:</b></dt><dd>
|
||
|
|
<table border="0" cellspacing="2" cellpadding="0">
|
||
|
|
<tr><td valign="top"></td><td valign="top"><em>__jmpb</em> </td><td>Variable of type <code>jmp_buf</code> which holds the stack information such that the environment can be restored.</td></tr>
|
||
|
|
</table>
|
||
|
|
</dl>
|
||
|
|
<dl class="return" compact><dt><b>Returns:</b></dt><dd><a class="el" href="group__setjmp.html#g2687c5ef7a3f376db90908999a9a7fc6" 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#g87f44eafaab5ec0ef8f5a11a8b853acf" title="Non-local jump to a saved stack context.">longjmp()</a> using the saved context. </dd></dl>
|
||
|
|
|
||
|
|
</div>
|
||
|
|
</div><p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<hr width="80%">
|
||
|
|
<p><center>Automatically generated by Doxygen 1.5.6 on 4 Dec 2008.</center></p>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|