unwind.5 (2010 09)

u
unwind(5) unwind(5)
(Itanium(R)-based Systems 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 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 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.
2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010