exception_dispatcher(3) Library Functions Manual exception_dispatcher(3)
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 con-
text. 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 excep-
tion. See excpt(4) and the Calling Standard for Alpha Systems for a detailed description of the structures that contain exception informa-
tion 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 han-
dler. 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 excep-
tion dispatcher, which causes the exception filter to execute. The filter returns a 1 to the dispatcher, resulting in the handler execut-
ing 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
");
}
except(1)
{ printf("exception raised correctly
");
}
}
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), sig-
nal(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
exception_dispatcher(3)