|
|
st_objlist_append(3)
Contents
|
st_objlist_append, st_objlist_delete, st_objlist_first,
st_objlist_last, st_objlist_close, st_foreach_obj,
st_addr_to_obj, st_file_to_obj, st_proc_to_obj,
st_sym_to_obj, st_objlist_external_name_sym - create,
close, or perform operations on object lists
#include <st.h>
st_status_t st_objlist_append(
st_objlist_t **obj_list,
st_obj_t *obj ); st_status_t st_objlist_delete(
st_objlist_t **obj_list,
st_obj_t *obj ); st_status_t st_objlist_close(
st_objlist_t *obj_list ); st_status_t
st_objlist_first(
st_objlist_t *obj_list,
st_obj_t **obj ); st_status_t st_objlist_last(
st_objlist_t *obj_list,
st_obj_t **obj ); st_status_t st_addr_to_obj(
st_objlist_t *obj_list,
st_addr_t addr,
st_obj_t **result ); st_status_t st_file_to_obj
st_objlist_t *obj_list,
st_file_t file,
st_obj_t **result ); st_status_t st_proc_to_obj(
st_objlist_t *obj_list,
st_proc_t proc,
st_obj_t **result ); st_status_t st_sym_to_obj(
st_objlist_t *obj_list,
st_sym_t sym,
st_obj_t **result ); st_status_t st_objlist_external_name_sym(
st_objlist_t *obj_list,
const char *name,
st_sym_t *sym ); st_status_t st_foreach_obj(
st_objlist_t *obj_list,
st_status_t (*routine) __((st_obj_t *obj, st_any_t
data, st_any_t *retval)),
st_any_t data,
st_any_t *retval );
Symbol Table and Object File Access Library (libst.a)
For the st_objlist_append() function, specifies an address
to which the function returns a handle to the object list
it creates or augments. To create an object list, supply a
pointer to NULL for this parameter and an object handle
for the obj parameter. To append an object to an existing
object list, supply the object list handle for this parameter
and an object handle for the obj parameter. For all
other functions, specifies an object list handle. For the
st_objlist_append() function, specifies the handle of the
object to be appended to the specified object list or from
which the object list is to be created. For the
st_objlist_delete() function, specifies the handle of the
object to be deleted from the specified object list. For
the st_objlist_first() or st_objlist_last() function,
specifies an address to which the function returns a
handle to the first or last object in the specified object
list. Specifies a text, data, or bss address. Specifies
an address to which a given function returns the handle of
the object that contains the specified text, data, or bss
address (st_addr_to_obj), file handle (st_file_to_obj),
procedure handle (st_proc_to_obj), or symbol handle
(st_sym_to_obj). Specifies a file handle. Specifies a
procedure handle. For the st_sym_to_obj() function, specifies
a symbol handle. For the st_objlist_external_name_sym()
function, specifies an address to which the
function returns the handle of the first external symbol
among the objects in the specified object list that
matches the name of the specified global symbol. Specifies
the name of an external symbol. Specifies a routine
to be called for each object in the specified object list.
Specifies data to be input to or output from the routine
to be called for each object in the specified object list.
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 object
list, and ST_FOREACH_CONTINUE to continue to the next
object.
These functions create, close, or perform operations on
object lists: Either creates a list of objects or appends
an object to an existing object list. It either creates a
new object list (when you specify a NULL pointer in the
obj_list parameter) and sets obj_list to the new handle,
or appends the object to the specified object list.
Deletes an object from an object list. The obj_list parameter
is set to the modified object list. Calls
st_obj_close for each object in the specified object list,
and deallocates the memory used for maintaining the list.
Do not directly call st_obj_close() for any object that is
part of an object list. Return object handles for the
first and last objects, respectively, in the specified
object list. Return the handle of the object in the specified
object list that contains the specified address,
file, procedure, or symbol. Note that the st_addr_to_obj()
function cannot match a heap address to an object in a
running program. Searches the external symbols in each
object in the specified object list for a name that
matches the specified global symbol name and returns the
handle of the first matching symbol. Note that there may
be multiple external symbols with the same name in callshared
programs. This function returns the symbol from the
first object on the list that contains a matching name.
For C++ objects, st_objlist_external_name_sym() returns a
demangled name if name demangling is enabled for the
object in which the name is found. By default, objects
are opened with C++ name-demangling enabled. Provides a
means of calling a routine once for each object in the
specified object list. You must write the called routine
so that it returns 0 to terminate its execution within the
object list, and ST_FOREACH_CONTINUE to continue to the
next object.
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_obj() function returns ST_E_NULL_ARGUMENT
if a null object list 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 objects on the
list without a successful return from the called routine.
The following code segment shows how to create a list of
objects. The code assumes that object_names[] has been
previously initialized with the full pathnames of each
object, and that name_count contains the number of entries
in object_names[]. Note that the object list handle is
initialized to NULL before the first call to
st_objlist_append().
st_objlist_t *list = NULL; st_obj_t obj;
... for(i=0; i< name_count; i++) {
if((ret = st_obj_open(&obj, object_names[i],
ST_RDONLY))) {
printf("%s: Open ret = %d\n", object_names[i], ret);
exit(1);
}
if((ret = st_objlist_append(&list, obj))) {
printf(%s: Append ret = %d\n", object_names[i],
ret);
exit(1);
}
...
/* st_objlist_close calls st_obj_close for each object */
st_objlist_close(list);
The following code segment demonstrates the usage of
st_foreach_obj(3). The called routine checks if an address
falls in the text segment of an object.
st_status_t check_addr(st_obj_t *obj, st_any_t addr,
st_any_t *retval) {
st_status_t ret;
st_addr_t text_start;
st_addr_t text_size;
st_addr_t text_end;
if((ret = st_obj_text_start(obj, &text_start)))
return ret;
if((ret = st_obj_text_size(obj, &text_size)))
return ret;
text_end = text_start + text_size;
if(retval)
*retval = 0L;
else
/* null argument error */
/* If address falls in the text segment of */
/* this object, stop searching */
if((addr >= text_start) && (addr < text_end)) {
*retval = (st_any_t)obj;
return 0;
}
/* Check next object */
return ST_FOREACH_CONTINUE; }
main() {
st_objlist_t *olist;
st_addr_t addr;
st_status_t ret;
st_obj_t *obj;
...
/* object list previously created and "addr" set to an
address */
ret = st_foreach_obj(olist, check_addr, addr, (st_any_t
*)&obj);
if(ret == ST_OBJ_END)
/* No object was found containing the address */
else
/* obj is set to object handle containing the address
*/
...
Header file that contains all definitions and function
prototypes for libst.a functions Header file that controls
name-demangling operations for C++ objects
Commands: atom(1)
Functions: libst_intro(3), st_addr_to_file(3),
st_file_lang(3), st_obj_file_start(3), st_obj_open(3),
st_proc_addr(3), st_sym_value(3)
st_objlist_append(3)
[ Back ] |
