Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > U

unwind(5)

Itanium(R)-based Systems Only
HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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 interrupting flow of control, saving almost the entire user-visible processor state, and giving control to a interruption handler function. We use two terms interrupted procedure and handler to describe the interruption 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, 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 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, 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 Runtime Architecture and terms defined in Section 5.1, Register Usage, and in Chapter 11, Stack Unwinding and Exception Handling.

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 programmatic 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 associated 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 Conventions 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.

_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.

_UNW_STEP_NO_DESCRIPTOR_FOR_NON_LEAF

The stack unwind library could not find an unwind descriptor for a procedure which the stack unwind library can prove is not a leaf procedure.

_UNW_STEP_CORRUPT_DESCRIPTOR

The unwind descriptor for the frame was misformed.

_UNW_STEP_RSE_NOT_FLUSHED

The register stack engine was not flushed.

_UNW_STEP_SIGNAL_CONTEXT

Error value returned while querying for an interruption's saved user context.

_UNW_STEP_NOT_ALLOWED_IN_STATE

A call to _UNW_step was made from one of the following states: Start, Bad, Kernel_Bottom_Frame. See subsection States below.

_UNW_INITIALIZATION_RANGE_ERROR

The client initialized outside of the allowed set of registers.

_UNW_QUERY_RANGE_ERROR

The client queried outside of the allowed set of registers.

_UNW_QUERY_INVALID_ERROR

The client queried a register marked invalid in the _Unwind_Context.

_UNW_SET_NOT_ALLOWED_IN_STATE

The client attempted to initialize values while the _Unwind_Context was not in the Init state.

_UNW_CURRENT_CONTEXT_FAILED

A generic problem occurred during a call to _UNW_currentContext.

_UNW_CURRENT_CONTEXT_NOT_ALLOWED_IN_STATE

The client called _UNW_currentContext from one of the following states: Start, Bad, Stop, Frame.

_UNW_MEMORY_ALLOCATION_ERROR

The stack unwind library cannot allocate enough memory to perform the function requested.

_UNW_CLEAR_NOT_ALLOWED_IN_STATE

The client called _UNW_clear from one of the following states: Start, Bad, Stop.

_UNW_QUERY_NOT_ALLOWED_IN_STATE

The client called _UNW_getKernelSavedContext while not in state Kernel_Bottom_Frame.

_UNW_INTERNAL_ERROR

Some logic problem occurred. Contact HP support.

_UNW_STEP_INTERRUPTION_ABI_MISMATCH

The stack unwind library encountered an incorrect abi field of a format P10 unwind descriptor. See Itanium Processor Family Software Conventions and Runtime Architecture, Section B.3: Descriptor Records for Prologue Regions.

The notion of TRUE and FALSE is communicated through an enumeration _UNW_Boolean which has enumerators _UNW_FALSE and _UNW_TRUE. _UNW_FALSE has value 0.

Integer values are communicated through types defined as follows:

  • uint32_t is an unsigned 32-bit integer.

  • 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 two fields of type uint32_t: p10_abi_value and p10_context_value.

  • Structure _UNW_FR_Value has two fields of type uint64_t: first_container and second_container.

  • Structure _UNW_GR_Value has a field of type uint64_t, value, and a field of type _UNW_Boolean, NaT.

The enumeration _UNW_AppReg is used by functions _UNW_getAR and _UNW_setAR when querying and setting values of application registers. _UNW_AppReg has enumerators _UNW_AR_RSC, _UNW_AR_BSP, _UNW_AR_BSPSTORE, _UNW_AR_RNAT, _UNW_AR_CCV, _UNW_AR_UNAT, _UNW_AR_FPSR, _UNW_AR_ITC, _UNW_AR_PFS, _UNW_AR_LC, _UNW_AR_EC, and _UNW_AR_LIST_COUNT.

_UNW_AR_FIRST_REG is a synonym for _UNW_AR_RSC.

COMMUNICATING AND LOCATING UNWIND INFORMATION

The definition of the Itanium-based unwind architecture is contained in Chapter 11 of Itanium Processor Family Software Conventions and Runtime Architecture. That document discusses the need for an unwind mechanism and the Runtime Architecture conventions that must be observed, and provides details about the layout and semantics of the unwind information blocks. It leaves environment-dependent details including the method of locating the unwind table to to be defined and handled by the Operating System environment. The stack unwind library handles these environment-dependent details for the client. Users interested in learning the environment-dependent details of the unwind information should refer to documents in the IA-64 Runtime Architecture Supplement series including the document entitled Processor-Specific ELF Supplement for IA-64.

Callbacks

