unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



c_excpt(4)							   c_excpt(4)



NAME

  c_excpt.h - Header file defining structured exception	handling keywords,
  intrinsics, and structures for the C language	compiler

SYNOPSIS

  #include <&lt;excpt.h>&gt;	  /* includes c_excpt.h	*/

DESCRIPTION

  The c_excpt.h	header file defines the	keywords, intrinsic functions, and
  structures the C language compiler uses to set up a structured exception
  handler or termination handler.

  Structured Exception Handling

  The syntax for a structured exception	handler	is as follows:

       try {
	       try-body
	   }
     except (exception-filter) {
	    exception-handler
	    }

  The try-body is the code, expressed as a compound statement, that the
  exception handler protects. The try body can be a block of statements	or a
  set of nested	blocks.	 If an exception occurs	while the try body is execut-
  ing, exception handling code evaluates the exception-filter to determine
  whether to transfer control to the try body's	exception-handler, continue
  the search for a handler in some outer-level try body, or continue normal
  execution.

  A program can	explicitly initiate an application-specific exception by cal-
  ling exc_raise_exception or exc_raise_status_exception.  These functions
  allow	the calling procedure to specify information that describes the
  exception. A program can also	install	a special signal handler,
  exc_raise_signal_exception, that converts a signal to	an exception, invok-
  ing the exception dispatcher to search for any frame-based exception
  handlers that	have been established.	In this	case, the code reported	to
  the handler has EXC_SIGNAL in	its facility field and the signal value	in
  its code field.  See the Calling Standard for	Alpha Systems and the
  exception_intro(3) and its associated	reference pages	for instructions on
  how to use exception management routines.

  The exception-filter is an expression	associated with	the exception handler
  that guards a	given try body.	It can be a simple expression or can invoke a
  function that	evaluates the exception. An exception filter must evaluate to
  one of the following integral	values:

    +  < 0 (EXCEPTION_CONTINUE_EXECUTION)
       The exception dispatcher	dismisses the exception	and resumes the
       thread of execution that	was originally disrupted by the	exception.
       If the exception	is noncontinuable, the dispatcher raises a
       STATUS_NONCONTINUABLE_EXCEPTION exception.

    +  0 (EXCEPTION_CONTINUE_SEARCH)
       The exception dispatcher	continues to search for	a handler, first in
       any try...except	blocks in which	the current one	might be nested, and
       then in the try..except blocks defined in the procedure frame preced-
       ing the current frame on	the runtime stack. If a	filter chooses not to
       handle an exception, it typically returns this value.

    +  > 0 (EXCEPTION_EXECUTE_HANDLER)
       The exception dispatcher	transfers control to the exception handler,
       and execution continues in the frame on the runtime stack in which the
       handler is found. This process, known as	handling the exception,
       unwinds all procedure frames below the current frame and	causes any
       termination handlers established	within those frames to execute.

  Note that you	can use	a comma	to make	assignments within the filter expres-
  sion.	 For instance:

	    except((e=exception_code())	== EXC_VALUE(EXC_SIGNAL, SIGILL) ? 1 :
	       (printf("unexpected signal exception code 0x%lx0, e),0))
	    {
	       /* exception handler */
	    }

  Two intrinsic	functions are allowed within the exception filter to access
  information about the	exception being	filtered:

       long		   exception_code();
       Exception_info_ptr  exception_info();

  exception_code returns the exception code.  The excpt.h include file
  defines the exception	code formats supported by the operating	system.	It
  also provides	symbolic constants for the facility component of Tru64 UNIX-
  format codes,	definitions of system internal exception codes,	and a macro,
  EXC_VALUE, that allows the definition	of application-specific	exception
  codes.  See excpt(4) and the Calling Standard	for Alpha Systems for addi-
  tional discussion of exception codes.

  exception_info returns a pointer to an EXCEPTION_POINTERS structure.	Using
  this pointer,	you can	access the machine state at the	time of	the excep-
  tion.	 The exception information structure is	defined	as follows:

	    typedef struct _EXCEPTION_POINTERS {
		system_exrec_type*		       ExceptionRecord;
		PCONTEXT				 ContextRecord;
		EXCEPTION_DISPOSITION	  Disposition;
		DISPATCHER_CONTEXT	  *DispatcherContext;
	    } EXCEPTION_POINTERS, *PEXCEPTION_POINTERS,	*Exception_info_ptr;

  An exception record, as defined in the excpt.h include file, describes an
  exception.  In addition to an	exception code,	an exception record contains
  flags	that identify the circumstances	under which a handler is called	(for
  instance, whether an unwind operation	is in progress or whether the excep-
  tion is continuable).	excpt.h	defines	macros that allow a handler to test
  the value of these flags.

  A context record, also defined in excpt.h, provides information about	the
  establisher of an exception handler (such as the PC where control left the
  establisher).	 This information allows the exception dispatcher to properly
  dispatch the exception. An exception disposition is a	value returned by an
  exception handler to indicate	to the exception dispatcher whether it should
  dismiss an exception,	continue the search for	an exception handler, or per-
  form some special action. Both the context record and	exception disposition
  are discussed	in greater detail in  excpt(4) and the Calling Standard	for
  Alpha	Systems.  The calling standard also discusses the circumstances	under
  which	a handler can modify exception records and context records.

  The exception_code intrinsic function	can be used within an exception
  filter and exception handler.	The exception_info function can	only be	used
  within an exception filter.  However,	the filter can store the information
  returned by the function and make it subsequently available to the excep-
  tion handler.	 If you	need to	refer to exception structures outside of the
  filter, you must copy	them as	well since their storage is valid only during
  the execution	of the filter.

  When an exception occurs, the	exception dispatcher virtually unwinds the
  runtime stack	until it reaches a frame for which a handler has been esta-
  blished. The dispatcher initially searches for an exception handler in the
  stack	frame that was current when the	exception occurred.  If	the handler
  is not in this stack frame, the dispatcher virtually unwinds the stack (in
  its own context), leaving the	current	stack frame and	any intervening	stack
  frames intact	until it reaches a frame that has established an exception
  handler.  It then executes the exception filter associated with that
  handler.  Note that, during this phase of exception dispatching, the
  dispatcher has only virtually	unwound	the runtime stack; all call frames
  that may have	existed	on the stack at	the time of the	exception are still
  there.  If it	cannot find an exception handler, or if	all handlers reraise
  the exception, the exception dispatcher invokes the system last-chance
  handler.

  By treating the exception filter as if it were a Pascal-style	nested pro-
  cedure, exception handling code evaluates the	filter expression within the
  scope	of the procedure that includes the try...except	construct.  This
  allows the filter expression to access the local variables of	that pro-
  cedure, even though the exception may	have occurred in a different pro-
  cedure.

  Prior	to executing an	exception handler (for instance, if an exception
  filter returns EXCEPTION_EXECUTE_HANDLER), the exception dispatcher per-
  forms	a real unwind of the runtime stack, executing any termination
  handlers established for try...finally blocks	that terminated	as a result
  of the transfer of control to	the exception handler.	Only then does the
  dispatcher calls the exception handler.

  The exception-handler	is a compound statement	that deals with	the exception
  condition. It	executes within	the scope of the procedure that	includes the
  try...except construct and can access	its local variables.  A	handler	can
  respond to an	exception in several different ways, depending on the nature
  of the exception.  For instance, it can log an error or correct the cir-
  cumstances the led to	the exception being raised.

  Either an exception filter or	exception handler can take steps to modify or
  augment the exception	information it has obtained and	ask the	C-language
  exception dispatcher to deliver the new information to exception code	esta-
  blished in some outer	try body or prior call frame.  This activity is	more
  straightforward from within the exception filter, which operates with	the
  frames of the	latest executing procedures -- and the exception context --
  still	intact on the runtime stack.  The filter simply	completes its pro-
  cessing by returning a 0 to the dispatcher to	request	the dispatcher to
  continue its search for the next handler.  For an exception handler to
  trigger a previously-established handler, it must raise another exception,
  from its own context,	that the previously-established	handler	is equipped
  to handle.

  A procedure (or group	of interrelated	procedures) can	contain	any number of
  try...except constructs, and can nest	these constructs.  If an exception
  occurs within	the try...except block,	the system invokes the exception
  handler associated with that block.

  Termination Handling

  The Tru64 UNIX C language compiler allows you	to ensure that whenever	con-
  trol is passed from a	guarded	body of	code, a	specified block	of termina-
  tion code is also executed.  The termination code is executed	regardless of
  how the flow of control leaves the guarded code.  For	example, a
  termination handler can guarantee that clean-up tasks	are performed even if
  an exception or some other error occurs while	the guarded body of code is
  executing.

  The syntax for a termination handler is as follows:

       try {
	       try-body
	   }
       finally	{
	termination-handler
	 }

  The try-body is the code, expressed as a compound statement, that the	ter-
  mination handler protects. The try body can be a block of statements or a
  set of nested	blocks.	It can include the following statement,	which causes
  an immediate exit from the block and execution of its	termination handler:

       leave;

  The termination-handler is a compound	statement that executes	when the flow
  of control leaves the	guarded	try body, regardless of	whether	the try	body
  terminated normally or abnormally.  The guarded body is considered to	have
  terminated normally when the last statement in the block is executed (that
  is, when the body's closing "}" is reached). Use of the leave	statement
  also causes a	normal termination. The	guarded	body terminates	abnormally
  when the flow	of control leaves it by	any other means: for example, due to
  an exception,	or due to a control statement such as return, goto, break or
  continue.

  A termination	handler	can call the following intrinsic function to deter-
  mine whether the guarded body	terminated normally or abnormally.

       int abnormal_termination();

  The abnormal_termination function returns 0 if the try body completed
  sequentially;	otherwise, it returns 1.

  The termination handler itself may terminate sequentially or by a jump out
  of the handler.  If it terminates sequentially (by reaching the closing
  "}"),	subsequent control flow	depends	on how the try body terminated,	as
  follows:

    +  If the try body terminated normally, execution continues	with the
       statement following the complete	try...finally block.

    +  If the try body terminated abnormally with an explicit jump out of the
       body, the jump is completed.  However, if the jump exits	the body of
       one or more containing  try...finally statements, their termination
       handlers	are invoked before control is finally transferred to the tar-
       get of the jump.

    +  If the try body terminated abnormally due to an unwind, a jump to an
       exception handler, or by	an exc_longjmp,	control	is returned to the
       runtime,	which will continue invoking termination handlers as required
       before jumping to the target of the unwind.

  Like exception filters, termination handlers are treated as Pascal-style
  nested procedures, and are executed without the removal of frames from the
  runtime stack. A termination	handler	can thus access	the local variables
  of the procedure in which it is declared.

  Note that there is a performance cost	in the servicing of abnormal termina-
  tions, inasmuch as abnormal terminations (and	exceptions) are	considered to
  be outside the normal	flow of	control	for most programs.  Keep in mind that
  explicit jumps out of	a try body are considered abnormal termination.
  Normal termination is	the simple case	and costs less at runtime.  In some
  instances, you can avoid this	cost by	replacing a jump out of	a try body
  with a leave statement (which	transfers control to the end of	the innermost
  try body) and	testing	a status variable after	completion of the entire
  try...finally	block.

  A termination	handler	itself may terminate nonsequentially (for instance,
  to abort an unwind) by means of a transfer of	control	(for instance, a
  goto,	break, continue, return, exc_longjmp, or the occurrence	of an excep-
  tion). If this transfer of control exits another try...finally block,	its
  termination handler will execute.

NOTES

  The try body,	exception handler, and termination handler are compound
  statements and thus must each	be enclosed in braces ({}).

  You must not jump into a try body, exception handler,	or termination
  handler when control is outside the body or handler.

  You cannot define a procedure	or function within a try...except or
  try...finally	block, although	the sole contents of the block might be	a
  procedure or function.

  If an	exception handler within a try...except	block contains another
  try...except block, and the exception_code() function	is invoked within the
  exception filter or exception	handler	for the	latter block, it returns the
  most recent exception	code.  If the original handler later invokes the
  intrinsic, its effects are undefined.

  The compiler will disable a number of	optimizations in order to ensure the
  integrity of try...except and	try...finally blocks.

FILES

  excpt.h    Defines data structures supporting	the exception handling sys-
	     tem.  excpt.h includes c_excpt.h.

RELATED	INFORMATION

  Functions: exception_intro(3), exception_dispatcher(3), unwind(3),
  exc_resume(3), signal(2), sigaction(2).

  Files: excpt(4), signal(4).

  Calling Standard for Alpha Systems