*** UNIX MANUAL PAGE BROWSER ***

exception_dispatcher(3) Library Functions Manual 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. 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_ex- ception( unsigned long exception, unsigned long code, PCONTEXT scp); unsigned long exc_dis- patch_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 sig- context (see signal(2)) used to represent a procedure's context. Ex- ception 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 ex- plicitly 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 Exception- Code 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 exception- Record to the sts argument, marks the exception as noncontinuable (be- cause 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 excep- tionRecord argument. It uses its caller's context as the exception con- text, 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 un- aligned), 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 han- dler 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 re- turn 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. EXAMPLES In the following example, exc_raise_signal_exception is installed as the signal handler for SIGFPE and SIGSEGV. When the divide-by-zero oc- curs, 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 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"); } } 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/in- clude/excpt.h - include file usr/include/pdsc.h - include file usr/in- clude/signal.h - include file usr/include/machine/fpu.h - include file RELATED INFORMATION Functions: exception_intro(3), exc_lookup_function_entry(3), exc_un- wind(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)