HP-UX Reference (11i v2 07/12) - 5 Miscellaneous (vol 9)

u
unwind(5)
Itanium(R)-based Systems Only
unwind(5)
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 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 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 associ-
ated 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.
HP-UX 11i Version 2: December 2007 Update − 2 − Hewlett-Packard Company 483