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)
