unwind(3)						     Library Functions Manual							 unwind(3)

NAME

       unwind, exc_virtual_unwind, RtlVirtualUnwind, exc_find_frame_ptr, exc_remote_virtual_unwind - Routines to unwind a context

SYNOPSIS

       #include <excpt.h>

       void unwind(
		       PCONTEXT pcontext,
		       PRUNTIME_FUNCTION prf);

       void exc_virtual_unwind(
		       PRUNTIME_FUNCTION prf,
		       PCONTEXT pcontext);

       exc_address RtlVirtualUnwind(
		       exc_address controlpc,
		       PRUNTIME_FUNCTION prf,
		       PCONTEXT pcontext,
		       PCONTEXT_POINTERS ppointers);

       exc_address  exc_find_frame_ptr(
		       PRUNTIME_FUNCTION prf,
		       PCONTEXT pcontext);
		       PCONTEXT pnext_context);

       unsigned long exc_remote_virtual_unwind (
		       void *handle,
		       int (*fetch_from_process) (
				    void *handle,
				    void *addr,
				    void *buffer,
				    long size),
		       exc_address crd_handle,
		       PRUNTIME_FUNCTION pcrd,
		       PCONTEXT pcontext);

PARAMETERS

       Pointer	to  a  struct  sigcontext (see signal(2)) used to represent a procedure's context.  Pointer to a struct sigcontext (see signal(2))
       used to represent the context of a procedure's caller.  If you specify a nonzero pnext_context argument, the pcontext argument is  ignored.
       Pointer	to  run-time  function	(code-range  descriptor)  for the PC stored in the sc_pc field of the activation context record; a call to
       exc_lookup_function_entry returns this value.  Although this argument can be zero, by providing this argument, a caller already having this
       information  would  save  an extra search for the run-time function.  Copy of the sc_pc field of the activation context record.	Pointer to
       structure containing addresses corresponding to the locations that were used to restore registers; if zero, this argument is ignored.

       The following descriptions apply to parameters for the exc_remote_virtual_unwind routine.  How these parameters are interpreted depends	on
       whether	the  process  involved	in the operation is local or remote.  Remote unwind: A pointer to an arbitrary block of memory, set up and
       managed by the user application, and passed throught the exception handling routines.  This allows the author of the function identified by
       the  fetch_from_process	parameter to maintain any necessary state.  The state maintained here will most likely include the identity of the
       process to be unwound.

	      Local unwind:  This parameter is ignored.  Remote unwind:  The address of an application-specific function, written by the author of
	      the  application	that calls exc_remote_virtual_unwind(). If the value of the fetch_from_process parameter is NULL, the unwind takes
	      place in the local process, not a remote process.

	      The function identified by the fetch_from_process parameter takes the following arguments: The handle parameter that was passed into
	      exc_remote_virtual_unwind.   The	starting  address  in the remote process from which to copy memory.  A buffer in the local process
	      into which data from the remote process is copied.  The number of bytes to copy from addr to buffer.  The region of  memory  pointed
	      to by buffer must be at least size bytes in length.

	      The  function  identified by the fetch_from_process parameter returns 0 (zero) to indicate success and nonzero to indicate a failure
	      in accessing the remote address space.  A failure will also cause an exception status to be raised.

	      Local unwind:  The fetch_from_process parameter is ignored.  Remote unwind: The address of the cell exc_crd_list_head in the  remote
	      process.	The means by which this address is communicated to the local (tracing) process is application specific.

	      Local unwind:  This parameter is ignored.  Remote unwind:  This parameter is ignored.

	      Local unwind: The address of a code-range descriptor describing the context from which to begin the unwind.  If NULL, the code-range
	      descriptor is looked up based on the PC contained in the pcontext parameter.  This is often passed as NULL for the  initial  invoca-
	      tion  of	exc_remote_virtual_unwind()  and  is always passed as NULL for iterated invocations during the stack walk.  A pointer to a
	      struct sigcontext representing the context of the procedure (local or remote) that is to be unwound.

	      At a minimum, this context structure must contain the following context for the routine to be unwound:  FP register ($15), SP regis-
	      ter ($30), RA register ($26 in a standard call), and the PC.  Additionally, the context may contain the preserved registers.

	      This  argument needs to be set up only once; consecutive calls to exc_remote_virtual_unwind() manipulate this structure to represent
	      the state of successively earlier procedures in the call chain.

