unwind.5 (2010 09)

u
unwind(5) unwind(5)
(Itanium(R)-based Systems Only)
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
_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 per-
tinent 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, _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
_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 func-
tion 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 gen-
eral 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.
HP-UX 11i Version 3: September 2010 − 5 − Hewlett-Packard Company 5