exc_virtual_unwind man page on DigitalUNIX

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

unwind(3)							     unwind(3)

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

       #include <excpt.h>

       void unwind(
	       PCONTEXT pcontext,
	       PRUNTIME_FUNCTION prf ); void exc_virtual_unwind(
	       PCONTEXT pcontext ); exc_address RtlVirtualUnwind(
	       exc_address controlpc,
	       PCONTEXT pcontext,
	       PCONTEXT_POINTERS ppointers ); exc_address exc_find_frame_ptr(
	       PCONTEXT pcontext,
	       PCONTEXT	 pnext_context	);   unsigned	long   exc_remote_vir‐
	       void *handle,
	       int (*fetch_from_process) (void *handle, void *addr, void *buf‐
       fer, long size),
	       exc_address crd_handle,
	       PCONTEXT pcontext );

       Pointer to a struct sigcontext (see signal(2)) used to represent a pro‐
       cedure'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 struc‐
       ture 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_vir‐
       tual_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 that is set up
       and  managed  by	 the user application and passed through 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_vir‐
	      tual_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
	      invocation 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) to be unwound.

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

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

       All of the unwind routines perform a virtual unwind.  Unlike  the  rou‐
       tines 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 assem‐
       bler and linker and conforms to the calling standard for Alpha systems.

       If  the specify a procedure's context in pcontext and the pnext_context
       argument is nonzero, exc_find_frame_ptr generates a copy of  the	 pcon‐
       text  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 context.

       The other unwind routines modify the structure pointed to by the	 pcon‐
       text 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_vir‐
       tual_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 mem‐
       ory of the process (local or remote) being acted on: If the user appli‐
       cation 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 sys‐
       tem, 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 Standard
       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.

       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.

       /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

       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


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