setjmp.h

Go to the documentation of this file.

/*--------------------------------------------------------
 * /
 * / apeNEXT setjmp functions for nlcc
 * /
 * / $Id: setjmp.h,v 1.14 2005/10/27 20:04:45 morinl Exp $
 * /
 * / ISO/IEC 9899:1999 (E) Standard
 * / ctype  <setjmp.h>
 * /
 * / IMPLEMENTATION for APEnext: possible?         (setjmp.h)
 * /---------------------------------------------------------------------------------------------*/

#ifndef _SETJMP_H
#define _SETJMP_H

#include <nlibc.h>

/*------------------------------------------------------------------------------------------------
 * / NAME   
 * /           setjmp.h - stack environment declarations 
 * / 
 * / SYNOPSIS
 * /           #include <setjmp.h>
 * / 
 * / DESCRIPTION
 * /           The <setjmp.h> header contains the type definitions for array 
 * /           types jmp_buf and sigjmp_buf. 
 * /
 * / RETURN VALUE
 * /           
 * / 
 * / Notes
 * /           
 * / 
 * / IMPLEMENTATION for APEnext:  possible         (setjmp.h) 
 * / --------------------------------------------------------------------------------------------*/


/*---------------------------------------------------------------------------------------------
     This header file is useful for dealing with errors and interrupts
     encountered in a low-level subroutine of a program.

     All varieties of setjmp save their stack environment in env for later use by all 
     varieties of longjmp.  If the return is from a direct invocation, all
     setjmps return the value 0. If the return is from a call to any of the
     longjmps, all setjmp routines return a nonzero value.

     All longjmps restore the environment saved by the last call of setjmp
     with the corresponding env argument.  After the longjmp is completed,
     program execution continues as if the corresponding call of setjmp (which
     must not itself have returned in the interim) had just returned the value
     val.  longjmps cannot cause setjmps to return the value 0.  If a longjmp
     is invoked with a second argument of 0, all versions of setjmp will
     return 1.  At the time of the second return from a setjmp, external and
     static variables have values as of the time longjmp is called (see
     example).  The values of register and automatic variables are undefined.
     Register or automatic variables whose value must be relied upon must be
     declared as volatile.

     Example:
     #include <setjmp.h>
     jmp_buf env;
     int i = 0;
     main ()
     {    if (setjmp(env) != 0) {
          (void) printf("2nd return from setjmp: i = %d\n", i);
          exit(0);
         }
         (void) printf("1st return from setjmp: i = %d\n", i);
         i = 1;
         g(); // NOTREACHED
     }
     g()
     {         longjmp(env, 1);  // NOTREACHED
     }

     The program's output is:
          1st return from setjmp: i = 0
          2nd return from setjmp: i = 1

     Another example:
          #include<setjmp.h>
          #include<stdio.h>
          void some_function(jmp_buf);
          int main(void)
          {
          int value;
          jmp_buf environment_buffer;

          value=setjmp(environment_buffer);
          if(value!=0)
          {  printf("Reached this point from a longjmp with value=%d.\n",value);  exit(0);  }
          printf("Calling function.\n");
          some_function(environment_buffer);
          return 0;
          }
          void some_function(jmp_buf env_buf)
          { longjmp(env_buf,5); }

          The output from this program should be:
          Calling function.
          Reached this point from a longjmp with value=5.

*/

/*------------------------------------------------------------------------------------------------
 * / NAME   
 * /           jmp_buf - typedef
 * / 
 * / SYNOPSIS
 * /           #include <setjmp.h>
 * /
 * /           typedef a-type jmp_buf 
 * / 
 * / DESCRIPTION
 * /           This type is the array type a-type of an object that you declare to hold the 
 * /           context information stored by setjmp (browse below) and accessed by longjmp.  
 * /
 * / RETURN VALUE
 * /           
 * / 
 * / Notes
 * /           
 * / 
 * / IMPLEMENTATION for APEnext:  possible         (jump_buf) 
 * / --------------------------------------------------------------------------------------------*/
typedef int jmp_buf[2];

/*------------------------------------------------------------------------------------------------
 * / NAME     
 * /           setjmp - set jump point for a non-local goto 
 * /  
 * / SYNOPSIS
 * /           #include <setjmp.h>
 * /
 * /           int setjmp(jmp_buf env)
 * / 
 * / DESCRIPTION
 * /            Saves the environment into the variable environment. 
 * / 
 * / RETURN VALUE
 * /           Non-zero when  the point in the sourcecode was reached by a longjmp
 * /           Zero indicating the environment  has been saved
 * / 
 * / Notes
 * /           
 * / 
 * / IMPLEMENTATION for APEnext:  possible         (setjmp) 
 * / --------------------------------------------------------------------------------------------*/
#ifndef __HAS_MAIN
extern int setjmp(jmp_buf env);
#else
#if defined(_uses_setjmp_setjmp_h) || !defined(__cflow_processed)
int setjmp(jmp_buf env)
{
  return -1;
}
#endif
#endif // Has Main


/*------------------------------------------------------------------------------------------------
 * / NAME   
 * /           longjmp - environment restored
 * / 
 * / SYNOPSIS
 * /           #include <setjmp.h>
 * /
 * /           void longjmp(jmp_buf env, int val) 
 * / 
 * / DESCRIPTION
 * /           longjmp() function causes the environment to be restored from a setjmp call 
 * /           where the environment variable had been saved. It causes execution to goto 
 * /           the setjmp location as if setjmp had returned the value of the variable value. 
 * /           The variable value cannot be zero. However, if zero is passed, then 1 is replaced. 
 * /           If the function where setjmp was called has terminated, then the results are undefined. 
 * / 
 * / RETURN VALUE
 * /           None
 * / 
 * / Notes
 * /           
 * / 
 * / IMPLEMENTATION for APEnext:  possible?         (longjmp) 
 * / --------------------------------------------------------------------------------------------*/
#ifndef __HAS_MAIN
extern void longjmp(jmp_buf env, int val);
#else
#if defined(_uses_longjmp_setjmp_h) || !defined(__cflow_processed)
void longjmp(jmp_buf env, int val)
{
}
#endif // longjmp
#endif // Has Main

#endif /* ifndef _SETJMP_H  */

---