exc_raise_exception man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

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)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net