Index for Section 3

Alphabetical listing for E

Bottom of page

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
  exception Address of primary exception record.

  code	    Exception code.

  scp	    Pointer to a struct sigcontext (see signal(2)) used to represent
	    a procedure's context.

  exceptionRecord
	    Address of primary exception record.

  contextRecord
	    Pointer to a struct sigcontext (see signal(2)) used to represent
	    a procedure's context.

  sts	    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.

Index for Section 3

Alphabetical listing for E

Top of page