 |
» |
|
|
|
NAMEuwx_find_source_info() — obtain source information from ELF files SYNOPSIS#include <uwx.h>
int uwx_find_source_info(
struct uwx_env *env,
struct uwx_symbol_cache **cachep,
char *mod,
uint64_t relip,
uint64_t relfuncstart,
int inline_context,
char **ifuncp,
char **funcp,
uint64_t *offsetp,
char **srcfilep,
int *linenump,
int *inline_contextp
); DESCRIPTIONuwx_find_source_info()
is part of the Unwind Express Library for Integrity systems; see
uwx(3X).
uwx_find_source_info()
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
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). 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.
uwx_find_source_info()
will create a symbol cache and store a pointer to the cache in
*cachep
for use on subsequent calls.
The cache can be released by calling
uwx_release_symbol_cache().
The symbol cache may be shared with
uwx_find_symbol(). - 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 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 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
identifier 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
uwx_step()
or
uwx_free(). Stepping through inlined callsIf
uwx_find_source_info()
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
uwx_find_source_info()
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 VALUEuwx_find_source_info()
returns
UWX_OK
on success.
See
uwx(3X)
for error codes. AUTHORThe 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_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).
|
Printable version
