hpux man page for unwind

unwind(5)							File Formats Manual							 unwind(5)

NAME
       unwind: unwind.h - overview of stack unwind library entry points and convenience macros

SYNOPSIS
DESCRIPTION
       The header defines the Application Programming Interface (API) of the stack unwind library, supplied as for HP-UX on Itanium-based systems.
       This manpage discusses the general concepts of stack unwinding and how the stack unwind library is intended to be used.	It is intended	to
       complement  the section 3X manpages describing unwind library entry points.  This manpage also explains the format of the unwind header and
       some details of the unwind tables contained within Itanium-based executable files which are not covered in and related documents.

CONCEPTS AND DEFINITIONS OF TERMS
       One of the most basic features distinguishing any high level programming language from assembly language is built-in support for  procedure
       or function calls.  A procedure that has been called may itself call other procedures, forming a procedure The terms, and describe the pro-
       cedure call relationship between procedures in the procedure call chain.  The caller is the procedure that calls the callee.  When a proce-
       dure in the call chain finishes executing statements, its caller resumes execution with the next statement following the call.

       One  of	the  basic  features  of multitasking operating systems is the interruption event, the act of interrupting flow of control, saving
       almost the entire user-visible processor state, and giving control to a function.  We use two terms and to describe the interruption  rela-
       tionship between procedures in the procedure call chain.

       We sometimes generalize the procedure call and interruption relationships using the terms and In the procedure call relationship, refers to
       the caller while refers to the callee.  In the interruption relationship, refers to the interrupted procedure while refers to the handler.

       Conceptually, for each procedure that is active during a chain of nested calls or interruptions, there is an which contains the user  visi-
       ble  processor  state  of that procedure at the time of the call or interruption event.	An activation record is like a link put on a chain
       when a procedure is called and removed when that procedure completes.  Activation records are  added  and  removed  in  last-in,  first-out
       order, so the call chain can be described technically as a

       Stack  unwinding  describes the task of recovering enough of the activation record of a predecessor (caller or interrupted procedure) given
       the activation record of its successor (callee or handler) so that one could initialize the processor  state  to  the  predecessor's  state
       using  values in the predecessor's activation record and subsequently the processor could continue executing the predecessor's instructions
       as though the call to the callee had returned or the interruption event had completed.

       A software application writer may be motivated to perform the task of stack unwinding for any number of reasons including:

	 o  Implement a user-space debugger's stack backtrace command that displays the program call stack, such as the command in the GNU  Debug-
	    ger.  See gdb(1).

	 o  Examine  the program call stack for the purpose of handling an exception, of garbage collection, or possibly for performance, profile-
	    base tools, or other resources analysis.

	 o  Display a stack trace to from an error-handling routine to simplify servicing or debugging the application.

       The stack unwind library's representation of a given procedure's activation record is contained in an data  structure  for  the	procedure.
       Space  allocated  to  a procedure in the procedure call (memory) stack is referred to as the procedure's The stack frame stores much of the
       information contained in a procedure's conceptual activation record defined earlier.  Because this is true, the term is typically  used	in
       place of throughout the the stack unwind library documentation.

       The unwind manpages assume familiarity with and terms defined in Section 5.1, and in Chapter 11,

FEATURES
       The  stack unwind library provides an API for unwinding the stack of a program that conforms to the The stack unwind library can be used by
       a process to

	 o  Print its own stack trace to standard error or to an output stream,  usually  for  diagnostic  purposes.   See  U_STACK_TRACE(3X)  and
	    _UNW_STACK_TRACE(3X).

	 o  Unwind its own stack, the stack of a target process, or the stack of a core file.  Querying for preserved register values is permitted
	    for most activation records on the procedure call stack.  For certain activation records, scratch register values can be queried, too.

	    To unwind a process other than self or a core file, the stack unwind library relies on the client to obtain the location of the unwind
	    segment  and  provide a reader function to access the other process' or core file's memory.  This is accomplished using callback func-
	    tions which the client must register with the stack unwind library.

	 o  Provide stack unwind support for conforming ANSI C++ exception handling including the transfer of control to an enclosing (less deeply
	    nested) procedure.	See (Draft), November 17, 2000, located at

       For  the  purpose of release-to-release compatibility, the stack unwind library's interface is completely programmatic in order to hide the
       implementation details of data structures.

