<refentry id="longjmp">
<refnamediv>
<refname>Longjmp</refname>
<refname>Setjmp</refname>
<refpurpose>jump to another function</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;setjmp.h&gt;
</funcsynopsisinfo>
<funcprototype>
  <funcdef><function>setjmp</function></funcdef>
  <paramdef>jmp_buf <parameter>env</parameter></paramdef>
</funcprototype>

<funcprototype>
  <funcdef><function>longjmp</function></funcdef>
  <paramdef>jmp_buf <parameter>env</parameter></paramdef>
  <paramdef>int <parameter>val</parameter></paramdef>
</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
These functions allow the return of program control directly to
a higher level function. They are most useful when dealing
with errors and interrupts encountered in a low level routine.
</para>
<para>
"Goto" in C has scope only in the function in which it is
used; i.e. the label which is the object of a "goto" may only
be in the same function. Control can only be transferred
elsewhere by means of the function call, which, of course
returns to the caller. In certain abnormal situations a
programmer would prefer to be able to start some section of
code again, but this would mean returning up a ladder of
function calls with error indications all the way.
</para>
<para>
Setjmp is used to "mark" a point in the program where a
subsequent longjmp can reach. It places in the buffer, defined
in the header file, enough information for longjmp to restore
the environment to that existing at the relevant call to
setjmp.
</para>
<para>
Longjmp is called with the environment buffer as an argument
and also, a value which can be used by the caller of setjmp as,
perhaps, an error status.
</para>
<para>
To set the system up, a function will call setjmp to set up the
buffer, and if the returned value is zero, the program will
know that the call was the "first time through". If, however,
the returned value is non-zero, it must be a longjmp returning
from some deeper level of the program.
</para>
<para>
NOTE that the function calling setjmp must <emphasis>not have returned</emphasis>
at the time of calling longjmp, and the environment buffer must
be declared <emphasis>globally</emphasis>.
</para>
</refsect1>
</refentry>