 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
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
obj Specifies an object handle, as returned by the st_obj_open() function.
start
Specifies the address to which the functions return the handle of the
first file, procedure, or symbol.
count
Specifies the address to which the functions return the count of the
files, procedures, or symbols.
cur Specifies the handle of the current file, procedure, or symbol.
next
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:
1. Obtain the handle of the first entity (file, procedure or symbol),
using the appropriate st_*_start routine.
2. Obtain the number of the files, procedures, or symbols contained in
the object using the appropriate st_*_count routine.
3. Loop through the files, procedures, or symbols using the appropriate
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 routines
are used.
The individual routines are described in the following list:
st_obj_file_start
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.
st_obj_file_count
Returns the number of files in the specified object.
st_obj_file_next
Returns the handle of the file following cur in the specified object.
You can use this function as a means of indexing 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.
st_obj_proc_start
Returns the handle of the first procedure in the specified object. See
st_file_proc_start(3) for information on accessing the procedures in a
particular file of an executable object.
st_obj_proc_count
Returns the number of procedures in the object.
st_obj_proc_next
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.
st_obj_sym_start
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.
st_obj_sym_count
Returns the number of symbols in the specified object.
st_obj_sym_next
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.
st_obj_esym_* and st_obj_lsym_*
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 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 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
/usr/include/st.h
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|