_UNW_currentContext(3X)

NAME

_UNW_currentContext(), _UNW_clear(), _UNW_jmpbufContext(), _UNW_setAR(), _UNW_setBR(), _UNW_setCFM(), _UNW_setFR(), _UNW_setGR(), _UNW_setGR_NaT(), _UNW_setIP(), _UNW_setPR(), _UNW_setPreds(), _UNW_step(), _UNW_FR_PhysicalNumber(), _UNW_GR_PhysicalNumber(), _UNW_PR_PhysicalNumber() — manipulate values in unwind library data structure

SYNOPSIS

#include <unwind.h> 

_UNW_ReturnCode _UNW_currentContext(_Unwind_Context* p); 

_UNW_ReturnCode _UNW_clear(_Unwind_Context* p); 

_UNW_ReturnCode _UNW_jmpbufContext(_Unwind_Context* p, 
                 jmp_buf env); 

_UNW_ReturnCode _UNW_setGR(_Unwind_Context* p, 
                 uint32_t num, 
                 uint64_t value); 

_UNW_ReturnCode _UNW_setGR_NaT(_Unwind_Context* p, 
                 uint32_t num, 
                 uint64_t value, 
                 _UNW_Boolean NaTval); 

_UNW_ReturnCode _UNW_setFR(_Unwind_Context* p, 
                 uint32_t num, 
                 uint64_t first_container, 
                 uint64_t second_container); 

_UNW_ReturnCode _UNW_setBR(_Unwind_Context* p, 
                 uint32_t num, 
                 uint64_t value); 

_UNW_ReturnCode _UNW_setAR(_Unwind_Context* p, 
                 _UNW_AppReg num, 
                 uint64_t value); 

_UNW_ReturnCode _UNW_setPR(_Unwind_Context* p, 
                 uint32_t num, 
                 _UNW_Boolean value); 

_UNW_ReturnCode _UNW_setPreds(_Unwind_Context* p, 
                 uint64_t value); 

_UNW_ReturnCode _UNW_setIP(_Unwind_Context* p, 
                 uint64_t value); 

_UNW_ReturnCode _UNW_setCFM(_Unwind_Context* p, 
                 uint64_t value); 

uint32_t _UNW_GR_PhysicalNumber(_Unwind_Context* p, 
                 uint32_t logical_num); 

uint32_t _UNW_FR_PhysicalNumber(_Unwind_Context* p, 
                 uint32_t logical_num); 

uint32_t _UNW_PR_PhysicalNumber(_Unwind_Context* p, 
                 uint32_t logical_num); 

_UNW_ReturnCode _UNW_step(_Unwind_Context* p); 

DESCRIPTION

_UNW_currentContext() initializes the _Unwind_Context object to describe the processor state of the procedure which is calling _UNW_currentContext— in other words, the processor state of "self."

_UNW_jmpbufContext() initializes the _Unwind_Context object to describe the processor state captured in a jmp_buf by a call to setjmp() (see setjmp(3C)).

_UNW_clear() resets the _Unwind_Context object to the "just constructed" condition. All register values in the _Unwind_Context are invalidated. The unwind library is placed in the Init state meaning the client can now use the _UNW_set routines to initialize values in the _Unwind_Context. The Init state is discussed further in unwind(5).

_UNW_setGR() initializes the value of numbered general register num to value in the _Unwind_Context pointed to by parameter p. The NAT bit for the register is set to _UNW_FALSE.

_UNW_setGR_NaT() initializes the value of a numbered general register num to value in the _Unwind_Context pointed to by parameter p. The NAT bit for the register is set to NaTval

_UNW_setFR() initializes the value of a numbered floating point register, num, in the _Unwind_Context pointed to by parameter p, to the value image represented in parameters first_container and second_container. These two containers represent the two consecutive double words of the Floating point register Spill/Fill memory format. See Intel IA-64 Architecture Software Developer's Manual, Volume 1: IA-64 Application Architecture, "Section 5.3: Floating Point Instructions".

_UNW_setBR() initializes the value of numbered branch register num to value in the _Unwind_Context pointed to by parameter p.

_UNW_setAR() initializes the value of enumerated application register num to value in the _Unwind_Context pointed to by parameter p. The enumeration type _UNW_AppReg is used for accessing application registers.

_UNW_setPR() initializes the value of a numbered predicate register num, in the _Unwind_Context pointed to by parameter p, to value, which is one of _UNW_TRUE or _UNW_FALSE.

_UNW_setPreds() initializes the value of all predicate registers in the _Unwind_Context pointed to by parameter p to a representation passed in value. value contains the contents of each predicate register in the bit corresponding corresponding to the predicate register number; for instance, bit 63 contains the contents (1 or 0) for predicate register 63.