In order to perform the task of stack unwinding, the stack unwind library needs to determine the text base, the unwind header location and the value of the global data pointer (general register GP) for any given load module (which is identified by any valid instruction address within the load module). Unwind functions such as U_STACK_TRACE() and the stack unwind library's exception handling support make use of dlmodinfo(3C) to obtain these values. Clients (such as debuggers) using the stack unwind library to perform a cross-process unwind need to register a function during the stack unwind library data structure construction to perform this lookup task in the place of dlmodinfo. The function has type _UNW_LoadMapFromIP. The semantics of and the interface to the lookup function are defined in _UNW_createContext(3X)

Furthermore, the stack unwind library needs the ability to read values from the target process memory (or memory image if the process is dead). Clients using the stack unwind library to perform a cross-process unwind need to register a function during data structure construction to perform memory reading tasks (in place of direct memory references). The function has type _UNW_ReadTargetMem. The semantics of and the interface to the memory reader function are defined in _UNW_createContext(3X).

CLIENT/LIBRARY INTERACTION

The steps a client takes to perform a stack unwind operation include

  • construction of an _Unwind_Context data structure

  • initialization of the _Unwind_Context

  • stepping the _Unwind_Context

  • querying the _Unwind_Context

  • possibly clearing and reinitialization the _Unwind_Context

  • finally, destruction of the _Unwind_Context.

Note: a client throwing an Exception uses a language independent API managed by the aCC standards committee. See ,CR http://www.codesourcery.com/cxx-abi/abi.html .

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. The states and possible transitions are:

Start

Prior to construction of the _Unwind_Context object.

From Start, the client may call _UNW_createContextForSelf and _UNW_createContext. They transfer the _Unwind_Context into either state Init or state Bad.

Bad

A state to indicate the _Unwind_Context is not usable. This state is entered after a failed attempt at construction — most likely due to a memory allocation error. This state can also be entered if the unwind library becomes hopelessly lost during unwinding — for example, after encountering a bad pointer value from an incorrectly initialized context.

With the exception of _UNW_destroyContext, the stack unwind library's behavior when in the Bad state is not defined. From state Bad, the client's safest recourse is to destroy the _Unwind_Context object via a call to _UNW_destroyContext, which transfers the _Unwind_Context into state Stop.

Init

The state in which the client is permitted to initialize the _Unwind_Context with pertinent user-visible processor state describing a given snapshot of a program's execution.

From Init, the client may call _UNW_setGR, _UNW_setGR_NaT, _UNW_setFR, _UNW_setBR, _UNW_setIP, _UNW_setAR, _UNW_setPR, _UNW_setPreds, _UNW_setCFM, _UNW_jmpbufContext, and _UNW_clear, none of which causes a state transition. The client may also call _UNW_step or _UNW_currentContext, which transfer the _Unwind_Context into state Frame or into state Bad. The client may call _UNW_destroyContext, which transfers the _Unwind_Context into state Stop.

Frame

The state in which the stack unwind library has produced or manipulated _Unwind_Context's description of the processor state through either _UNW_step or _UNW_currentContext. The client may query for and obtain valid values for most of the preserved register values. Most scratch register values are not valid in the Frame state. Note that use of the query functions are permitted in any state, but validity of the values returned is guaranteed only in certain states as listed in section Queries below.

From Frame, the client may call _UNW_currentContext, which transfers the _Unwind_Context into states Frame or Bad. It may call _UNW_step, which transfers the _Unwind_Context into states Frame, Bad, Kernel_Bottom_Frame, or User_Sendsig_Frame. The client may call _UNW_clear, which transfers the _Unwind_Context into state Init. The client may call _UNW_destroyContext, which transfers the _Unwind_Context into state Stop.

User_Sendsig_Frame

The state in which _Unwind_Context describes the processor state of a wrapper function through which the kernel calls the user's signal handler. See Itanium Processor Family Runtime Architecture Supplement, Signal Handling on HP-UX. From User_Sendsig_Frame, the client may call _UNW_currentContext, which transfers the _Unwind_Context into states Frame or Bad. It may call _UNW_step, which transfers the _Unwind_Context into states User_Interrupted_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.

User_Interrupted_Frame

The state in which the _Unwind_Context describes user code which was interrupted by a signal. The unique characteristic of this state is the client may query for and obtain valid values of scratch branch, scratch predicate, scratch floating point, and scratch general registers as well as for preserved registers. During a series of calls to _UNW_step, a frame associated with state User_Interrupted_Frame always follows a frame associated with state User_Sendsig_Frame.

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. The client may use _UNW_getKernelSavedContext while in this state. See _UNW_getKernelSavedContext(3X)

