uwx_find_source_info(3X) uwx_find_source_info(3X)
NAME
uwx_find_source_info() - obtain source information from ELF files
SYNOPSIS
DESCRIPTION
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 independently of any stack unwind operation (note that an unwind
environment 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 ini-
tial 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 segment. 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 function 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 function name is not avail-
able, 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 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 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 ALSO
dlgetname(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_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_find_source_info(3X)