_UNW_setIP() initializes the value of the instruction pointer to value in the _Unwind_Context pointed to by parameter p. value must be a full 64-bit address. That means that any 32-bit pointer values from the 32-bit address space must be swizzled before being passed to _UNW_setIP(). See Itanium Processor Family Runtime Architecture Supplement: 32-Bit Runtime Architecture for HP-UX, "Section 1: Memory Model".

_UNW_setCFM() initializes the value of the current frame marker (CFM) to value in the _Unwind_Context pointed to by parameter p. Refer to Intel IA-64 Architecture Software Developer's Manual, Volume 1: IA-64 Application Architecture, "Section 3.1.7 Current Frame Marker". The current frame marker contains the sizes of the various portions of the stack frame. It also specifies three Register Rename Base values (used in register rotation). The current frame marker is not an architecturally visible value. It is used by the unwind library while initializing an _Unwind_Context for unwinding to provide the initial _Unwind_Context with a picture of the Register Stack Engine (RSE) (specifically how many stacked general registers registers from the range GR32 to GR127 are in the current frame) and any register base rotations in effect. A client program can construct a current frame marker value by several means:

A procedure wanting to unwind itself can call a "current state" collection procedure whose purpose is to fill in an _Unwind_Context structure which describes its own state. That procedure (if written in assembly) can use knowledge of its own register usage to craft the current frame marker value.
A tool (such as a debugger) wishing to unwind a process other than itself that it has interrupted (for instance, by setting a break point) can piece together the current frame marker value from the interruption context produced by the interruption event. See Intel IA-64 Architecture Software Developer's Manual, Volume 2: IA-64 System Architecture, "Chapter 5: IA-64 Interruptions".

_UNW_GR_PhysicalNumber(), _UNW_FR_PhysicalNumber(), and _UNW_PR_PhysicalNumber() for the _Unwind_Context pointed to by parameter p return the physical register number corresponding to the logical register number, logical_num. The distinction between physical and logical register number is explained below in subsection INTERACTION BETWEEN INITIALIZER FUNCTIONS.

INTERACTION BETWEEN INITIALIZER FUNCTIONS

The stack unwind library requires that calls to these setter functions occur only during the Init state (and the Pre-install state while handling a conforming ANSI C++ standards exception). The state constraints are discussed in unwind(5).

