uwx_find_symbol(3X)uwx_find_symbol(3X)NAMEuwx_find_symbol() - obtain symbolic information from ELF files
SYNOPSISDESCRIPTION
is part of the Unwind Express Library for Integrity systems; see
uwx(3X). obtains symbolic information for a given IP (instruction
pointer) from the symbol tables 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 dlgetname(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).
This entry point returns a subset of the information returned by
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. If the offset of the start of
the function is available, it may be used here to
improve the speed and reliability of the symbol lookup.
(The offset returned through the offsetp parameter would
then be the difference between the symbol found and the
address passed in, which will usually be 0.)
funcp Pointer to a variable of type char * where the function
name will be returned. The returned function name is
allocated within the unwind environment, and the pointer
is valid only until the next call to either or 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 (the difference between the IP and the
actual value of the function symbol located) will be
returned. If NULL, the offset will not be returned. If
the function name is not available, an offset of 0 will
be returned.
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_source_info(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_symbol(3X)