HP-UX Reference (11i v3 07/02) - 5 Miscellaneous Topics (vol 9)

u
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 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. 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 files 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 procedure
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 finishes executing statements, its caller resumes execution 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 flow 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 interrup-
tion 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 suc-
cessor 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, first-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 ini-
tialize 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 pos-
sibly for performance, profile-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 defined 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 Run-
time Architecture and terms defined in Section 5.1, Register Usage, and in Chapter 11, Stack Unwinding
and Exception Handling.
HP-UX 11i Version 3: February 2007 − 1 − Hewlett-Packard Company 529