HP-UX Reference (11i v2 03/08) - 5 Miscellaneous Topics, 7 Device (Special) Files, 9 General Information, Index (vol 9)

u
unwind(5) unwind(5)
(Itanium(R)-based System Only)
FEATURES
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 pur-
poses. 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 pro-
cedure 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 pro-
grammatic in order to hide the implementation details of data structures.
TYPE DEFINITIONS
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 asso-
ciated 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 Con-
ventions 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.
Section 5−−330 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: August 2003