uwx_get_source_info(3x) [hpux man page]
uwx_get_source_info(3X) uwx_get_source_info(3X) NAME
uwx_get_source_info() - return source information for current frame SYNOPSIS
DESCRIPTION
is part of the Unwind Express Library for Integrity systems; see uwx(3X). obtains source file and line number information for the current frame from the symbolic information stored in the ELF object file, if available. This entry point is provided for use immediately following a call to or For other situations, see uwx_find_source_info(3X). Parameters env A pointer to an unwind environment object. ifuncp Pointer to a variable of type char * where the inlined function name will be returned. If NULL, the inlined function name will not be returned. If the IP (instruction pointer) of the current context is not in an inlined call or if symbolic debug information is not available, a NULL pointer will be returned. srcfilep Pointer to a variable of type char * where the source file name will be returned. If NULL, the source file name will not be returned. If symbolic debug information is not available, a NULL pointer will be returned. linenump Pointer to a variable of type int where the source line number will be returned. If NULL, the source line number will not be returned. If symbolic debug information is not available, 0 will be returned. inline_contextp Pointer to a variable of type int where the inline context identifier will be returned. If NULL, the inline context identi- fier will not be returned. If the IP of the current context is not in an inlined call or if symbolic debug information is not available, 0 will be returned. In all cases where a pointer to a string is returned, the string is allocated within the unwind environment, and the pointer is valid only until the next call to either or Stepping through inlined calls If returns a non-zero inline context identifier, it indicates that the IP is located within an inline call. If the application wishes to step through the chain of inlined calls, it can find the name of the inlined function through the ifuncp pointer, then call to move one step up the chain of inlined calls. The application may then call again to obtain the updated information. This process should be repeated until the returned identifier is 0. RETURN VALUE
returns on success. See uwx(3X) for error codes. AUTHOR
The Unwind Express Library was developed by Hewlett-Packard. SEE ALSO
uwx(3X), uwx_add_to_bsp(3X), uwx_find_source_info(3X), uwx_find_symbol(3X), uwx_free(3X), uwx_get_abi_context_code(3X), uwx_get_func- start(3X), uwx_get_module_info(3X), uwx_get_nat(3X), uwx_get_reg(3X), uwx_get_sym_info(3X), uwx_init(3X), uwx_init_context(3X), uwx_regis- ter_alloc_cb(3X), uwx_register_callbacks(3X), uwx_release_symbol_cache(3X), uwx_self_do_context_frame(3X), uwx_self_free_info(3X), uwx_self_init_context(3X), uwx_self_init_info(3X), uwx_set_nofr(3X), uwx_set_remote(3X), uwx_step(3X), uwx_step_inline(3X). Integrity Systems Only uwx_get_source_info(3X)
Check Out this Related Man Page
uwx(3X) uwx(3X) NAME
uwx() - Unwind Express Library SYNOPSIS
[flag... ] file... [library] ... DESCRIPTION
The Unwind Express Library is a lightweight library for unwinding a process stack on Integrity systems. It may be used for "self-unwind- ing," where a thread traces back through its own stack, or for "cross-unwinding," where a debugger or other tool can examine the stack of another target thread or process. To use the Unwind Express Library, link your application with the option on the compiler or linker command line. All source code should include the header file Source code that uses the library for self-unwinding should also include the header file The Unwind Express Library maintains its entire state within a single unwind environment structure. To unwind a stack, the client applica- tion provides an initial context to the unwind environment, then unwinds the stack one frame at a time. After reaching the bottom of the stack, the unwind environment may be reused for a subsequent unwind operation simply by providing a new initial context, or it may be dis- carded, freeing the memory it was using. A client application may create any number of separate unwind environments, and each one will operate independently of and completely unaf- fected by the others. The Unwind Express Library consists of a core unwind engine that can be adapted to specific environments through the use of callback rou- tines. For self-unwinding, a set of standard callback routines are provided as part of the library. For cross-unwinding, the client must supply callback routines to interface the unwind engine to the target thread or process. Self-Unwinding To prepare for self-unwinding, a client application must perform the following steps to create and initialize a new unwind environment: 1. Call to create a new unwind environment. The return value is a pointer to the unwind environment. 2. Call to initialize the standard callback environment. The return value is a pointer to the callback info structure. 3. Call to register the standard callbacks: and The steps above may be performed at any time in advance of performing a stack unwind. The resulting unwind environment can then be used repeatedly. To perform a stack unwind from some point in the application, the client must perform the following steps: 1. Call to provide the current thread's context as a starting point for unwinding. The stack frame for the caller of this function becomes the current frame. 2. Call to step back one frame in the call stack. After each step, the new frame becomes the current frame, and the client may call to obtain values from the reconstructed context for the new frame. This step can be repeated until the process reaches the bottom of the stack or a signal context frame. 3. When a signal context frame is reached, the client may call to provide a new starting point for unwinding based on the context at the point of interruption. The stack frame for the function interrupted by the signal becomes the current frame. Subsequent calls to will proceed from there. Cross-Unwinding To prepare for cross-unwinding, a client application must perform the following steps to create and initialize a new unwind environment: 1. Call to create a new unwind environment. The return value is a pointer to the unwind environment. 2. Call to setup the unwind environment for cross unwinding. This call also allows the client to specify the byte order (little-endian or big-endian) of the target process. 3. Call to register the client-provided callback functions. See uwx_register_callbacks(3X) for information on writing callback routines. The steps above may be performed at any time in advance of performing a stack unwind. The resulting unwind environment can then be used repeatedly. To perform a stack unwind, the client must perform the following steps: 1. Call to provide the basic initial context as a starting point for unwinding. This initial context consists of the values of ip (instruction pointer), sp (stack pointer), bsp (backing store pointer), and cfm (current frame marker). The frame described by these values becomes the current frame. If the unwind engine needs values from additional registers in the target thread's context, it will request them as needed through the callback interface. 2. Call to step back one frame in the call stack. After each step, the new frame becomes the current frame, and the client may call to obtain values from the reconstructed context for the new frame. This step can be repeated until the process reaches the bottom of the stack or a signal context frame. 3. When a signal context frame is reached, the client may call to obtain the abi and context parameters recorded in the unwind descrip- tors for the frame. This routine returns the two values in a single int as ((abi << 8) | context). It should then call again to pro- vide a new starting point for unwinding based on the context at the point of interruption. The stack frame for the function inter- rupted by the signal becomes the current frame. Subsequent calls to will proceed from there. Obtaining Information From the Current Frame's Context Registers from the current frame may be read using and The starting address of the current function may be obtained by calling Symbolic information may be obtained, if available, for the current frame's IP by calling and ERRORS
For the APIs that return pointer values, a NULL pointer indicates a memory allocation error; otherwise a pointer to an opaque object is returned. For other APIs, an integer status code is returned. These codes are listed here. Request successfully completed. hit a signal context frame. hit bottom of stack. The cached information returned by the lookup-ip callback was invalid. The "Lookup IP" callback returned an invalid key in the result vector. The register id is invalid. The unwind information block contains an invalid descriptor. The unwind engine is unable to unwind from the current frame because of an unsupported descriptor. There was an error reading a value from the memory stack. There was an error reading a register from the initial context. There was an error reading a value from the register stack backing store. There was an error reading the unwind information block. There was an error reading the unwind table. No module information was found for the current frame's IP. The "Lookup IP" callback encountered an error. No callback routines have been registered. No initial context has been supplied. The env parameter is NULL. An attempt to allocate additional memory failed. No symbolic information was found. An unwind information block was found, but it does not describe the current frame's IP. No unwind information block was found for the current frame's IP. The unwind information block is invalid -- the nesting of prologue regions is not balanced. An unidentified error was received from the uc_access(3) library. The unwind information block is invalid -- an undefined label is referenced. EXAMPLES
The following code fragment performs a stack unwind in the current thread: LIMITATIONS
The Unwind Express Library currently does not recognize X-format unwind descriptors. These are not currently used by HP compilers. AUTHOR
The Unwind Express Library was developed by Hewlett-Packard. SEE ALSO
uc_access(3), uwx_add_to_bsp(3X), uwx_find_source_info(3X), uwx_find_symbol(3X), uwx_free(3X), uwx_get_abi_context_code(3X), uwx_get_func- start(3X), uwx_get_module_info(3X), uwx_get_nat(3X), uwx_get_reg(3X), uwx_get_source_info(3X), uwx_get_sym_info(3X), uwx_init(3X), uwx_init_context(3X), uwx_register_alloc_cb(3X), uwx_register_callbacks(3X), uwx_release_symbol_cache(3X), uwx_self_do_context_frame(3X), uwx_self_free_info(3X), uwx_self_init_context(3X), uwx_self_init_info(3X), uwx_set_nofr(3X), uwx_set_remote(3X), uwx_step(3X), uwx_step_inline(3X). Integrity Systems Only uwx(3X)