 |
» |
|
|
|
NAMEunwind — overview of stack unwind library entry points and convenience macros DESCRIPTIONThe
<unwind.h>
header defines the Application Programming Interface (API) of the stack unwind
library, supplied as
libunwind.so
for HP-UX on the Itanium Processor Family.
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 IA-64 executable files which are not
covered in
Itanium Processor Family Software Conventions and Runtime Architecture
and related documents. CONCEPTS AND DEFINITIONS OF TERMSOne 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 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. FEATURESThe 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_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
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 DEFINITIONSReturn 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 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. - _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 sub-section
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.
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 INFORMATIONThe definition of the IA-64 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. CallbacksIn 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 cross-process 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 INTERACTIONThe 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. StatesA 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
_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 user-visible 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,
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
_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
_UNW_destroyContext,
which transfers the
_Unwind_Context
into state
Stop. - Stop
The
_Unwind_Context
has been discarded.
ConstructionConstruction is performed by a call to either
_UNW_createContextForSelf
or to
_UNW_createContext.
_UNW_createContextForSelf
is used when a process intends to unwind its own stack.
_UNW_createContext
is 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. InitializationThe 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
IA-64 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_set_IP(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
_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).
SteppingOnce 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). QueriesQuerying 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.
- 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
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. - 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-InitializationThe 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 RECOVERYIn 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 ConditionsIn 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
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 SemanticsThe 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. |
Printable version
