unwind(5)unwind(5)NAME
unwind: unwind.h - overview of stack unwind library entry points and
convenience macros
SYNOPSISDESCRIPTION
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 exe‐
cutable files which are not covered in and related documents.
CONCEPTS AND DEFINITIONS OF TERMS
One of the most basic features distinguishing any high level program‐
ming 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 pro‐
cedure 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 relation‐
ship between procedures in the procedure call chain.
We sometimes generalize the procedure call and interruption relation‐
ships using the terms and In the procedure call relationship, refers to
the caller while refers to the callee. In the interruption relation‐
ship, 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 vis‐
ible 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 activa‐
tion 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 pro‐
cessor 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:
· Implement a user-space debugger's stack backtrace command that
displays the program call stack, such as the command in the GNU
Debugger. See gdb(1).
· 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.
· Display a stack trace to from an error-handling routine to sim‐
plify servicing or debugging the application.
The stack unwind library's representation of a given procedure's acti‐
vation 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 Sec‐
tion 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
· 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).
· Unwind its own stack, the stack of a target process, or the stack
of a core file. Querying for preserved register values is permit‐
ted 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 call‐
back functions which the client must register with the stack
unwind library.
· 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 associated with User space unwinder applica‐
tions 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 con‐
text.
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 val‐
ues 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 mechanism
and the Runtime Architecture conventions that must be observed, and
provides details about the layout and semantics of the unwind informa‐
tion 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 interested in
learning the environment-dependent details of the unwind information
should refer to documents in the series including the document 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
function 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
· construction of an data structure
· initialization of the
· stepping the
· querying the
· possibly clearing and reinitialization the
· 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 initial‐
ize 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 pro‐
duced 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 values 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 trans‐
fers 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_Inter‐
rupted_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_getKernelSavedContext(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_createContext(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 snapshot
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 system'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 vali‐
dated) in order for subsequent calls to to be successful:
· The Instruction Pointer (IP). See _UNW_setIP(3X)
· Preserved and scratch branch registers in the range BR0
through BR7.
· Preserved and scratch predicate registers (PR1 through
PR63).
· Application Registers in the set and
· General registers in the range GR1 through GR31. Note
that many general registers are considered "scratch" gen‐
eral registers. If scratch general registers are not
initialized by the client, subsequent calls are still
likely (but not guaranteed) to succeed, because most pro‐
cedures 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 regis‐
ters, 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.
· Preserved and scratch floating point registers.
· The Current Frame Marker (CFM). See _UNW_setCFM(3X).
· Stacked general registers in the snapshot procedure's
frame as defined by the Current Frame Marker. See previ‐
ous 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 Predicate
register by number outside the documented ranges returns a value equiv‐
alent 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 interrup‐
tion 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 sig‐
nal 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 sig‐
nal handler.
scratch BR0 (return link)
Value valid only after across a user space interrup‐
tion 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 sig‐
nal 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 han‐
dler.
Convenience value CFM
Value valid after successful return from and Reminder:
CFM (current frame marker) is not architecturally vis‐
ible. 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 con‐
structed" 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 func‐
tions 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
communicated 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 enumeration
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)
