*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> unwind (3)              



NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       #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
               PRUNTIME_FUNCTION prf,
               PCONTEXT pcontext,
               PCONTEXT    pnext_context    );    unsigned   long
               void *handle,
               int  (*fetch_from_process)  (void  *handle,   void
       *addr, void *buffer, long size),
               exc_address crd_handle,
               PRUNTIME_FUNCTION pcrd,
               PCONTEXT pcontext );

PARAMETERS    [Toc]    [Back]

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

              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    [Toc]    [Back]

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

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

FILES    [Toc]    [Back]

       /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    [Toc]    [Back]

       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

[ Back ]
 Similar pages
Name OS Title
gss_init_sec_context HP-UX establish a security context between the context initiator and a context acceptor
unwind HP-UX overview of stack unwind library entry points and convenience macros
gss_accept_sec_context HP-UX establish a security context between the application and a context acceptor
glciscontext IRIX test whether a context ID is the current GLC context
glXGetContextIDEXT Tru64 get the XID for a context.
glxgetcontextidext IRIX get the XID for a context.
csplit HP-UX context split
glxdestroycontext IRIX destroy a GLX context
ucontext Tru64 user context
glXDestroyContext Tru64 destroy a GLX context
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service