st_addr_to_file(3) Library Functions Manual st_addr_to_file(3)
NAME
st_addr_to_file, st_addr_to_proc, st_addr_to_line, st_data_addr_to_sym - Convert an address in an object to a file handle, procedure han-
dle, line number, or symbol handle and offset.
LIBRARY
Symbol Table and Object File Access Library (libst.a)
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_data_addr_to_sym (st_obj_t *obj,
st_addr_t addr,
st_sym_t *sym,
int *byte_offset );
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_Data_addr_to_sym writes the symbol handle of the
data variable lower or equal to the specified text address. Specifies an address to which st_data_addr_to_sym writes the difference
between the specified text address and the start of the data symbol indicated by sym.
DESCRIPTION
The st_addr_to_file, st_addr_to_proc, st_addr_to_line, and st_data_addr_to_sym functions convert an address in an object to a file handle,
procedure handle, line number, or symbol handle and offset.
The st_addr_to_file function returns the file handle corresponding to the specified text address.
The st_addr_to_proc function returns the handle of the procedure containing the specified text address. If the procedure contains alter-
nate entry points, the function returns the handle of the entry point that has the nearest address preceding the specified text address.
The st_addr_to_line function returns the source line number corresponding to the specified text address.
The st_data_addr_to_sym function returns the symbol handle of the data or variable 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 start of the data symbol.
Notes
Use the st_data_addr_to_sym function on initialized and uninitialized data only (that is, for addresses that fall in the data or bss seg-
ments 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 text address may fall in padding between variables, st_data_addr_to_sym may return a symbol that does not actually
contain the specified text 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.
RETURN VALUES
All functions indicate success by returning a value of 0 (zero). A positive 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 non-zero 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 opera-
tions for C++ objects
RELATED INFORMATION
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)
delim off
st_addr_to_file(3)