The transition into the Init state happens when _UNW_clear(), _UNW_createContextForSelf(), or _UNW_createContext() is called. In the Init state, _UNW_set... calls are allowed to initialize values in the _Unwind_Context of General Registers 1-31, scratch and preserved Floating Point Registers, scratch and preserved Predicate Registers, Branch Registers 0-7, IP, CFM, and Application Registers in the set RSC, BSP, BSPSTORE, RNAT, CCV, UNAT, FPSR, ITC, PFS, LC. Writing to a particular register validates that value in the _Unwind_Context. A call to _UNW_setCFM invalidates the _Unwind_Context's general register values in the range GR32..GR127 and validates the _Unwind_Context's current frame marker (CFM) value. Once the CFM value is valid writes to General Registers in the range, GR32 through GR32 + CFM.sof are allowed (for the purpose of initializing RSE stacked general registers in the current procedure's RSE frame).

A specific set of registers listed in the unwind(5) INITIALIZATION section must be validated in order for a call to _UNW_step() to be successful.

Any initialization of register values not specifically listed in the previous paragraph is not allowed. For instance initialization of the constant registers (GR0, FR0, FR1, PR0) are not allowed. Violating this rule results in the _Unwind_Context alert code set to _UNW_INITIALIZATION_RANGE_ERROR and the _UNW_set... function returning _UNW_INITIALIZATION_RANGE_ERROR.

Attempts to initialize an _Unwind_Context object which is in a state where initialization of values is not allowed causes no change to the value in _Unwind_Context. It results in a return alert code of _UNW_SET_NOT_ALLOWED_IN_STATE. See also unwind(5).

The unwind library register value initializer functions refer to registers by their physical numbers as opposed to the mapped (logical) numbers associated with rotations indicated in CFM.sor, CFM.rrb.gr, CFM.rrb.pr, CFM.rrb.fr. The stack unwind library defines the physical number to be the register number the value would lie in should the appropriate CFM.rrb field have value 0.

The mapping functions _UNW_GR_PhysicalNumber, _UNW_FR_PhysicalNumber, and _UNW_PR_PhysicalNumber return the physical register number to pass to the _UNW_get... initializer functions to access a given logical register. Passing a mapping function a logical number which is outside of the range of mapped logical numbers returns 0 and sets the _UNW_QUERY_RANGE_ERROR alert condition. For example, calling _UNW_GR_PhysicalNumber(uc,42) while CFM.sor is 0 sets the alert condition. The contents of the _Unwind_Context object's CFM should be initialized prior to using the mapping functions.

_UNW_step modifies the _Unwind_Context pointed to by parameter p to represent the predecessor's processor state.

RETURN VALUE

_UNW_set... returns _UNW_SET_NOT_ALLOWED_IN_STATE when _Unwind_Context is in a state where initialization of values is not allowed. States in which initialization is allowed are Init and Pre_Install. See Error conditions and recovery in the manpage unwind(5).

_UNW_set... returns _UNW_INITIALIZATION_RANGE_ERROR on an attempt to initialize a register for which initialization is forbidden. See the subsection INTERACTION BETWEEN INITIALIZER FUNCTIONS above. Otherwise _UNW_set... returns _UNW_OK on successful completion.

_UNW_clear returns _UNW_OK on successful completion. Otherwise _UNW_clear returns _UNW_CLEAR_NOT_ALLOWED_IN_STATE when _Unwind_Context is not in one of the following states: Init, User_Interrupted_Frame, User_Sendsig_Frame, Kernel_Bottom_Frame, Frame. See unwind(5).

_UNW_GR_PhysicalNumber, _UNW_FR_PhysicalNumber, and _UNW_PR_PhysicalNumber each return a register number. They return 0 (along with the side effect of setting the _Unwind_Context alert code to _UNW_QUERY_RANGE_ERROR) if passed a logical number which is outside of the range of mapped logical numbers for that register class.

_UNW_step produces the following return codes:

_UNW_STEP_KERNEL_SAVE_STATE

Indicates _Unwind_Context describes a frame beyond which the stack unwind library can no longer step. Any HP_UX kernel interruption frame other than the one associated with _user_sendsig() which supports user signal handling (see signal(5)) results in this return value.

_UNW_STEP_BOTTOM

Indicates _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. This return code indicates the _Unwind_Context is in state Bad. See unwind(5) section STATES.

_UNW_INTERNAL_ERROR

Some logic problem occurred during step. Contact HP support.

_UNW_STEP_INVALID_IP

The instruction pointer value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_SP

The stack pointer value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_GR

A general register value which was marked invalid was encountered in _Unwind_Context during the step process. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_PFS

The AR.PRS value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_RSC

The AR.RSC value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_BSP

The AR.BSP value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_BSPSTORE

The AR.BSPSTORE value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_CFM

The AR.CFM value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_BR

A branch register value which was marked invalid was encountered in _Unwind_Context during the step process. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_BAD_BSP_ALIGNMENT

The _UNW_currentContext value ar.BSP was not aligned. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_INVALID_RNAT

The AR.RNAT value in _Unwind_Context is marked invalid. The probable cause is a failure to initialize it. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_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. All non-leaf procedures are required to have unwind descriptors. Some but not all possible causes for this include

code that does not conform to the coding conventions specified in Itanium Processor Family Software Conventions and Runtime Architecture, "Chapter 11.3 Coding conventions for reliable unwinding".
failure of a _UNW_LoadMapFromIP callback function (see unwind(5)) to identify the location of the unwind header or text segment base
corrupted system memory
initialization of the _Unwind_Context with incorrect values

_UNW_STEP_CORRUPT_DESCRIPTOR

The unwind descriptor for the frame was mis-formed. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_STEP_RSE_NOT_FLUSHED

The register stack engine was not flushed. See unwind(5). This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).

_UNW_currentContext has the following return codes:

_UNW_OK: All's well.
_UNW_CURRENT_CONTEXT_FAILED: A generic problem occurred during a call to _UNW_currentContext.
_UNW_STEP_CORRUPT_DESCRIPTOR: The unwind descriptor for the frame was mis-formed. This return code indicates the _Unwind_Context is in state Bad. See the STATES section in unwind(5).
_UNW_MEMORY_ALLOCATION_ERROR: The stack unwind library cannot allocate enough memory to perform the function requested. _Unwind_Context is in state Bad. See unwind(5).
_UNW_INTERNAL_ERROR: Some logic problem occurred during step. Contact HP support.

ERRORS

_UNW_currentContext fails gracefully (that is, returns an appropriate error) if there is not enough memory to perform the initialization or a library interaction problem (for example, calls to the service manager or dlmodinfo) prevents unwindlib from performing the initialization.

EXAMPLES

Initialize the value of General Register 5 to 400:

#include <unwind.h> 
main() { 
    _Unwind_Context *uc; 
    _UNW_ReturnCode retcode; 
    uc = _UNW_createContextForSelf(); 
    if ((retcode = _UNW_setGR(uc,5,400)) != _UNW_OK) { 
         /* Notify client: Initialization problem  */ 
    } 
} 

AUTHOR

_UNW_currentContext(), _UNW_clear(), _UNW_jmpbufContext(), _UNW_setAR(), _UNW_setBR(), _UNW_setCFM(), _UNW_setFR(), _UNW_setGR(), _UNW_setGR_NaT(), _UNW_setIP(), _UNW_setPR(), _UNW_setPreds(), _UNW_step(), _UNW_FR_PhysicalNumber(), _UNW_GR_PhysicalNumber(), and _UNW_PR_PhysicalNumber() were developed by HP.

_UNW_currentContext(3X)

Technical documentation

» Table of Contents

» Index