 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
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_foreach_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
obj Specifies an object handle, as returned by the st_obj_open() function.
proc
Specifies a procedure handle, as returned by a function such as
st_obj_proc_start().
alt Specifies an address to which st_is_alternate_entry() returns a Boolean
value of TRUE if the specified procedure is an alternate entry or a
nested routine.
proc_addr
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.
sym Specifies an address to which st_proc_sym() returns the symbol handle
for the specified procedure.
name
Specifies an address to which st_proc_name() returns the null-
terminated string of the procedure name.
file
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.
sline
Specifies an address to which st_proc_start_line() writes the starting
line number for the specified procedure. This number identifies the
line in the source file at which the procedure is defined.
eline
Specifies an address to which st_proc_end_line() writes the ending line
number for the specified 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 ending line of the procedure containing the specified
procedure to this location.
line
Specifies a line number that st_check_proc_line_range() is to determine
is within the range of lines within the specified procedure.
oproc
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.
pstart
Specifies an address to which st_proc_sorted_start() the handle of the
first procedure in the sorted procedure table created by its implicit
call of (or prior explicit call to) st_proc_sort().
result
For the st_proc_sorted_next function, specifies an address to which the
function returns the procedure that follows proc in the sorted
procedure table. For the st_foreach_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_CONTINUE to continue to the next procedure.
routine
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_foreach_obj_proc_sorted()).
data
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 procedure table
(st_foreach_obj_proc_sorted()).
DESCRIPTION
These functions return information about a procedure or perform operations
on the procedures in an object or file:
st_is_alternate_entry
Determines whether the specified procedure is an alternate entry or
nested routine.
st_proc_addr
Returns the starting address of the procedure as it would reside in
memory when the object is executing.
st_proc_sym
Returns the symbol handle for the specified procedure.
st_proc_name
Returns the null-terminated string of the procedure name. Because the
returned procedure name is for read-access only, the calling program
should make any modifications to a copy of this string.
st_proc_to_file
Returns the handle of the file that contains the specified procedure.
st_proc_start_line and st_proc_end_line
Return the numbers of the line in the source file at which the
procedure 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
procedure, st_outer_proc_end_line() returns the line at which the
specified procedure ends.
st_check_proc_line_range
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_foreach_obj_proc(),
st_foreach_obj_proc_sorted() to operate on all the procedures 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.
st_proc_sort, st_proc_sorted_start, and st_proc_sorted_next
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 table
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 ascending
address order.
Note that some objects may have multiple procedures at the same
address.
st_obj_proc_count
Determines the number of procedures in an object or sorted procedure
table.
st_foreach_proc, st_foreach_obj_proc, and
st_foreach_obj_proc_sorted
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 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.
The st_foreach_proc(), st_foreach_obj_proc(), and
st_foreach_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
/usr/include/st.h
Header file that contains all definitions and function prototypes for
libst.a functions
/usr/include/cmplrs/demangle_string.h
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|