st_addr_to_file(3)st_addr_to_file(3)NAME
st_addr_to_file, st_addr_to_proc, st_addr_to_line, st_addr_to_sym,
st_data_addr_to_sym, st_text_addr_to_sym - convert an address in an
object to a file handle, procedure handle, line number, or symbol han‐
dle and offset
SYNOPSIS
#include <st.h>
st_status_t st_addr_to_file(
st_obj_t *obj,
st_addr_t addr,
st_file_t *file ); st_status_t st_addr_to_proc(
st_obj_t *obj,
st_addr_t addr,
st_proc_t *proc ); st_status_t st_addr_to_line(
st_obj_t *obj,
st_addr_t addr,
st_line_t *line ); st_status_t st_addr_to_sym(
st_obj_t *obj,
st_addr_t addr,
st_sym_t *sym,
int *byte_offset ); st_status_t st_data_addr_to_sym(
st_obj_t *obj,
st_addr_t addr,
st_sym_t *sym,
int *byte_offset ); st_status_t st_text_addr_to_sym(
st_obj_t *obj,
st_addr_t addr,
int *byte_offset,
st_sym_t *sym );
LIBRARY
Symbol Table and Object File Access Library (libst.a)
PARAMETERS
Specifies an object handle, as returned by the st_obj_open() function.
Specifies a text address from the object. Specifies an address to
which st_addr_to_file() writes the handle of the file containing the
specified text address. Specifies an address to which
st_addr_to_proc() writes the handle of the procedure containing the
specified text address. Specifies an address to which
st_addr_to_line() writes the source line number corresponding to the
specified text address. Specifies an address to which
st_addr_to_sym(), st_data_addr_to_sym(), or st_text_addr_to_sym()
writes the handle of the symbol lower or equal to the specified
address. Specifies an address to which st_addr_to_sym(),
st_data_addr_to_sym(), or st_text_addr_to_sym() writes the difference
between the specified address and the address of the symbol indicated
by sym.
DESCRIPTION
These functions convert an address in an object to a file handle, pro‐
cedure handle, line number, or symbol handle and offset:
Returns the file handle corresponding to the specified text address.
Returns the handle of the procedure containing the specified text
address. If the procedure contains alternate entry points, the function
returns the handle of the entry point that has the nearest address pre‐
ceding the specified text address. Returns the source line number cor‐
responding to the specified text address. Returns the handle of a sym‐
bol with an address lower or equal to the specified address and a byte
offset that is set to the difference between the specified address and
the address of the symbol. Returns the handle of a symbol with an
address lower or equal to the specified data address and a byte offset
that is set to the difference between the specified data address and
the address of the symbol.
Use the st_data_addr_to_sym() function on initialized and unini‐
tialized data only (that is, for addresses that fall in the data
or bss segments of the object). You cannot use
st_data_addr_to_sym() on local variables or for data allocated
on the heap -- for example, data allocated with malloc().
Because the specified data address may fall in padding between
variables, st_data_addr_to_sym() may return a symbol that does
not actually contain the specified data address. To determine if
this is the case, specify the returned symbol handle in calls to
st_sym_value() or st_sym_size() to obtain the address and size
of the symbol. Returns the handle of a symbol with an address
lower or equal to the specified text address and a byte offset
that is set to the difference between the specified text address
and the address of the symbol.
Use the st_text_addr_to_sym() function on text and read-only
data only (that is, for addresses that fall in the text segment
of the object). You cannot use st_text_addr_to_sym() on local
variables.
RETURN VALUES
All functions indicate success by returning a value of 0 (zero). A pos‐
itive return value is an errno value from a system call. A negative
return value is a library error or informational code. The library
codes are documented in st.h.
Return parameters are set to 0 or -1 when an error occurs. Address
parameters are set to 0 while file and procedure handles are set to -1.
An exception to this is if a NULL pointer for the object or other
return parameter is input. In these cases, the return parameters will
be unchanged. A nonzero return status is the recommended method for
detecting an error return from a libst function.
FILES
Header file that contains all definitions and function prototypes for
libst.a functions Header file that controls name-demangling operations
for C++ objects
SEE ALSO
Commands: atom(1)
Functions: libst_intro(3), st_file_lang(3), st_obj_file_start(3),
st_obj_open(3), st_objlist_append(3), st_proc_addr(3), st_sym_value(3)
Programmer's Guide
st_addr_to_file(3)
