unwind.5 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

unwind(5) unwind(5)

(Itanium(R)-based Systems Only)

NAME

unwind: unwind.h - overview of stack unwind library entry points and convenience macros

SYNOPSIS

#include <unwind.h>

DESCRIPTION

The <unwind.h> header deﬁnes the Application Programming Interface (API) of the stack unwind

library, supplied as libunwind.so for HP-UX on Itanium-based systems. This manpage 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 manpages describing unwind library entry points. This manpage

also explains the format of the unwind header and some details of the unwind tables contained within

Itanium-based executable ﬁles which are not covered in Itanium Processor Family Software Conventions

and Runtime Architecture and related documents.

CONCEPTS AND DEFINITIONS OF TERMS

One 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 pro-

cedure 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 ﬁnishes executing statements, its caller resumes exe-

cution with the next statement following the call.

One of the basic features of multitasking operating systems is the interruption event, the act of interrupt-

ing ﬂow of control, saving almost the entire user-visible processor state, and giving control to a interrup-

tion handler function. We use two terms interrupted procedure and handler to describe the interr-

uption 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, ﬁrst-

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, proﬁle-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 deﬁned 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 manpages assume familiarity with Itanium Processor Family Software Conventions and

Runtime Architecture and terms deﬁned in Section 5.1, Register Usage, and in Chapter 11, Stack

Unwinding and Exception Handling .

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (10 pages)

PAGE 1
unwind(5) unwind(5) (Itanium(R)-based Systems Only) NAME unwind: unwind.h - overview of stack unwind library entry points and convenience macros SYNOPSIS #include DESCRIPTION The header defines the Application Programming Interface (API) of the stack unwind library, supplied as libunwind.so for HP-UX on Itanium-based systems. This manpage discusses the general concepts of stack unwinding and how the stack unwind library is intended to be used.
PAGE 2
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).
PAGE 3
unwind(5) unwind(5) (Itanium(R)-based Systems Only) _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.
PAGE 4
unwind(5) unwind(5) (Itanium(R)-based Systems Only) 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 p10_abi_value and p10_context_value. two fields Structure _UNW_FR_Value has two fields of type uint64_t: second_container.
PAGE 5
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.
PAGE 6
unwind(5) unwind(5) (Itanium(R)-based Systems Only) 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.
PAGE 7
unwind(5) unwind(5) (Itanium(R)-based Systems Only) • 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). Stepping Once 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.
PAGE 8
unwind(5) unwind(5) (Itanium(R)-based Systems Only) 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.
PAGE 9
unwind(5) unwind(5) (Itanium(R)-based Systems Only) _UNW_MEMORY_ALLOCATION_ERROR in the event of a low memory condition. Low Memory Conditions In 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.
PAGE 10
(Notes) A (Notes) uA 10 Hewlett-Packard Company −1− HP-UX 11i Version 3: September 2010