st_obj_file_start(3)st_obj_file_start(3)NAME
st_obj_file_start, st_obj_file_count, st_obj_file_next,
st_obj_proc_start, st_obj_proc_count, st_obj_proc_next,
st_obj_sym_start, st_obj_sym_next, st_obj_sym_count, st_obj_lsym_start,
st_obj_lsym_next, st_obj_lsym_count, st_obj_esym_start,
st_obj_esym_next, st_obj_esym_count - access information about an
object's files, procedures, and symbols
SYNOPSIS
#include <st.h>
st_status_t st_obj_file_start(
st_obj_t *obj,
st_file_t *start ); st_status_t st_obj_file_count(
st_obj_t *obj,
unsigned int *count ); st_status_t st_obj_file_next(
st_obj_t *obj,
st_file_t cur,
st_file_t *next ); st_status_t st_obj_proc_start(
st_obj_t *obj,
st_proc_t *start ); st_status_t st_obj_proc_count(
st_obj_t *obj,
unsigned int *count ); st_status_t st_obj_proc_next(
st_obj_t *obj,
st_proc_t cur,
st_proc_t *next ); st_status_t st_obj_sym_start(
st_obj_t *obj,
st_sym_t *start ); st_status_t st_obj_sym_next(
st_obj_t *obj,
st_sym_t cur,
st_sym_t *next ); st_status_t st_obj_sym_count(
st_obj_t *obj,
unsigned int *count ); st_status_t st_obj_lsym_start(
st_obj_t *obj,
st_sym_t *start ); st_status_t st_obj_lsym_next(
st_obj_t *obj,
st_sym_t cur,
st_sym_t *next ); st_status_t st_obj_lsym_count(
st_obj_t *obj,
unsigned int *count ); st_status_t st_obj_esym_start(
st_obj_t *obj,
st_sym_t *start ); st_status_t st_obj_esym_next(
st_obj_t *obj,
st_sym_t cur,
st_sym_t *next ); st_status_t st_obj_esym_count(
st_obj_t *obj,
unsigned int *count );
LIBRARY
Symbol Table and Object File Access Library (libst.a)
PARAMETERS
Specifies an object handle, as returned by the st_obj_open() function.
Specifies the address to which the functions return the handle of the
first file, procedure, or symbol. Specifies the address to which the
functions return the count of the files, procedures, or symbols. Spec‐
ifies the handle of the current file, procedure, or symbol. Specifies
the address to which the functions return the handle of the next file,
procedure, or symbol.
DESCRIPTION
An object or executable can contain multiple files, procedures, and
symbols. These routines provide the interface for accessing each of
these entities sequentially. Separate interfaces are provided to allow
local and external symbols to be accessed independently.
The process for using these routines is as follows: Obtain the handle
of the first entity (file, procedure or symbol), using the appropriate
st_*_start routine. Obtain the number of the files, procedures, or
symbols contained in the object using the appropriate st_*_count rou‐
tine. Loop through the files, procedures, or symbols using the appro‐
priate st_*_next routine. In typical usage, the first time that the
st_*_next routine is called, the cur argument will be the handle
returned by the earlier call to st_*_start. In subsequent calls, the
cur argument will be the handle returned by the previous call to
st_*_next.
Refer to the program in libst_intro(3) for an example of how these rou‐
tines are used.
The individual routines are described in the following list: Returns
the handle of the first file in the specified object. You can use this
file handle to call other functions that return information about the
procedures, symbols, or lines in the file. Returns the number of files
in the specified object. Returns the handle of the file following cur
in the specified object. You can use this function as a means of index‐
ing through the files in an object. If cur equals or exceeds the number
of files in the specified object, st_obj_file_next returns
ST_E_FILE_RANGE and returns a value of -1 to the location to which next
points. Returns the handle of the first procedure in the specified
object. See st_file_proc_start(3) for information on accessing the pro‐
cedures in a particular file of an executable object. Returns the num‐
ber of procedures in the object. Returns the handle of the procedure
following cur in the specified object. You can use this function as a
means of indexing through the procedures in an object. If cur equals or
exceeds the number of procedures in the specified object,
st_obj_proc_next() returns ST_E_PROC_RANGE and returns a value of -1 to
the location to which next points. Returns the handle of the first
symbol in the specified object. See st_file_sym_start(3) for more
information on accessing symbols within a particular file. Returns the
number of symbols in the specified object. Returns the handle of the
symbol following sym in the specified object. You can use this function
as a means of indexing through the symbols in an object -- after
st_obj_sym_start() and st_obj_sym_count() have been called. If sym
equals or exceeds the number of symbols in the specified object,
st_obj_sym_next() returns ST_E_SYM_RANGE. Perform the same processing
as the st_obj_sym_* routines -- except for distinguishing between the
local and external symbol tables (which enables separate processing for
each portion of the symbol table). In a locally stripped object, the
external symbol table may be present without the local symbol table. In
this case, st_obj_sym_start() and st_obj_esym_start() will return the
same handle, and st_obj_lsym_start() will return ST_E_OBJ_LSTRIPPED.
If cur equals or exceeds the number of symbols in either the
local or external symbol tables, the st_obj_esym_next() and
st_obj_lsym_next() routines will return ST_E_SYM_RANGE.
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.
EXAMPLES
See libst_intro(3) for examples of the use of st_obj_file_* and
st_obj_proc_*.
FILES
Header file that contains all definitions and function prototypes for
libst.a functions
SEE ALSO
Commands: atom(1)
Functions: libst_intro(3), st_addr_to_file(3), st_file_lang(3),
st_obj_open(3), st_obj_calls(3), st_objlist_append(3), st_proc_addr(3),
st_sym_value(3)st_obj_file_start(3)
