st_proc_addr(3)st_proc_addr(3)NAME
st_is_alternate_entry, st_proc_addr, st_proc_sym, st_proc_name,
st_proc_to_file, st_proc_start_line, st_proc_end_line,
st_outer_proc_end_line, st_check_proc_line_range, st_proc_sort,
st_proc_sorted_start, st_proc_sorted_next, st_foreach_proc, st_fore‐
ach_obj_proc, st_foreach_proc_sorted - access information about the
procedures in an object
SYNOPSIS
#include <st.h>
st_status_t st_is_alternate_entry(
st_obj_t *obj,
st_proc_t proc,
st_bool_t *alt ); st_status_t st_proc_addr(
st_obj_t *obj,
st_proc_t proc,
st_addr_t *proc_addr ); st_status_t st_proc_sym(
st_obj_t *obj,
st_proc_t proc,
st_sym_t *sym ); st_status_t st_proc_name(
st_obj_t *obj,
st_proc_t proc,
char **name ); st_status_t st_proc_to_file(
st_obj_t *obj,
st_proc_t proc,
st_file_t *file ); st_status_t st_proc_start_line(
st_obj_t *obj,
st_proc_t proc,
st_line_t *sline ); st_status_t st_proc_end_line(
st_obj_t *obj,
st_proc_t proc,
st_line_t *eline ); st_status_t st_outer_proc_end_line(
st_obj_t *obj,
st_proc_t proc,
st_line_t *eline ); st_status_t st_check_proc_line_range(
st_obj_t *obj,
st_proc_t proc,
unsigned long line,
st_proc_t *oproc ); st_status_t st_proc_sort(
st_obj_t *obj ); st_status_t st_proc_sorted_start(
st_obj_t *obj,
st_proc_t *pstart ); st_status_t st_proc_sorted_next(
st_obj_t *obj,
st_proc_t proc,
st_proc_t *result ); st_status_t st_foreach_proc(
st_obj_t *obj,
st_file_t file,
st_status_t (*routine) __((st_obj_t *obj, st_proc_t proc,
st_any_t data, st_any_t *result)),
st_any_t data,
st_any_t *result ); st_status_t st_foreach_obj_proc(
st_obj_t *obj,
st_status_t (*routine) __((st_obj_t *obj, st_proc_t proc,
st_any_t data, st_any_t *result)),
st_any_t data,
st_any_t *result ); st_status_t st_foreach_obj_proc_sorted(
st_obj_t *obj,
st_status_t (*routine) __((st_obj_t *obj, st_proc_t proc,
st_any_t data, st_any_t *result)),
st_any_t data,
st_any_t *result );
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 procedure handle, as returned by a function such as
st_obj_proc_start(). Specifies an address to which st_is_alter‐
nate_entry() returns a Boolean value of TRUE if the specified procedure
is an alternate entry or a nested routine. Specifies an address to
which st_proc_addr() returns the starting address of the procedure as
it would reside in memory when the object is executing. Specifies an
address to which st_proc_sym() returns the symbol handle for the speci‐
fied procedure. Specifies an address to which st_proc_name() returns
the null-terminated string of the procedure name. Specifies an address
to which st_proc_to_file() returns the handle of the file that contains
the specified procedure, or a file handle that st_foreach_proc() uses
to locate procedures for which to run the specified routine. Specifies
an address to which st_proc_start_line() writes the starting line num‐
ber for the specified procedure. This number identifies the line in the
source file at which the procedure is defined. Specifies an address to
which st_proc_end_line() writes the ending line number for the speci‐
fied procedure. This number identifies the line in the source file at
which the procedure ends. If the specified procedure is an alternate
entry or a nested procedure, st_outer_proc_end_line() returns the end‐
ing line of the procedure containing the specified procedure to this
location. Specifies a line number that st_check_proc_line_range() is
to determine is within the range of lines within the specified proce‐
dure. Specifies an address to which st_check_proc_line_range() returns
a procedure handle if the specified line number is within the range of
lines in the specified procedure, or -1 if it is not. Specifies an
address to which st_proc_sorted_start() the handle of the first proce‐
dure in the sorted procedure table created by its implicit call of (or
prior explicit call to) st_proc_sort(). For the st_proc_sorted_next
function, specifies an address to which the function returns the proce‐
dure that follows proc in the sorted procedure table. For the st_fore‐
ach_proc(), st_foreach_obj_proc(), and st_foreach_obj_proc_sorted()
functions, specifies an address to receive the return value from the
specified routine. The called routine must be written to return 0 to
terminate its execution within the procedure list, and ST_FOREACH_CON‐
TINUE to continue to the next procedure. Specifies a routine to be
called for each procedure in the specified file (st_foreach_proc()),
object (st_foreach_obj_proc()), or sorted procedure table (st_fore‐
ach_obj_proc_sorted()). Specifies data to be input to or output from
the routine to be called for each object in the specified file
(st_foreach_proc()), object (st_foreach_obj_proc()), or sorted proce‐
dure table (st_foreach_obj_proc_sorted()).
DESCRIPTION
These functions return information about a procedure or perform opera‐
tions on the procedures in an object or file: Determines whether the
specified procedure is an alternate entry or nested routine. Returns
the starting address of the procedure as it would reside in memory when
the object is executing. Returns the symbol handle for the specified
procedure. Returns the null-terminated string of the procedure name.
Because the returned procedure name is for read-access only, the call‐
ing program should make any modifications to a copy of this string.
Returns the handle of the file that contains the specified procedure.
Return the numbers of the line in the source file at which the proce‐
dure is defined and the line at which the procedure ends, respectively.
The st_outer_proc_end_line() function returns the ending line number of
the procedure that contains the specified procedure, and is used for
procedures that are alternate entries or nested procedures. If the
specified procedure is neither an alternate entry or a nested proce‐
dure, st_outer_proc_end_line() returns the line at which the specified
procedure ends. Determines whether the specified line number is within
the range of lines in the specified procedure. If the line number is
within range, the function returns the procedure handle. If not, it
returns -1 to the location to which oproc points. Use
st_check_proc_line_range() when calling st_foreach_proc(), st_fore‐
ach_obj_proc(), st_foreach_obj_proc_sorted() to operate on all the pro‐
cedures in a given file, object, or sorted procedure list. The line
parameter is defined as unsigned long to allow it to be used for this
purpose. The st_proc_sort() function creates a table of procedures
sorted by increasing address order. It includes all procedures in the
specified object in the sorted procedure table. The sorted procedure
table enables faster search operations on the procedure addresses by
other routines. Any libst routines that require a sorted procedure ta‐
ble implicitly call st_proc_sort() if the table does not already exist.
The st_proc_sorted_start() function returns the handle of the first
procedure in the sorted procedure table. The st_proc_sorted_next()
function returns the handle of the procedure that follows proc in the
sorted procedure table.
NOTE
Use the st_obj_proc_start() and st_obj_proc_next() functions to
access procedures in the order that they appear in the object,
that is, in their link order. Use the st_proc_sorted_start() and
st_proc_sorted_next() functions to access procedures in ascend‐
ing address order.
Note that some objects may have multiple procedures at the same
address. Determines the number of procedures in an object or
sorted procedure table. Provide a means of calling a routine
once for each procedure in the specified file, object, or sorted
procedure table. You must write the called routine so that it
returns 0 to terminate its execution within the procedure list,
and ST_FOREACH_CONTINUE to continue to the next procedure.
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.
The st_foreach_proc(), st_foreach_obj_proc(), and st_fore‐
ach_obj_proc_sorted() functions return ST_E_NULL_ARGUMENT if a null
object handle or routine pointer are supplied. It returns a value of 0
(zero) when the called routine returns 0 to it. Otherwise, it returns
ST_OBJ_END to indicate that it has reached the end of the procedures
without a successful return from the called routine.
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_addr_to_file(3), st_file_lang(3),
st_obj_open(3), st_obj_file_start(3), st_objlist_append(3),
st_sym_value(3)st_proc_addr(3)
