1.3 Throwing an Exception

_Unwind_RaiseException

           _Unwind_Reason_Code _Unwind_RaiseException	      ( struct _Unwind_Exception *exception_object );
      

Raise an exception, passing along the given exception object, which should have its exception_class and exception_cleanup fields set. The exception object has been allocated by the language-specific runtime, and has a language-specific format, except that it must contain an _Unwind_Exception struct (see Exception Header above). _Unwind_RaiseException does not return, unless an error condition is found (such as no handler for the exception, bad stack format, etc.). In such a case, an _Unwind_Reason_Code value is returned. Possibilities are:

• _URC_END_OF_STACK : The unwinder encountered the end of the stack during phase 1, without finding a handler. The unwind runtime will not have modified the stack. The C++ runtime will normally call uncaught_exception() in this case.

• _URC_FATAL_PHASE1_ERROR : The unwinder encountered an unexpected error during phase 1, e.g. stack corruption. The unwind runtime will not have modified the stack. The C++ runtime will normally call terminate() in this case.

If the unwinder encounters an unexpected error during phase 2, it should return _URC_FATAL_PHASE2_ERROR to its caller. In C++, this will usually be __cxa_throw , which will call terminate() .

The unwind runtime will likely have modified the stack (e.g. popped frames from it) or register context, or landing pad code may have corrupted them. As a result, the the caller of _Unwind_RaiseException can make no assumptions about the state of its stack or registers.

_Unwind_ForcedUnwind

            typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)		(int version,		 _Unwind_Action actions,		 uint64 exceptionClass,		 struct _Unwind_Exception *exceptionObject,		 struct _Unwind_Context *context,		 void *stop_parameter );    _Unwind_Reason_Code _Unwind_ForcedUnwind	      ( struct _Unwind_Exception *exception_object,		_Unwind_Stop_Fn stop,		void *stop_parameter );
      

Raise an exception for forced unwinding, passing along the given exception object, which should have its exception_class and exception_cleanup fields set. The exception object has been allocated by the language-specific runtime, and has a language-specific format, except that it must contain an _Unwind_Exception struct (see Exception Header above).

Forced unwinding is a single-phase process (phase 2 of the normal exception-handling process). The stop and stop_parameter parameters control the termination of the unwind process, instead of the usual personality routine query. The stop function parameter is called for each unwind frame, with the parameters described for the usual personality routine below, plus an additional stop_parameter .

When the stop function identifies the destination frame, it transfers control (according to its own, unspecified, conventions) to the user code as appropriate without returning, normally after calling _Unwind_DeleteException . If not, it should return an _Unwind_Reason_Code value as follows:

• _URC_NO_REASON : This is not the destination frame. The unwind runtime will call the frame's personality routine with the _UA_FORCE_UNWIND and _UA_CLEANUP_PHASE flags set in actions , and then unwind to the next frame and call the stop function again.

• _URC_END_OF_STACK : In order to allow _Unwind_ForcedUnwind to perform special processing when it reaches the end of the stack, the unwind runtime will call it after the last frame is rejected, with a NULL stack pointer in the context, and the stop function must catch this condition (i.e. by noticing the NULL stack pointer). It may return this reason code if it cannot handle end-of-stack.

• _URC_FATAL_PHASE2_ERROR : The stop function may return this code for other fatal conditions, e.g. stack corruption.

Example: longjmp_unwind()

The expected implementation of longjmp_unwind() is as follows. The setjmp() routine will have saved the state to be restored in its customary place, including the frame pointer. The longjmp_unwind() routine will call _Unwind_ForcedUnwind with a stop function that compares the frame pointer in the context record with the saved frame pointer. If equal, it will restore the setjmp() state as customary, and otherwise it will return _URC_NO_REASON or _URC_END_OF_STACK .

If a future requirement for two-phase forced unwinding were identified, an alternate routine could be defined to request it, and an actions parameter flag defined to support it.

_Unwind_Resume

            void _Unwind_Resume (struct _Unwind_Exception *exception_object);
      

Resume propagation of an existing exception e.g. after executing cleanup code in a partially unwound stack. A call to this routine is inserted at the end of a landing pad that performed cleanup, but did not resume normal execution. It causes unwinding to proceed further.