From Kernel_Bottom_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.

Stop

The _Unwind_Context has been discarded.

Construction

Construction is performed by a call to either _UNW_createContextForSelf or to _UNW_createContext. _UNW_createContextForSelf is primarily used when a process intends to unwind its own stack. _UNW_createContext is primarily used when a process intends to unwind a different process' stack or the stack of a dead process preserved in a core file. See _UNW_createContext(3X), _UNW_createContextForSelf(3X) and subsection Callbacks in section ACCESSING UNWIND INFORMATION above.

Initialization

The client's goal when the _Unwind_Context is in the Init state is to place a snapshot of the processor state at a given point of time into the _Unwind_Context. The snapshot consists of a set of required register values. The register stack engine (RSE) must be flushed at the time the snapshot is taken. See the flushrs instruction in the processor specification.

Initialization is only allowed while the _Unwind_Context is in the Init state.

Writes are always allowed to general registers 1-31, Floating Point Registers, Predicate Registers, Branch Registers, the Current Frame Marker (CFM), the Instruction Pointer (IP), and Application Registers in the set _UNW_AR_RSC, _UNW_AR_BSP, _UNW_AR_BSPSTORE, _UNW_AR_RNAT, _UNW_AR_CCV, _UNW_AR_UNAT, _UNW_AR_FPSR, _UNW_AR_ITC, _UNW_AR_PFS, _UNW_AR_LC. Writing to a particular register validates that value in the _Unwind_Context. Once the current frame marker (CFM) value is valid, writes to General Registers in the range GR32 through GR32 + CFM.sof are allowed (for the purpose of initializing an Itanium-based system's RSE stacked general registers in the snapshot procedure's RSE frame). A set to CFM invalidates the general registers in the range GR32 through GR127.

Of the above, the following values must be initialized (therefore validated) in order for subsequent calls to _UNW_step() to be successful:

  • The Instruction Pointer (IP). See _UNW_setIP(3X)

  • Preserved and scratch branch registers in the range BR0 through BR7.

  • Preserved and scratch predicate registers (PR1 through PR63).

  • Application Registers in the set _UNW_AR_RSC, _UNW_AR_BSP, _UNW_AR_BSPSTORE, _UNW_AR_RNAT, and _UNW_AR_PFS.

  • General registers in the range GR1 through GR31. Note that many general registers are considered "scratch" general registers. If scratch general registers are not initialized by the client, subsequent _UNW_step() calls are still likely (but not guaranteed) to succeed, because most procedures do not preserve values in Scratch registers. The general unwind descriptors defined in Table 11-13 of the Itanium Processor Family Software Conventions and Runtime Architecture do permit procedures to preserve values in Scratch registers, so for thoroughness, it is required that even the scratch general registers be initialized. The same is true for the scratch branch, predicate and floating point registers.

  • Preserved and scratch floating point registers.

  • 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. See _UNW_step(3X).

Queries

Querying register values by the client is allowed during all states. Returned values are guaranteed valid only after certain actions, however, as described below. Reading a register which is uninitialized or marked invalid returns a value equivalent to zero (0.0 for floating point registers, _UNW_FALSE from the enumeration _UNW_Boolean for Predicates) and sets _Unwind_Context's AlertCode to _UNW_QUERY_INVALID_ERROR. See ERROR CONDITIONS AND RECOVERY. Requesting a General, Floating Point, Branch, Application, or Predicate register by number outside the documented ranges returns a value equivalent to zero and sets the _Unwind_Context's AlertCode to _UNW_QUERY_RANGE_ERROR.

The following list indicates after which API calls specific register values are valid. This "validity list" does not cover the Initialization phase (that is, when the stack unwind library is in state Init) during which only those values which the client has initialized are valid. The registers are listed by their register classes as defined in Chapter 5 of Itanium Processor Family Software Conventions and Runtime Architecture.

constant GR0

Value valid always.

special GR1 (global pointer)

Value valid after successful return from _UNW_step and _UNW_currentContext.

scratch GR2-GR3, GR8-11 and GR14-GR31

Value valid only after _UNW_step() across a user space interruption such as a signal handler.

preserved GR4-GR7

Value valid after successful return from _UNW_step and _UNW_currentContext.

special GR12 (stack pointer)

Value valid after successful return from _UNW_step and _UNW_currentContext.

special GR13 (thread pointer)

Value valid after successful return from _UNW_step and _UNW_currentContext.

stacked GR32-127 (automatic RSE registers)

Value valid after successful return from _UNW_step and _UNW_currentContext. Note: only those values existing in the current frame (as depicted by the CFM value) are valid. Alert code _UNW_QUERY_RANGE_ERROR is set when values outside of the current frame are queried.