TYPE DEFINITIONS
       Return values for the API functions are an enumeration and have the following meaning:

	      describes a frame beyond which
			the stack unwind library can no longer step since the frame belongs to kernel interruption frame other than the one  asso-
			ciated with User space unwinder applications should never receive this return code.

	      describes a frame beyond which
			the  stack  unwind library can no longer step.	This return code is produced when is called for any describing a procedure
			whose frame is marked with the bottom of stack convention -- a saved return link of 0 (see Chapter 11.1:

	      All's well.

	      Some generic problem occurred during step.

	      The instruction pointer value in
			is marked invalid.

	      The stack pointer value in
			is marked invalid.

	      A general register value which was marked invalid
			was encountered in during the step process.

	      The AR.PFS value in
			is marked invalid.

	      The AR.RSC value in
			is marked invalid.

	      The AR.BSP value in
			is marked invalid.

	      The AR.BSPSTORE value in
			is marked invalid.

	      The AR.CFM value in
			is marked invalid.

	      A branch register value which was marked invalid
			was encountered in during the step process.

	      The	value was not aligned.

	      The AR.RNAT value in
			is marked invalid.

	      The stack unwind library
			could not find an unwind descriptor for a procedure which the stack unwind library can prove is not a leaf procedure.

	      The unwind descriptor for the frame was misformed.

	      The register stack engine was not flushed.

	      Error value returned
			while querying for an interruption's saved user context.

	      A call to was made from one of the following states: Start, Bad, Kernel_Bottom_Frame.  See subsection below.

	      The client initialized outside of the allowed set of registers.

	      The client queried outside of the allowed set of registers.

	      The client queried a register marked invalid in the

	      The client attempted to initialize values while the
			was not in the Init state.

	      A generic problem occurred during a call to

	      The client called
			from one of the following states: Start, Bad, Stop, Frame.

	      The stack unwind library cannot allocate enough memory to
			perform the function requested.

	      The client called
			from one of the following states: Start, Bad, Stop.

	      The client called
			while not in state Kernel_Bottom_Frame.

	      Some logic problem occurred.
			Contact HP support.

	      The stack unwind library
			encountered an incorrect field of a format unwind descriptor.  See Section B.3: Descriptor Records for Prologue Regions.

       The notion of TRUE and FALSE is communicated through an enumeration which has enumerators and has value 0.

       Integer values are communicated through types defined as follows:

	      is an unsigned 32-bit integer.

	      is a signed 64-bit integer.

	      is a signed 32-bit integer.

	      is an unsigned 64-bit integer.

       The value query and initialization functions use several structures for passing values.	They are as follows:

	      Structure has two fields of type and

	      Structure has two fields of type and

	      Structure has a field of type and a field of type

       The enumeration is used by functions and when querying and setting values of application registers.  has enumerators and

       is a synonym for

COMMUNICATING AND LOCATING UNWIND INFORMATION
       The definition of the Itanium-based unwind architecture is contained in Chapter 11 of That document discusses the need for an unwind mecha-
       nism  and  the  Runtime	Architecture  conventions that must be observed, and provides details about the layout and semantics of the unwind
       information blocks.  It leaves environment-dependent details including the method of locating the unwind table to to be defined and handled
       by  the	Operating  System environment.	The stack unwind library handles these environment-dependent details for the client.  Users inter-
       ested in learning the environment-dependent details of the unwind information should refer to documents in the series including	the  docu-
       ment entitled

   Callbacks
       In  order to perform the task of stack unwinding, the stack unwind library needs to determine the text base, the unwind header location and
       the value of the global data pointer (general register for any given load module (which is identified  by  any  valid  instruction  address
       within  the  load module).  Unwind functions such as and the stack unwind library's exception handling support make use of dlmodinfo(3C) to
       obtain these values.  Clients (such as debuggers) using the stack unwind library to perform a cross-process unwind need to register a func-
       tion  during  the  stack  unwind  library data structure construction to perform this lookup task in the place of The function has type The
       semantics of and the interface to the lookup function are defined in _UNW_createContext(3X)

       Furthermore, the stack unwind library needs the ability to read values from the target process memory (or memory image if  the  process	is
       dead).	Clients  using	the  stack unwind library to perform a cross-process unwind need to register a function during data structure con-
       struction to perform memory reading tasks (in place of direct memory references).  The function has type The semantics of and the interface
       to the memory reader function are defined in _UNW_createContext(3X).

CLIENT
/LIBRARY INTERACTION
       The steps a client takes to perform a stack unwind operation include

	 o  construction of an data structure

	 o  initialization of the

	 o  stepping the

	 o  querying the

	 o  possibly clearing and reinitialization the

	 o  finally, destruction of the

       Note:  a  client  throwing  an Exception uses a language independent API managed by the aCC standards committee.  See ,CR http://www.codes-
       ourcery.com/cxx-abi/abi.html .

   States
       A state machine is used as an aid to define the legal ordering of the tasks of a stack unwind operation and to describe	the  stack  unwind
       library's  response  to	calls  from the client.  The state machine is defined by eight states and transitions between the states which are
       triggered by calls to the stack unwind library API functions or in some cases by system conditions such as an out of memory condition.  The
       states and possible transitions are:

	      Start	Prior to construction of the object.

			From Start, the client may call and They transfer the into either state Init or state Bad.

	      Bad	A state to indicate the is not usable.	This state is entered after a failed attempt at construction -- most likely due to
			a memory allocation error.  This state can also be entered if the unwind library becomes hopelessly lost during  unwinding
			-- for example, after encountering a bad pointer value from an incorrectly initialized context.

			With  the  exception  of  the  stack  unwind library's behavior when in the Bad state is not defined.  From state Bad, the
			client's safest recourse is to destroy the object via a call to which transfers the into state Stop.

	      Init	The state in which the client is permitted to initialize the with pertinent  user-visible  processor  state  describing  a
			given snapshot of a program's execution.

			From  Init,  the  client may call and none of which causes a state transition.	The client may also call or which transfer
			the into state Frame or into state Bad.  The client may call which transfers the into state Stop.

	      Frame	The state in which the stack unwind library has produced or manipulated description of the processor state through  either
			or The client may query for and obtain valid values for most of the preserved register values.	Most scratch register val-
			ues are not valid in the Frame state.  Note that use of the query functions are permitted in any state,  but  validity	of
			the values returned is guaranteed only in certain states as listed in section below.

			From Frame, the client may call which transfers the into states Frame or Bad.  It may call which transfers the into states
			Frame, Bad, Kernel_Bottom_Frame, or User_Sendsig_Frame.  The client may call which transfers the  into	state  Init.   The
			client may call which transfers the into state Stop.

	      User_Sendsig_Frame
			The  state  in	which describes the processor state of a wrapper function through which the kernel calls the user's signal
			handler.  See From User_Sendsig_Frame, the client may call which transfers the into states Frame  or  Bad.   It  may  call
			which  transfers  the into states User_Interrupted_Frame or Bad.  The client may call which transfers the into state Init.
			The client may call which transfers the into state Stop.

	      User_Interrupted_Frame
			The state in which the describes user code which was interrupted by a signal.  The unique characteristic of this state	is
			the client may query for and obtain valid values of scratch branch, scratch predicate, scratch floating point, and scratch
			general registers as well as for preserved registers.  During  a  series  of  calls  to  a  frame  associated  with  state
			User_Interrupted_Frame always follows a frame associated with state User_Sendsig_Frame.

			From  User_Interrupted_Frame,  the  client  may call or which transfers the into states Frame or Bad.  The client may call
			which transfers the into state Init.  The client may call which transfers the into state Stop.

	      Kernel_Bottom_Frame
			The state indicating the bottom of a kernel call stack.  The client may use while in this state.  See _UNW_getKernelSaved-
			Context(3X)

			From  Kernel_Bottom_Frame, the client may call or which transfers the into states Frame or Bad.  The client may call which
			transfers the into state Init.	The client may call which transfers the into state Stop.

	      Stop	The has been discarded.

   Construction
       Construction is performed by a call to either or to is primarily used when a process intends to unwind its own stack.   is  primarily  used
       when  a	process intends to unwind a different process' stack or the stack of a dead process preserved in a core file.  See _UNW_createCon-
       text(3X), _UNW_createContextForSelf(3X) and subsection in section above.

   Initialization
       The client's goal when the is in the Init state is to place a snapshot of the processor state at a given point of time into the	The  snap-
       shot  consists  of  a  set of required register values.	The register stack engine (RSE) must be flushed at the time the snapshot is taken.
       See the instruction in the processor specification.

       Initialization is only allowed while the is in the Init state.

       Writes are always allowed to general registers 1-31, Floating Point Registers, Predicate Registers, Branch Registers, the (CFM), the  (IP),
       and Application Registers in the set Writing to a particular register validates that value in the Once the current frame marker (CFM) value
       is valid, writes to General Registers in the range GR32 through GR32 + are allowed (for the purpose of initializing an  Itanium-based  sys-
       tem's  RSE  stacked  general registers in the snapshot procedure's RSE frame).  A set to CFM invalidates the general registers in the range
       GR32 through GR127.

       Of the above, the following values must be initialized (therefore validated) in order for subsequent calls to to be successful:

	      o      The Instruction Pointer (IP).  See _UNW_setIP(3X)

	      o      Preserved and scratch branch registers in the range BR0 through BR7.

	      o      Preserved and scratch predicate registers (PR1 through PR63).

	      o      Application Registers in the set and

	      o      General registers in the range GR1 through GR31.  Note that many general registers are considered	"scratch"  general  regis-
		     ters.  If scratch general registers are not initialized by the client, subsequent calls are still likely (but not guaranteed)
		     to succeed, because most procedures do not preserve values in Scratch registers.  The general unwind descriptors  defined	in
		     Table  11-13  of  the  do permit procedures to preserve values in Scratch registers, so for thoroughness, it is required that
		     even the scratch general registers be initialized.  The same is true for the scratch branch,  predicate  and  floating  point
		     registers.

	      o      Preserved and scratch floating point registers.

	      o      The Current Frame Marker (CFM).  See _UNW_setCFM(3X).

	      o      Stacked  general registers in the snapshot procedure's frame as defined by the Current Frame Marker.  See previous bullet and
		     _UNW_setCFM(3X).

   Stepping
       Once initialization of the is complete, it now represents the snapshot procedure's processor state.  The client may call which modifies	to
       represent the processor state.  See _UNW_step(3X).

   Queries
       Querying register values by the client is allowed during all states.  Returned values are guaranteed valid only after certain actions, how-
       ever, as described below.  Reading a register which is uninitialized or marked invalid returns a value equivalent to zero (0.0 for floating
       point  registers, from the enumeration for Predicates) and sets to See Requesting a General, Floating Point, Branch, Application, or Predi-
       cate register by number outside the documented ranges returns a value equivalent to zero and sets the AlertCode to

       The following list indicates after which API calls specific register values are valid.  This "validity list" does not cover the Initializa-
       tion  phase  (that  is, when the stack unwind library is in state Init) during which only those values which the client has initialized are
       valid.  The registers are listed by their register classes as defined in Chapter 5 of

	      constant GR0
			Value valid always.

	      special GR1 (global pointer)
			Value valid after successful return from and

	      scratch GR2-GR3, GR8-11 and GR14-GR31
			Value valid only after across a user space interruption such as a signal handler.

	      preserved GR4-GR7
			Value valid after successful return from and

	      special GR12 (stack pointer)
			Value valid after successful return from and

	      special GR13 (thread pointer)
			Value valid after successful return from and

	      stacked GR32-127 (automatic RSE registers)
			Value valid after successful return from and Note: only those values existing in the current frame (as depicted by the CFM
			value) are valid.  Alert code is set when values outside of the current frame are queried.

	      constant FR0 and FR1
			Value valid always.

	      preserved FR2-FR5 and FR16-FR31
			Value valid after successful return from and

	      scratch FR6-FR15 and FR32-FR127
			Value valid only while in state User_Interrupted_Frame after across a user space interruption such as a signal handler.

	      constant P0
			Value valid always.

	      preserved PR1-PR5 and PR16-PR63
			Value valid after successful return from and

	      scratch PR6-PR15
			Value valid only while in state User_Interrupted_Frame after across a user space interruption such as a signal handler.

	      scratch BR0 (return link)
			Value valid only after across a user space interruption such as a signal handler.

			Do  not  attempt  to  figure out the predecessor's instruction pointer from BR0.  Call to obtain the for the predecessor's
			frame and use

	      preserved BR1-BR5
			Value valid after successful return from and

	      scratch BR6-BR7
			Value valid only while in state User_Interrupted_Frame after across a user space interruption such as a signal handler.

	      application register FPSR
			Value valid after successful return from and

	      Value valid after successful return from
			and

	      Value valid after successful return from
			and

	      Value valid after successful return from
			and

	      Value valid after successful return from
			and

	      Value valid after successful return from
			and

	      The	application register is a special case.  It is marked valid but not updated during because its values are only scratch and
			read-only.

	      Value valid after successful return from
			and

	      Value valid only after
			across a user space interruption such as a signal handler.

	      Convenience value CFM
			Value  valid  after  successful  return from and Reminder: CFM (current frame marker) is not architecturally visible.  The
			stack unwind library uses the same register layout as the application register for this value.

   Clearing for Reinitialization
       The client may call from any states other than Bad, Start, and Stop.  On successful completion of the object appears to	be  in	the  "just
       constructed" condition.	All register values in the object are invalidated and it is placed in the Init state.

ERROR CONDITIONS AND RECOVERY
       In order to allow clients a convenient way of checking for range errors while initializing an or for sanity checking for an error condition
       after several actions have been performed on an object, two API functions are provided: and

       allows the client to obtain the most recent "client needs to know" returned (or "encountered" in the case of the  query	functions)  by	an
       interface function since the last clear of the Alert Code.

       "Client needs to know" return codes are all of the enumerators in the enumeration with the exception of

       and each reset the Alert Code to although and can set the Alert Code to in the event of a low memory condition.

   Low Memory Conditions
       In  most cases, a failed construction of an leaves the client with enough of an object to support a call to the function which would return
       in the event of a failed construction.  Had the construction been successful, would have returned Failed construction is sometimes communi-
       cated by setting the pointer to Subsequent calls to stack unwind library interface functions return if the pointer is

       A failed memory allocation during actions such as returns the return code and sets the Alert Code.  The remaining state of is undefined.

   Return Code Semantics
       The  enumeration  has  some embedded semantics.	has value 0.  Stack boundary conditions that indicate stack frames through which the stack
       unwind library cannot step are assigned negative values.  For example, and have negative values.  All other return values in  the  enumera-
       tion  have  positive  values.   Hewlett-Packard reserves the right to add more return codes to the enumeration.	For compatibility reasons,
       none will be removed, nor will the values assigned to existing return codes be changed in future releases.

SEE ALSO
       _UNW_createContextForSelf(3X), _UNW_currentContext(3X), _UNW_getGR(3X), U_STACK_TRACE(3X).

							   Itanium(R)-based Systems Only						 unwind(5)