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.

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_status_exception(
	  unsigned long sts );

LIBRARY
  Exception Handling Library (libexc.a)

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

  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_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).

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

  The exc_raise_status_exception() routine 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().

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

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

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 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");
	    }
	}

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.

Index for Section 3

Alphabetical listing for E

Top of page