uwx_find_source_info(3X)uwx_find_source_info(3X)NAMEuwx_find_source_info() - obtain source information from ELF files
SYNOPSISDESCRIPTION
is part of the Unwind Express Library for Integrity systems; see
uwx(3X). obtains source file and line number information for a given
IP (instruction pointer) from the symbolic information stored in the
ELF object file, if available. To use this interface, the name of the
load module and the relative offset of the IP from the beginning of
that module's text segment must be known. See dlmodinfo(3C) and dlget‐
name(3C) for information on obtaining information about load modules.
This entry point is provided for cases where an application may wish to
perform a quick stack unwind operation, saving only the IP values in an
array, then later produce a symbolic report. It may also be used inde‐
pendently of any stack unwind operation (note that an unwind environ‐
ment object must be provided, but it does not need to have a current
context). For obtaining source information while unwinding, see
uwx_get_sym_info(3X) and uwx_get_source_info(3X).
Parameters
env A pointer to an unwind environment object. The state of
the unwind environment does not matter except that the
allocate and free callback routines are used for memory
allocation.
cachep A pointer to a symbol cache pointer. The symbol cache
is an opaque object created and maintained within the
Unwind Express Library. If cachep is NULL, no symbol
cache will be created. If cachep is not NULL, it must
point to a pointer whose initial value is NULL. will
create a symbol cache and store a pointer to the cache
in for use on subsequent calls. The cache can be
released by calling The symbol cache may be shared with
mod The name of the load module. This must be the name of
an executable ELF object file (a main program or a
shared library).
relip The offset of the IP relative to the start of the load
module's text segment.
relfuncstart The offset of the start of the function containing the
IP, relative to the start of the load module's text seg‐
ment. If the function start address is not known, the
relip can be passed instead. (The advantage of knowing
the function start address is that symbol lookup can be
faster and more reliable.)
inline_context The value of the inline context identifier. This should
be 0 except when stepping through inlined calls.
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 of the
current context is not in an inlined call or if symbolic
debug information is not available, a NULL pointer will
be returned.
funcp Pointer to a variable of type char * where the function
name will be returned. If NULL, the function name will
not be returned. If the function name is not available,
a NULL pointer will be returned.
offsetp Pointer to a variable of type uint64_t where the func‐
tion offset will be returned (the difference between the
IP and the actual value of the function symbol located).
If NULL, the offset will not be returned. If the func‐
tion name is not available, an offset of 0 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 informa‐
tion 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 num‐
ber 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 con‐
text identifier will be returned. If NULL, the inline
context identifier will not be returned. If the IP of
the current context is not in an inlined call or if sym‐
bolic 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 again, this time passing
the previously-returned value of the inline context identifier as the
inline_context parameter. 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 ALSOdlgetname(3C), dlmodinfo(3C), uwx(3X), uwx_add_to_bsp(3X),
uwx_find_symbol(3X), uwx_free(3X), uwx_get_abi_context_code(3X),
uwx_get_funcstart(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_reg‐
ister_callbacks(3X), uwx_release_symbol_cache(3X), uwx_self_do_con‐
text_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_find_source_info(3X)