_Unwind_Resume should not be used to implement rethrowing. To the unwinding runtime, the catch code that rethrows was a handler, and the previous unwinding session was terminated before entering it. Rethrowing is implemented by calling _Unwind_RaiseException again with the same exception object.

This is the only routine in the unwind library which is expected to be called directly by generated code: it will be called at the end of a landing pad in a "landing-pad" model.

1.4 Exception Object Management

_Unwind_DeleteException

            void _Unwind_DeleteException	      (struct _Unwind_Exception *exception_object);
      

Deletes the given exception object. If a given runtime resumes normal execution after catching a foreign exception, it will not know how to delete that exception. Such an exception will be deleted by calling _Unwind_DeleteException . This is a convenience function that calls the function pointed to by the exception_cleanup field of the exception header.

1.5 Context Management

_Unwind_GetGR

            uint64 _Unwind_GetGR	    (struct _Unwind_Context *context, int index);
      

This function returns the 64-bit value of the given general register. The register is identified by its index: 0 to 31 are for the fixed registers, and 32 to 127 are for the stacked registers.

During the two phases of unwinding, only GR1 has a guaranteed value, which is the Global Pointer (GP) of the frame referenced by the unwind context. If the register has its NAT bit set, the behaviour is unspecified.

_Unwind_SetGR

            void _Unwind_SetGR	  (struct _Unwind_Context *context,	   int index,	   uint64 new_value);
      

This function sets the 64-bit value of the given register, identified by its index as for _Unwind_GetGR . The NAT bit of the given register is reset.

The behaviour is guaranteed only if the function is called during phase 2 of unwinding, and applied to an unwind context representing a handler frame, for which the personality routine will return _URC_INSTALL_CONTEXT . In that case, only registers GR15, GR16, GR17, GR18 should be used. These scratch registers are reserved for passing arguments between the personality routine and the landing pads.

_Unwind_GetIP

            uint64 _Unwind_GetIP	    (struct _Unwind_Context *context);
      

This function returns the 64-bit value of the instruction pointer (IP).

During unwinding, the value is guaranteed to be the address of the bundle immediately following the call site in the function identified by the unwind context. This value may be outside of the procedure fragment for a function call that is known to not return (such as _Unwind_Resume ).

_Unwind_SetIP

            void _Unwind_SetIP	    (struct _Unwind_Context *context,	     uint64 new_value);
      

This function sets the value of the instruction pointer (IP) for the routine identified by the unwind context.

The behaviour is guaranteed only when this function is called for an unwind context representing a handler frame, for which the personality routine will return _URC_INSTALL_CONTEXT . In this case, control will be transferred to the given address, which should be the address of a landing pad.

_Unwind_GetLanguageSpecificData

            uint64 _Unwind_GetLanguageSpecificData	    (struct _Unwind_Context *context);
      

This routine returns the address of the language-specific data area for the current stack frame.

This routine is not stricly required: it could be accessed through _Unwind_GetIP using the documented format of the UnwindInfoBlock , but since this work has been done for finding the personality routine in the first place, it makes sense to cache the result in the context. We could also pass it as an argument to the personality routine.

_Unwind_GetRegionStart

            uint64 _Unwind_GetRegionStart	    (struct _Unwind_Context *context);
      

This routine returns the address of the beginning of the procedure or code fragment described by the current unwind descriptor block.

This information is required to access any data stored relative to the beginning of the procedure fragment. For instance, a call site table might be stored relative to the beginning of the procedure fragment that contains the calls. During unwinding, the function returns the start of the procedure fragment containing the call site in the current stack frame.

1.6 Personality Routine

        	throw X;
      

        	// Allocate -- never throws:	temp1 = __cxa_allocate_exception(sizeof(X));	// Construct the exception object:	#if COPY_ELISION	  [evaluate X into temp1]	#else	  [evaluate X into temp2]	  
        
          copy-constructor
        
        (temp1, temp2)	  // Landing Pad L1 if this throws	#endif	// Pass the exception object to unwind library:	__cxa_throw(temp1, type_info<x>, destructor<x>); // Never returns	// Landing pad for copy constructor:	L1: __cxa_free_exception(temp1) // never throws</x></x>
      

          extern "C" void __cxa_bad_cast ();
        

          extern "C" void __cxa_bad_typeid ();