uwx_find_symbol(3X) uwx_find_symbol(3X)
NAME
uwx_find_symbol() - obtain symbolic information from ELF files
SYNOPSIS
DESCRIPTION
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 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).
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 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. 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 function 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 avail-
able, 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 ALSO
dlgetname(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_register_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)