Index for Section 3

Alphabetical listing for S

Bottom of page

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

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

  addr	    Specifies 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).

  file	    Specifies a file handle.

  proc	    Specifies a procedure handle.

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

  name	    Specifies the name of an external symbol.

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

  data	    Specifies 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.

  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 maintaining 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\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 */
	   ...

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

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)

Index for Section 3

Alphabetical listing for S

Top of page