Content-type: text/html Man page of exception_dispatcher

exception_dispatcher

Section: C Library Functions (3)
Index Return to Main Contents

 

NAME

exception_dispatcher, exc_raise_signal_exception, exc_dispatch_exception, exc_raise_exception, exc_raise_status_exception - Routines to search and call handlers for exceptions.  

LIBRARY

Exception Handling Library (libexc.a)  

SYNOPSIS

#include <excpt.h> void exception_dispatcher(
                unsigned long         exception,
                unsigned long         code,
                PCONTEXT              scp); void exc_raise_signal_exception(
                unsigned long         exception,
                unsigned long         code,
                PCONTEXT              scp); unsigned long exc_dispatch_exception(
                system_exrec_type     exceptionRecord,
                PCONTEXT              contextRecord); void exc_raise_exception(
                system_exrec_type     exceptionRecord); void exc_raise_status_exception(
                unsigned long         sts);  

PARAMETERS

Address of primary exception record. Exception code. Pointer to a struct sigcontext (see signal(2)) used to represent a procedure's context. Address of primary exception record. Pointer to a struct sigcontext (see signal(2)) used to represent a procedure's context. Exception code.  

DESCRIPTION

These routines allow user and compiler generated code to initiate the exception process. Typically, programs written in the C programming language use these routines within the structured exception handling capabilities of the language, described in c_excpt(4).

The exception context is provided by structures that describe the point at which either a hardware exception occurred or a software program explicitly raised an exception (for example, a user-defined exception). The exception code is an integer that uniquely defines the exception. See excpt(4) and the Calling Standard for Alpha Systems for a detailed description of the structures that contain exception information and a discussion on how to select appropriate exception codes.

Both exception_dispatcher and exc_raise_signal_exception generate an exception context and are typically used as arguments to signal(2).

exception_dispatcher, a libexc interface, directly sets the ExceptionCode field in an exceptionRecord to the exception argument and calls exc_dispatch_exception.

exc_raise_signal_exception applies the EXC_VALUE(EXC_SIGNAL, exception) macro (described in excpt(4)) to the exception argument before calling exc_dispatch_exception. If exc_dispatch_exception returns, exc_raise_signal_exception calls exc_unwind(3) to cause an exit unwind, eventually resulting in a call to __exc_last_chance(3).

exc_raise_status_exception and exc_raise_exception are typically called before a context exists and are thus not used as handlers.

exc_raise_status_exception sets the ExceptionCode in the exceptionRecord to the sts argument, marks the exception as noncontinuable (because the exception context points at exc_raise_status_exception) and calls exc_raise_exception.

exc_raise_exception expects its caller to explicitly set up the exceptionRecord argument. It uses its caller's context as the exception context, obtaining it by calling setjmp(3) (to get its own context) and then exc_virtual_unwind(3) (to obtain its caller's context). Finally, it calls exc_dispatch_exception. If exc_dispatch_exception returns, exc_raise_exception calls exc_unwind(3) to cause an exit unwind. The exit unwind eventually results in the execution of __exc_last_chance(3).

exc_dispatch_exception attempts to dispatch an exception to a frame-based handler (see the Calling Standard for Alpha Systems and excpt(4)) by searching backwards through the stack-based call frames. The search begins with the frame specified in the contextRecord and continues backward until either a handler is found that handles the exception, the stack is found to be invalid (for example, out of limits or unaligned), or the end of the call hierarchy is reached.

As it encounters each frame, the dispatcher determines the PC where control left the corresponding function and uses it in a call to exc_lookup_function_entry(3) to obtain exception information from the run-time function table built by the linker. If the corresponding function has an exception handler, the dispatcher calls it. If the handler does not handle the exception, the dispatcher then calls exc_virtual_unwind(3) to unwind to the next frame and examines it.

If, during this process, the dispatcher encounters an error, the dispatcher raises an internal exception (see excpt(4)).

An exception handlers does not have to return. If it does, it may return one of the following dispositions:


     typedef enum _EXCEPTION_DISPOSITION {
         ExceptionContinueExecution,
         ExceptionContinueSearch,
         ExceptionNestedException,
         ExceptionCollidedUnwind
     } EXCEPTION_DISPOSITION;

All dispositions, except for ExceptionContinueExecution, cause the dispatcher to unwind to the next frame to continue its search for a handler. If the disposition ExceptionContinueExecution is returned, execution continues from the context of the exception.

 

EXAMPLES

In the following example, exc_raise_signal_exception is installed as the signal handler for SIGFPE and SIGSEGV. When the divide-by-zero occurs, exc_raise_signal_exception executes, transforming the signal into a structured exception to be processed by the C structured exception dispatcher, which causes the exception filter to execute. The filter returns a 1 to the dispatcher, resulting in the handler executing and printing the ``exception raised correctly'' message.

#include <excpt.h> #include <stdio.h> #include <signal.h> struct sigaction foo = {(void (*)(int))exc_raise_signal_exception,0,0};

double x,y=0; main()
 {
   sigaction(SIGFPE,&foo,0);
   sigaction(SIGSEGV,&foo,0);


   try
      {         x = x/y;
        printf("exception not raised\n");

      }
   except(1)
      {         printf("exception raised correctly\n");

      }
 }  

RETURN VALUES

If the dispatcher does not find a handler to handle the exception, these functions return EXC_FALSE.

 

FILES

/usr/ccs/lib/cmplrs/cc/libexc.a - exception handling library /usr/include/excpt.h - include file /usr/include/pdsc.h - include file /usr/include/signal.h - include file /usr/include/machine/fpu.h - include file

 

RELATED INFORMATION

Functions: exception_intro(3), exc_lookup_function_entry(3), exc_unwind(3), __exc_last_chance(3), ieee(3), setjmp(3), sigaction(2), signal(2).

Files: excpt(4), c_excpt(4), pdsc(4), signal(4).

Programmer's Guide.

Assembly Language Programmer's Guide.

Calling Standard for Alpha Systems. delim off


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
EXAMPLES
RETURN VALUES
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:31 GMT, October 02, 2010