st_objlist_append(3) — Subroutines

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_external_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

obj_list
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.

objFor 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.

addrSpecifies a text, data, or bss address.

result
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).

fileSpecifies a file handle.

procSpecifies a procedure handle.

symFor 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.

name
Specifies the name of an external symbol.

routine
Specifies a routine to be called for each object in the specified object list.

dataSpecifies data to be input to or output from the routine to be called for each object in the specified object list.

retval
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:

st_objlist_append
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.

st_objlist_delete
Deletes an object from an object list. The obj_list parameter is set to the modified object list.

st_objlist_close
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.

st_objlist_first and st_objlist_last
Return object handles for the first and last objects, respectively, in the specified object list.

st_addr_to_obj, st_file_to_obj, st_proc_to_obj, and st_sym_to_obj
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.

st_objlist_external_name_sym
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.

st_foreach_obj
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.

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_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

/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

Museum

Related Articles