exception_dispatcher(3)exception_dispatcher(3)NAME
exception_dispatcher, exc_raise_signal_exception, exc_dispatch_excep‐
tion, exc_raise_exception, exc_raise_status_exception - routines to
search and call handlers for exceptions.
SYNOPSIS
#include <excpt.h>
void exception_dispatcher(
unsigned long exception,
unsigned long code,
PCONTEXT scp ); 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_sta‐
tus_exception(
unsigned long sts );
LIBRARY
Exception Handling Library (libexc.a)
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 sig‐
context (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).
The exception_dispatcher() routine, a libexc interface, directly sets
the ExceptionCode field in an exceptionRecord to the exception argument
and calls exc_dispatch_exception().
The exc_raise_signal_exception() routine applies the EXC_VALUE(EXC_SIG‐
NAL,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).
The exc_raise_status_exception() and exc_raise_exception() routines are
typically called before a context exists and are thus not used as han‐
dlers.
The exc_raise_status_exception() routine sets the ExceptionCode in the
exceptionRecord to the sts argument, marks the exception as noncontinu‐
able (because the exception context points at exc_raise_status_excep‐
tion), and calls exc_raise_exception().
The exc_raise_exception() routine 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 con‐
text). Finally, it calls exc_dispatch_exception(). If exc_dis‐
patch_exception() returns, exc_raise_exception() calls exc_unwind(3) to
cause an exit unwind. The exit unwind eventually results in the execu‐
tion of __exc_last_chance(3).
The exc_dispatch_exception() routine 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 contex‐
tRecord 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 func‐
tion has an exception handler, the dispatcher calls it. If the handler
does not handle the exception, the dispatcher then calls exc_vir‐
tual_unwind(3) to unwind to the next frame and examines it.
If, during this process, the dispatcher encounters an error, the dis‐
patcher 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 dis‐
patcher to unwind to the next frame to continue its search for a han‐
dler. If the disposition ExceptionContinueExecution is returned, execu‐
tion continues from the context of the exception.
RETURN VALUES
If the dispatcher does not find a handler to handle the exception,
these functions return EXC_FALSE.
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 fil‐
ter 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 sigac‐
tion 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");
}
}
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
SEE ALSO
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.
exception_dispatcher(3)