unwind(5) unwind(5)
Itanium(R)-based System Only
NAME [Toc] [Back]
unwind - overview of stack unwind library entry points and convenience
macros
SYNOPSIS [Toc] [Back]
#include <unwind.h>
DESCRIPTION [Toc] [Back]
The <unwind.h> header defines the Application Programming Interface
(API) of the stack unwind library, supplied as libunwind.so for HP-UX
on Itanium-based systems. This page 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 manual pages
describing unwind library entry points. This page 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 Itanium Processor Family Software Conventions and Runtime
Architecture and related documents.
CONCEPTS AND DEFINITIONS OF TERMS [Toc] [Back]
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 call chain. The
terms, caller and callee describe the procedure call relationship
between procedures in the procedure call chain. The caller is the
procedure that calls the callee. When a procedure in the call chain
finishes executing statements, its caller resumes execution with the
next statement following the call.
One of the basic features of multi-tasking 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 interruption handler function. We use two terms interrupted
procedure and handler to describe the interruption relationship
between procedures in the procedure call chain.
We sometimes generalize the procedure call and interruption
relationships using the terms successor and predecessor. In the
procedure call relationship, predecessor refers to the caller while
successor refers to the callee. In the interruption relationship,
predecessor refers to the interrupted procedure while successor refers
to the handler.
Conceptually, for each procedure that is active during a chain of
nested calls or interruptions, there is an activation record which
contains the user visible 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
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
technically as a stack.
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:
+ Implement a user-space debugger's stack backtrace command
that displays the program call stack, such as the bt 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 stderr 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 _Unwind_Context data structure
for the procedure. Space allocated to a procedure in the procedure
call (memory) stack is referred to as the procedure's stack frame.
The stack frame stores much of the information contained in a
procedure's conceptual activation record defined earlier. Because
this is true, the term frame is typically used in place of activation
record throughout the the stack unwind library documentation.
The unwind manual pages assume familiarity with Itanium Processor
Family Software Conventions and Runtime Architecture and terms defined
in Section 5.1, Register Usage, and in Chapter 11, Stack Unwinding and
Exception Handling.
FEATURES [Toc] [Back]
The stack unwind library provides an API for unwinding the stack of a
program that conforms to the Itanium Processor Family Software
Conventions and Runtime Architecture. 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_TRAC
.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
+ Unwind its own stack, the stack of a target process, or the
stack of a core file. Querying for unwind context 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 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 C++ ABI for
IA-64, (Draft), November 17, 2000, located at
http://www.codesourcery.com/cxx-abi/abi.html.
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 [Toc] [Back]
Return values for the API functions are an enumeration _UNW_ReturnCode
and have the following meaning:
_UNW_STEP_KERNEL_SAVE_STATE
_Unwind_Context 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_sendsig(). User space unwinder
applications should never receive this return code.
_UNW_STEP_BOTTOM
_Unwind_Context describes a frame beyond which the
stack unwind library can no longer step. This return
code is produced when _UNW_step is called for any
_Unwind_Context describing a procedure whose frame is
marked with the bottom of stack convention - a saved
return link of 0 (see Itanium Processor Family Software
Conventions and Runtime Architecture, Chapter 11.1:
Unwinding the stack).
_UNW_OK All's well.
_UNW_STEP_ERROR
Some generic problem occurred during step.
_UNW_STEP_INVALID_IP
The instruction pointer value in _Unwind_Context is
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
marked invalid.
_UNW_STEP_INVALID_SP
The stack pointer value in _Unwind_Context is marked
invalid.
_UNW_STEP_INVALID_GR
A general register value which was marked invalid was
encountered in _Unwind_Context during the step process.
_UNW_STEP_INVALID_PFS
The AR.PFS value in _Unwind_Context is marked invalid.
_UNW_STEP_INVALID_RSC
The AR.RSC value in _Unwind_Context is marked invalid.
_UNW_STEP_INVALID_BSP
The AR.BSP value in _Unwind_Context is marked invalid.
_UNW_STEP_INVALID_BSPSTORE
The AR.BSPSTORE value in _Unwind_Context is marked
invalid.
_UNW_STEP_INVALID_CFM
The AR.CFM value in _Unwind_Context is marked invalid.
_UNW_STEP_INVALID_BR
A branch register value which was marked invalid was
encountered in _Unwind_Context during the step process.
_UNW_STEP_BAD_BSP_ALIGNMENT
The _UNW_currentContext value AR.BSP was not aligned.
_UNW_STEP_INVALID_RNAT
The AR.RNAT value in _Unwind_Context is marked invalid.
_UNW_STEP_NO_DESCRIPTOR_FOR_NON_LEAF
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.
_UNW_STEP_CORRUPT_DESCRIPTOR
The unwind descriptor for the frame was mis-formed.
_UNW_STEP_RSE_NOT_FLUSHED
The register stack engine was not flushed.
_UNW_STEP_SIGNAL_CONTEXT
Error value returned while querying for an
interruption's saved user context.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
_UNW_STEP_NOT_ALLOWED_IN_STATE
A call to _UNW_step was made from one of the following
states: Start, Bad, Kernel_Bottom_Frame. See subsection
States below.
_UNW_INITIALIZATION_RANGE_ERROR
The client initialized outside of the allowed set of
registers.
_UNW_QUERY_RANGE_ERROR
The client queried outside of the allowed set of
registers.
_UNW_QUERY_INVALID_ERROR
The client queried a register marked invalid in the
_Unwind_Context.
_UNW_SET_NOT_ALLOWED_IN_STATE
The client attempted to initialize values while the
_Unwind_Context was not in the Init state.
_UNW_CURRENT_CONTEXT_FAILED
A generic problem occurred during a call to
_UNW_currentContext.
_UNW_CURRENT_CONTEXT_NOT_ALLOWED_IN_STATE
The client called _UNW_currentContext from one of the
following states: Start, Bad, Stop, Frame.
_UNW_MEMORY_ALLOCATION_ERROR
The stack unwind library cannot allocate enough memory
to perform the function requested.
_UNW_CLEAR_NOT_ALLOWED_IN_STATE
The client called _UNW_clear from one of the following
states: Start, Bad, Stop.
_UNW_QUERY_NOT_ALLOWED_IN_STATE
The client called _UNW_getKernelSavedContext while not
in state Kernel_Bottom_Frame.
_UNW_INTERNAL_ERROR
Some logic problem occurred. Contact HP support.
_UNW_STEP_INTERRUPTION_ABI_MISMATCH
The stack unwind library encountered an incorrect abi
field of a format P10 unwind descriptor. See Itanium
Processor Family Software Conventions and Runtime
Architecture, Section B.3: Descriptor Records for
Prologue Regions.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
The notion of TRUE and FALSE is communicated through an enumeration
_UNW_Boolean which has enumerators _UNW_FALSE and _UNW_TRUE.
_UNW_FALSE has value 0.
Integer values are communicated through types defined as follows:
uint32_t is an unsigned 32-bit integer.
uint64_t is a signed 64-bit integer.
int32_t is a signed 32-bit integer.
int64_t is an unsigned 64-bit integer.
The value query and initialization functions use several structures
for passing values. They are as follows:
Structure _UNW_KernelSavedContext has two fields of type
uint32_t: p10_abi_value and p10_context_value.
Structure _UNW_FR_Value has two fields of type uint64_t:
first_container and second_container.
Structure _UNW_GR_Value has a field of type uint64_t, value,
and a field of type _UNW_Boolean, NaT.
The enumeration _UNW_AppReg is used by functions _UNW_getAR and
_UNW_setAR when querying and setting values of application registers.
_UNW_AppReg has enumerators _UNW_AR_RSC, _UNW_AR_BSP,
_UNW_AR_BSPSTORE, _UNW_AR_RNAT, _UNW_AR_CCV, _UNW_AR_UNAT,
_UNW_AR_FPSR, _UNW_AR_ITC, _UNW_AR_PFS, _UNW_AR_LC, _UNW_AR_EC, and
_UNW_AR_LIST_COUNT.
_UNW_AR_FIRST_REG is a synonym for _UNW_AR_RSC.
COMMUNICATING AND LOCATING UNWIND INFORMATION [Toc] [Back]
The definition of the Itanium-based unwind architecture is contained
in Chapter 11 of Itanium Processor Family Software Conventions and
Runtime Architecture. 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 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
interested in learning the environment-dependent details of the unwind
information should refer to documents in the IA-64 Runtime
Architecture Supplement series including the document entitled
Processor-Specific ELF Supplement for IA-64.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
Callbacks [Toc] [Back]
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 GP) for any
given load module (which is identified by any valid instruction
address within the load module). Unwind functions such as
U_STACK_TRACE() 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 dlmodinfo. The function has type _UNW_LoadMapFromIP.
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 crossprocess
unwind need to register a function during data structure
construction to perform memory reading tasks (in place of direct
memory references). The function has type _UNW_ReadTargetMem. 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 _Unwind_Context data structure
+ initialization of the _Unwind_Context
+ stepping the _Unwind_Context
+ querying the _Unwind_Context
+ possibly clearing and re-initialization the _Unwind_Context
+ finally, destruction of the _Unwind_Context.
Note: a client throwing an Exception uses a language independent API
managed by the aCC standards committee. See
http://www.codesourcery.com/cxx-abi/abi.html.
States [Toc] [Back]
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:
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
Start Prior to construction of the _Unwind_Context object.
From Start, the client may call
_UNW_createContextForSelf and _UNW_createContext. They
transfer the _Unwind_Context into either state Init or
state Bad.
Bad A state to indicate the _Unwind_Context 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 _UNW_destroyContext, 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 _Unwind_Context object via a call to
_UNW_destroyContext, which transfers the
_Unwind_Context into state Stop.
Init The state in which the client is permitted to
initialize the _Unwind_Context with pertinent uservisible
processor state describing a given snapshot of
a program's execution.
From Init, the client may call _UNW_setGR,
_UNW_setGR_NaT, _UNW_setFR, _UNW_setBR, _UNW_setIP,
_UNW_setAR, _UNW_setPR, _UNW_setPreds, _UNW_setCFM,
_UNW_jmpbufContext, and _UNW_clear, none of which
causes a state transition. The client may also call
_UNW_step or _UNW_currentContext, which transfer the
_Unwind_Context into state Frame or into state Bad.
The client may call _UNW_destroyContext, which
transfers the _Unwind_Context into state Stop.
Frame The state in which the stack unwind library has
produced or manipulated _Unwind_Context's description
of the processor state through either _UNW_step or
_UNW_currentContext. 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 Queries below.
From Frame, the client may call _UNW_currentContext,
which transfers the _Unwind_Context into states Frame
or Bad. It may call _UNW_step, which transfers the
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
_Unwind_Context into states Frame, Bad,
Kernel_Bottom_Frame, or User_Sendsig_Frame. The client
may call _UNW_clear, which transfers the
_Unwind_Context into state Init. The client may call
_UNW_destroyContext, which transfers the
_Unwind_Context into state Stop.
User_Sendsig_Frame
The state in which _Unwind_Context describes the
processor state of a wrapper function through which the
kernel calls the user's signal handler. See Itanium
Processor Family Runtime Architecture Supplement,
Signal Handling on HP-UX. From User_Sendsig_Frame, the
client may call _UNW_currentContext, which transfers
the _Unwind_Context into states Frame or Bad. It may
call _UNW_step, which transfers the _Unwind_Context
into states User_Interrupted_Frame or Bad. The client
may call clear, which transfers the _Unwind_Context
into state Init. The client may call
_UNW_destroyContext, which transfers the
_Unwind_Context into state Stop.
User_Interrupted_Frame
The state in which the _Unwind_Context 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 _UNW_step, 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
_UNW_currentContext or _UNW_step, which transfers the
_Unwind_Context into states Frame or Bad. The client
may call clear, which transfers the _Unwind_Context
into state Init. The client may call
_UNW_destroyContext, which transfers the
_Unwind_Context into state Stop.
Kernel_Bottom_Frame
The state indicating the bottom of a kernel call stack.
The client may use _UNW_getKernelSavedContext while in
this state. See _UNW_getKernelSavedContext(3X)
From Kernel_Bottom_Frame, the client may call
_UNW_currentContext or _UNW_step, which transfers the
_Unwind_Context into states Frame or Bad. The client
may call clear , which transfers the _Unwind_Context
into state Init. The client may call
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
_UNW_destroyContext, which transfers the
_Unwind_Context into state Stop.
Stop The _Unwind_Context has been discarded.
Construction [Toc] [Back]
Construction is performed by a call to either
_UNW_createContextForSelf or to _UNW_createContext.
_UNW_createContextForSelf is primarily used when a process intends to
unwind its own stack. _UNW_createContext 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 Callbacks in section
ACCESSING UNWIND INFORMATION above.
Initialization [Toc] [Back]
The client's goal when the _Unwind_Context is in the Init state is to
place a snapshot of the processor state at a given point of time into
the _Unwind_Context. 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 flushrs instruction in the
processor specification.
Initialization is only allowed while the _Unwind_Context is in the
Init state.
Writes are always allowed to general registers 1-31, Floating Point
Registers, Predicate Registers, Branch Registers, the Current Frame
Marker (CFM), the Instruction Pointer (IP), and Application Registers
in the set _UNW_AR_RSC, _UNW_AR_BSP, _UNW_AR_BSPSTORE, _UNW_AR_RNAT,
_UNW_AR_CCV, _UNW_AR_UNAT, _UNW_AR_FPSR, _UNW_AR_ITC, _UNW_AR_PFS,
_UNW_AR_LC. Writing to a particular register validates that value in
the _Unwind_Context. Once the current frame marker (CFM) value is
valid, writes to General Registers in the range GR32 through GR32 +
CFM.sof are allowed (for the purpose of initializing the Itanium-based
system 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 _UNW_step() 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).
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
+ Application Registers in the set _UNW_AR_RSC, _UNW_AR_BSP,
_UNW_AR_BSPSTORE, _UNW_AR_RNAT, and _UNW_AR_PFS.
+ General registers in the range GR1 through GR31. Note that
many general registers are considered ``scratch'' general
registers. If scratch general registers are not initialized
by the client, subsequent _UNW_step() 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 Itanium
Processor Family Software Conventions and Runtime
Architecture 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.
+ 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 previous bullet
and _UNW_setCFM(3X).
Stepping [Toc] [Back]
Once initialization of the _Unwind_Context is complete, it now
represents the snapshot procedure's processor state. The client may
call _UNW_step(), which modifies _Unwind_Context to represent the
predecessor's processor state. See _UNW_step(3X).
Queries [Toc] [Back]
Querying register values by the client is allowed during all states.
Returned values are guaranteed valid only after certain actions,
however, as described below. Reading a register which is
uninitialized or marked invalid returns a value equivalent to zero
(0.0 for floating point registers, _UNW_FALSE from the enumeration
_UNW_Boolean for Predicates) and sets _Unwind_Context's AlertCode to
_UNW_QUERY_INVALID_ERROR. See ERROR CONDITIONS AND RECOVERY.
Requesting a General, Floating Point, Branch, Application, or
Predicate register by number outside the documented ranges returns a
value equivalent to zero and sets the _Unwind_Context's AlertCode to
_UNW_QUERY_RANGE_ERROR.
The following list indicates after which API calls specific register
values are valid. This ``validity list'' does not cover the
Initialization 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 Itanium Processor Family Software
Conventions and Runtime Architecture.
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
constant GR0
Value valid always.
special GR1 (global pointer)
Value valid after successful return from _UNW_step and
_UNW_currentContext.
scratch GR2-GR3, GR8-11 and GR14-GR31
Value valid only after _UNW_step() across a user space
interruption such as a signal handler.
preserved GR4-GR7
Value valid after successful return from _UNW_step and
_UNW_currentContext.
special GR12 (stack pointer)
Value valid after successful return from _UNW_step and
_UNW_currentContext.
special GR13 (thread pointer)
Value valid after successful return from _UNW_step and
_UNW_currentContext.
stacked GR32-127 (automatic RSE registers)
Value valid after successful return from _UNW_step and
_UNW_currentContext. Note: only those values existing
in the current frame (as depicted by the CFM value) are
valid. Alert code _UNW_QUERY_RANGE_ERROR 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 _UNW_step and
_UNW_currentContext.
scratch FR6-FR15 and FR32-FR127
Value valid only while in state User_Interrupted_Frame
after _UNW_step() 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 _UNW_step and
_UNW_currentContext.
scratch PR6-PR15
Value valid only while in state User_Interrupted_Frame
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
after _UNW_step() across a user space interruption such
as a signal handler.
scratch BR0 (return link)
Value valid only after _UNW_step() across a user space
interruption such as a signal handler.
Do not attempt to figure out the predecessor's
instruction pointer from BR0. Call _UNW_step() to
obtain the _Unwind_Context for the predecessor's frame
and use _UNW_getIP.
preserved BR1-BR5
Value valid after successful return from _UNW_step and
_UNW_currentContext.
scratch BR6-BR7
Value valid only while in state User_Interrupted_Frame
after _UNW_step() across a user space interruption such
as a signal handler.
application register FPSR
Value valid after successful return from _UNW_step and
_UNW_currentContext.
automatic application register _UNW_AR_RNAT
Value valid after successful return from _UNW_step and
_UNW_currentContext.
preserved application register _UNW_AR_UNAT
Value valid after successful return from _UNW_step and
_UNW_currentContext.
special application register _UNW_AR_PFS
Value valid after successful return from _UNW_step and
_UNW_currentContext.
read-only application register _UNW_AR_BSP
Value valid after successful return from _UNW_step and
_UNW_currentContext.
special application register _UNW_AR_BSPSTORE
Value valid after successful return from _UNW_step and
_UNW_currentContext.
application register _UNW_AR_RSC
The _UNW_AR_RSC application register is a special case.
It is marked valid but not updated during _UNW_step(),
because its values are only scratch and read-only.
Hewlett-Packard Company - 13 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
preserved application register _UNW_AR_LC
Value valid after successful return from _UNW_step and
_UNW_currentContext.
scratch application register _UNW_AR_CCV
Value valid only after _UNW_step() across a user space
interruption such as a signal handler.
Convenience value CFM
Value valid after successful return from _UNW_step and
_UNW_currentContext. Reminder: CFM (current frame
marker) is not architecturally visible. The stack
unwind library uses the same register layout as the
application register AR.PFS for this value.
Clearing for Re-Initialization [Toc] [Back]
The client may call _UNW_clear() from any states other than Bad,
Start, and Stop. On successful completion of _UNW_clear, the
_Unwind_Context object appears to be in the ``just constructed''
condition. All register values in the _Unwind_Context object are
invalidated and it is placed in the Init state.
ERROR CONDITIONS AND RECOVERY [Toc] [Back]
In order to allow clients a convenient way of checking for range
errors while initializing an _Unwind_Context or for sanity checking
for an error condition after several actions have been performed on an
_Unwind_Context object, two API functions are provided:
_UNW_getAlertCode and _UNW_clearAlertCode.
_UNW_getAlertCode() allows the client to obtain the most recent
``client needs to know'' _UNW_ReturnCode 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 _UNW_ReturnCode with the exception of _UNW_OK.
_UNW_clearAlertCode, _UNW_clear, _UNW_createContextForSelf(), and
_UNW_createContext() each reset the Alert Code to _UNW_OK although
_UNW_clear, _UNW_createContextForSelf(), and _UNW_createContext() can
set the Alert Code to _UNW_MEMORY_ALLOCATION_ERROR in the event of a
low memory condition.
Low Memory Conditions [Toc] [Back]
In most cases, a failed construction of an _Unwind_Context leaves the
client with enough of an _Unwind_Context object to support a call to
the function _UNW_getAlertCode(), which would return
_UNW_MEMORY_ALLOCATION_ERROR in the event of a failed construction.
Had the construction been successful, _UNW_getAlertCode() would have
returned _UNW_OK. Failed construction is sometimes communicated by
setting the _Unwind_Context pointer to NULL. Subsequent calls to
Hewlett-Packard Company - 14 - HP-UX 11i Version 2: August 2003
unwind(5) unwind(5)
Itanium(R)-based System Only
stack unwind library interface functions return
_UNW_MEMORY_ALLOCATION_ERROR if the _Unwind_Context pointer is NULL.
A failed memory allocation during actions such as _UWN_step() returns
the _UNW_MEMORY_ALLOCATION_ERROR return code and sets the
_Unwind_Context Alert Code. The remaining state of _Unwind_Context is
undefined.
Return Code Semantics [Toc] [Back]
The enumeration _UNW_ReturnCode has some embedded semantics. _UNW_OK
has value 0. Stack boundary conditions that indicate stack frames
through which the stack unwind library cannot step are assigned
negative values. For example, _UNW_STEP_BOTTOM and
_UNW_STEP_KERNEL_SAVE_STATE 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 [Toc] [Back]
_UNW_createContextForSelf(3X), U_STACK_TRACE(3X), _UNW_getGR(3X),
_UNW_currentContext(3X).
Hewlett-Packard Company - 15 - HP-UX 11i Version 2: August 2003 [ Back ] |
