st_objlist_append(3) Library Functions Manual st_objlist_append(3)
NAME
st_objlist_append, 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.
LIBRARY
Symbol Table and Object File Access Library (libst.a)
SYNOPSIS
#include <st.h>
st_status_t st_objlist_append (
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 );
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_first or t_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 func-
tion, 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.
The st_objlist_append function 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.
The st_objlist_close function calls st_obj_close for each object in the specified object list, and deallocates the memory used for main-
taining the list. Do not directly call st_obj_close for any object that is part of an object list.
The st_objlist_first and st_objlist_last functions return object handles for the first and last objects, respectively, in the specified
object list.
The st_addr_to_obj, st_file_to_obj, st_proc_to_obj, and st_sym_to_obj functions 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.
The st_objlist_external_name_sym function 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_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.
The st_foreach_obj function 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.
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
", object_names[i], ret);
exit(1);
}
if((ret = st_objlist_append(&list, obj)) {
printf(%s: Append ret = %d
", 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 */
...
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.
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.
FILES
header file that contains all definitions and function prototypes for libst.a functions header file that controls name-demangling opera-
tions for C++ objects
RELATED INFORMATION
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)
delim off
st_objlist_append(3)