constant FR0 and FR1

Value valid always.

preserved FR2-FR5 and FR16-FR31

Value valid after successful return from _UNW_step and _UNW_currentContext.

scratch FR6-FR15 and FR32-FR127

Value valid only while in state User_Interrupted_Frame after _UNW_step() across a user space interruption such as a signal handler.

constant P0

Value valid always.

preserved PR1-PR5 and PR16-PR63

Value valid after successful return from _UNW_step and _UNW_currentContext.

scratch PR6-PR15

Value valid only while in state User_Interrupted_Frame after _UNW_step() across a user space interruption such as a signal handler.

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.

scratch BR6-BR7

Value valid only while in state User_Interrupted_Frame after _UNW_step() across a user space interruption such as a signal handler.

application register FPSR

Value valid after successful return from _UNW_step and _UNW_currentContext.

automatic application register _UNW_AR_RNAT

Value valid after successful return from _UNW_step and _UNW_currentContext.

preserved application register _UNW_AR_UNAT

Value valid after successful return from _UNW_step and _UNW_currentContext.

special application register _UNW_AR_PFS

Value valid after successful return from _UNW_step and _UNW_currentContext.

read-only application register _UNW_AR_BSP

Value valid after successful return from _UNW_step and _UNW_currentContext.

special application register _UNW_AR_BSPSTORE

Value valid after successful return from _UNW_step and _UNW_currentContext.

application register _UNW_AR_RSC

The _UNW_AR_RSC application register is a special case. It is marked valid but not updated during _UNW_step(), because its values are only scratch and read-only.

preserved application register _UNW_AR_LC

Value valid after successful return from _UNW_step and _UNW_currentContext.

scratch application register _UNW_AR_CCV

Value valid only after _UNW_step() across a user space interruption such as a signal handler.

Convenience value CFM

Value valid after successful return from _UNW_step and _UNW_currentContext. Reminder: CFM (current frame marker) is not architecturally visible. The stack unwind library uses the same register layout as the application register AR.PFS for this value.

Clearing for Reinitialization

The client may call _UNW_clear() from any states other than Bad, Start, and Stop. On successful completion of _UNW_clear, the _Unwind_Context object appears to be in the "just constructed" condition. All register values in the _Unwind_Context object are invalidated and it is placed in the Init state.

ERROR CONDITIONS AND RECOVERY

In order to allow clients a convenient way of checking for range errors while initializing an _Unwind_Context or for sanity checking for an error condition after several actions have been performed on an _Unwind_Context object, two API functions are provided: _UNW_getAlertCode and _UNW_clearAlertCode.

_UNW_getAlertCode() allows the client to obtain the most recent "client needs to know" _UNW_ReturnCode returned (or "encountered" in the case of the query functions) by an interface function since the last clear of the Alert Code.

"Client needs to know" return codes are all of the enumerators in the enumeration _UNW_ReturnCode with the exception of _UNW_OK.

_UNW_clearAlertCode, _UNW_clear, _UNW_createContextForSelf(), and _UNW_createContext() each reset the Alert Code to _UNW_OK although _UNW_clear, _UNW_createContextForSelf(), and _UNW_createContext() can set the Alert Code to _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. Failed construction is sometimes communicated by setting the _Unwind_Context pointer to NULL. Subsequent calls to stack unwind library interface functions return _UNW_MEMORY_ALLOCATION_ERROR if the _Unwind_Context pointer is NULL.

A failed memory allocation during actions such as _UWN_step() returns the _UNW_MEMORY_ALLOCATION_ERROR return code and sets the _Unwind_Context Alert Code. The remaining state of _Unwind_Context is undefined.

Return Code Semantics

The enumeration _UNW_ReturnCode has some embedded semantics. _UNW_OK has value 0. Stack boundary conditions that indicate stack frames through which the stack unwind library cannot step are assigned negative values. For example, _UNW_STEP_BOTTOM and _UNW_STEP_KERNEL_SAVE_STATE have negative values. All other return values in the enumeration have positive values. Hewlett-Packard reserves the right to add more return codes to the enumeration. For compatibility reasons, none will be removed, nor will the values assigned to existing return codes be changed in future releases.

SEE ALSO

_UNW_createContextForSelf(3X), _UNW_currentContext(3X), _UNW_getGR(3X), U_STACK_TRACE(3X).

Itanium Processor Family Runtime Architecture Supplement

Itanium Processor Family Software Conventions and Runtime Architecture

Processor-Specific ELF Supplement for IA-64

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.