st_obj_file_start(3) Library Functions Manual 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.
LIBRARY
Symbol Table and Object File Access Library (libst.a)
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);
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.
Specifies 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 appropri-
ate st_*_start routine. Obtain the number of the files, procedures, or symbols contained in the object using the appropriate st_*_count
routine. Loop through the files, procedures, or symbols using the approprate 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: 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 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. 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.
Returns the number 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 speci-
fied 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 process-
ing as the st_obj_sym_* routines - except for distinguishing between the local and external symbol tables (which enables separate process-
ing 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 non-zero 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
RELATED INFORMATION
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)
delim off
st_obj_file_start(3)