st_objlist_append(3)st_objlist_append(3)NAME
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_exter‐
nal_name_sym - create, close, or perform operations on object lists
SYNOPSIS
#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 );
LIBRARY
Symbol Table and Object File Access Library (libst.a)
PARAMETERS
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 han‐
dle. 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.
DESCRIPTION
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 modi‐
fied 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 call-shared programs.
This function returns the symbol from the first object on the list that
contains a matching name. For C++ objects, st_objlist_exter‐
nal_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 execu‐
tion within the object list, and ST_FOREACH_CONTINUE to continue to the
next object.
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_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.
EXAMPLES
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 */
...
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_file_start(3), st_obj_open(3), st_proc_addr(3), st_sym_value(3)st_objlist_append(3)
