StdLib/Include/setjmp.h

   1 /** @file
   2     This file defines the macro setjmp, and declares the function longjmp
   3     and the type jmp_buf, for bypassing the normal function call and return discipline.
   4
   5     Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
   6     This program and the accompanying materials are licensed and made available under
   7     the terms and conditions of the BSD License that accompanies this distribution.
   8     The full text of the license may be found at
   9     http://opensource.org/licenses/bsd-license.
  10
  11     THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12     WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13 **/
  14 #ifndef _SETJMP_H
  15 #define _SETJMP_H
  16 #include  <Library/BaseLib.h>
  17 #include  <sys/EfiCdefs.h>
  18
  19 /** jmp_buf is an array type suitable for holding the information needed to
  20     restore a calling environment. The environment of a call to the setjmp
  21     macro consists of information sufficient for a call to the longjmp function
  22     to return execution to the correct block and invocation of that block, were
  23     it called recursively. It does not include the state of the floating-point
  24     status flags, of open files, or of any other component of the abstract
  25     machine.
  26 **/
  27 typedef BASE_LIBRARY_JUMP_BUFFER jmp_buf[1];
  28
  29 /** The setjmp macro saves its calling environment in its jmp_buf argument for
  30     later use by the longjmp function.
  31
  32     The Standard does not specify whether setjmp is a macro or an identifier
  33     declared with external linkage. If a macro definition is suppressed in
  34     order to access an actual function, or a program defines an external
  35     identifier with the name setjmp, the behavior is undefined by the Standard.
  36
  37     @param[in,out]  env   A jmp_buf type object into which
  38                           the current environment is stored.
  39
  40     @return   If the return is from a direct invocation, the setjmp macro
  41     returns the value zero. If the return is from a call to the longjmp
  42     function, the setjmp macro returns a nonzero value based upon the value
  43     of the second argument to the longjmp function.
  44 **/
  45 #define setjmp(env)   (INTN)SetJump((env))
  46
  47 /** The longjmp function restores the environment saved by the most recent
  48     invocation of the setjmp macro in the same invocation of the program with
  49     the corresponding jmp_buf argument. If there has been no such invocation,
  50     or if the function containing the invocation of the setjmp macro has
  51     terminated execution in the interim, or if the invocation of the setjmp
  52     macro was within the scope of an identifier with variably modified type and
  53     execution has left that scope in the interim, the behavior is undefined.
  54
  55     @param[in]    env     The jump buffer containing the environment to be returned to.
  56     @param[in]    val     A non-zero value to be returned from setjmp.
  57
  58     @return     After longjmp is completed, program execution continues as if the
  59     corresponding invocation of the setjmp macro had just returned the value
  60     specified by val. The longjmp function cannot cause the setjmp macro to
  61     return the value 0; if val is 0, the setjmp macro returns the value 1.
  62 **/
  63 extern void longjmp(jmp_buf env, int val);
  64
  65 #endif  /* _SETJMP_H */