DESCRIPTION

       All of the unwind routines perform a virtual unwind.  Unlike the routines described in exc_resume(3), these routines do not actually unwind
       a  procedure  call by modifying the real registers and other machine state.  Instead, these routines modify the structure pointed to by the
       pcontext argument so that it represents the previous procedure in the call stack. The routines use procedure information  supplied  in  the
       structure pointed to by the prf argument to decide how to virtually unwind the context (for instance, how to modify the registers and other
       machine state).	This information is placed in the object by the assembler and linker and conforms to the calling standard for  Alpha  sys-
       tems.

       If  the	specify  a  procedure's context in pcontext and the pnext_context argument is non-zero, exc_find_frame_ptr generates a copy of the
       pcontext argument.  The original copy of the context is not modified.  If you supply a  pointer	to  the  context  of  the  caller  in  the
       pnext_context  argument, exc_find_frame_ptr returns the stack pointer associated with that context as the frame pointer of the current con-
       text.

       The other unwind routines modify the structure pointed to by the pcontext argument in order to represent the context of the caller.

       Remote unwinding by the exc_remote_virtual_unwind function can involve a local or remote process - unlike the  unwind,  exc_virtual_unwind,
       and  RtlVirtualUnwind  functions  that operate only on local processes. Remote unwinding is controlled by the fetch_from_process parameter.
       This parameter is a pointer to (or handle for) an application-supplied function that knows how to access the memory of the  process  (local
       or remote) being acted on: If the user application passes a NULL value in the fetch_from_process parameter, the local process is performing
       an unwind on its own stack. This allows the unwind routine to make certain optimizations in its processing.  If the user application passes
       the  address of a routine in the fetch_from_process parameter, the unwind routine is not allowed to assume anything about the process it is
       accessing, and only the fetch routine is allowed to know the identity of the process being unwound.  It might  be  the  local  process,	it
       might  be  another  process  in	the system, it might be a process on another system on the network, or it might be a corefile from a long-
       deceased process.

       To summarize, remote unwinding is the capability to unwind the stack of a process that is not necessarily the process doing the unwind.

       The exc_remote_virtual_unwind function returns 1 to indicate that the program being unwound was in the prologue or epilogue  of	the  frame
       for the current context; otherwise, it returns 0.

       All of the unwind routines typically use masks and stack offsets found in procedure related data structures (described in the Calling Stan-
       dard for Alpha Systems) to restore registers. Those data structures also can contain enough information for these  routines  to	adequately
       deal with prologues, epilogues, and signal frames.

       Users writing assembly language routines should consult the Assembly Language Programmer's Guide to determine which directives are required
       to provide enough information for these routines to correctly unwind through them.

									  Note
       The origins of the various unwind routines are as follows: unwind originated in the ULTRIX libexc and has an interface compatible with  the
       original one, as long as the ULTRIX caller treated the prf argument as an opaque pointer.  The prf structure has been changed to conform to
       the calling standard for Alpha systems, and any callers that explicitly access  its  fields  will  encounter  incompatibilities.   exc_vir-
       tual_unwind originated in libexc.  RtlVirtualUnwind is a Microsoft Windows NT run-time library interface.  It returns a copy of the updated
       sc_pc field of the sigcontext when leaving the routine.	The routine also updates the structure pointed to by the ppointers argument.

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),	exception_dispatcher(3),  exc_lookup_function_entry(3), signal(2), sigaction(2), setjmp(3), exc_unwind(3),
       __exc_last_chance(3), ieee(3).

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

       Assembly Language Programmer's Guide.

       Calling Standard for Alpha Systems.  delim off

																	 unwind(3)