libst_intro(3)						     Library Functions Manual						    libst_intro(3)

NAME

       libst_intro, libst - Symbol table and object file access library

SYNOPSIS

       #include <st.h>

DESCRIPTION

       libst.a	contains a collection of functions for accessing object file data and symbol table information.  These functions effectively insu-
       late the calling program from knowledge of the overall structure of the object file.  An object can be a file with a .o suffix, a nonshared
       or call-shared executable, or a shared library.	The libst function can also be used to access objects in archive libraries.

       The  libst.a  functions	are particularly useful for developing tools that must access file, procedure, symbol, or line number information.
       They can assist in the development of Atom-based tools for application performance tuning and debugging.  (See atom(1) for more information
       on the Atom tool kit.)

       The  header  file /usr/include/st.h contains all definitions and function prototypes needed for utilizing libst.a functions.  Some applica-
       tions may also need to include the <cmplrs/demangle_string.h> header file to  control  name-demangling  operations  for	C++  objects.	By
       default, name demangling is enabled by libst when an object is opened.

       Functions allow you to manage both a single object and lists of objects.  Object lists are useful when a call-shared object and one or more
       shared libraries that it uses must be available simultaneously.

       Interface routines provide access to object file header information and the symbol table.  The symbol table contains information on  source
       files,  procedures,  symbols, symbol type/class/size information, and lines.  Address look-up routines are provided for text, data, and bss
       addresses.  Access is provided where applicable to obtain information at the list, object, and source file  level.  For	example,  you  can
       obtain  the  number  of	procedures  in	an  entire object, or the number of procedures in a particular file.  Functions return handles for
       objects, files, procedures, and symbols.

       libst functions are reentrant but not threadsafe. The calling program must synchronize thread access to objects or lists of  objects.   You
       should  serialize  access  to  an  object  list whenever an object is appended or when the object list is closed.  At the object level, you
       should serialize calls to st_proc_sort, for instance. If a thread changes name demangling for an object, then you should both set the name-
       demangling flag and perform the name translation before another thread makes a name-translation call, such as st_sym_name.  Generally, most
       calls to libst are read requests and do not require synchronization.

EXAMPLES

       The following code example shows how to use libst routines to list the file and procedure names in an object file.

       The build command for this program is:

       cc -g test.c -o test -lst -lmld

       This command ensures that libst will use any newer C++ demangler that has been installed along with a C++ compiler. The program	is  linked
       as  a  call-shared program, so the demangler in libmld.a loads libdemangle.so dynamically using ldopen(3), and it runs the shared library's
       demangler if that one is newer. To link a non-shared program so that libst uses a newer (or older) demangler  in  libdemangle.a,  use  this
       build command:

       cc -non_shared test.c -o test -lst -all -qldemangle -none -lmld
	 #include <st.h>

	 main(int argc, char **argv)
	 {
	    st_status_t ret;
	    st_obj_t *obj;
	    st_file_t file;
	    st_proc_t proc;
	    unsigned int fcount;
	    unsigned int pcount;
	    char *fname;
	    char *pname;
	    st_bool_t stripped;
	    st_addr_t paddr;
	    int i, j;

	    if(argc < 2) {
	       printf("Usage: test object_name
");
	       exit(1);
	    }

	    /* Open the object.  For C++, name demangling is enabled
	     * when an object is successfully opened.
	     */
	    if((ret = st_obj_open(&obj, argv[1], ST_RDONLY))) {
	       printf("open ret = %d
",ret);
	       exit(1);
	    }

	    /* If the object is stripped, exit since no symbolic
	     * information is available.
	     */
	    st_is_obj_stripped(obj, &stripped);
	    if(stripped) {
	       printf("Object %s is stripped
", argv[1]);
	       exit(0);
	    }
	    /* Get handle for first file in the object and the count
	     * of files.
	     */
	    st_obj_file_start(obj, &file);
	    st_obj_file_count(obj, &fcount);

	    /* Loop through the files in the object, printing the
	     * procedures contained in each.  File names and static
	     * procedure names are unavailable for files that were not
	     * compiled with -g.
	     */
	    for(i = 0; i < fcount; i++) {
	       st_is_file_locally_stripped(obj, file, &stripped);
	       if(stripped)
		  printf("File is locally stripped - name is unavailable:
");
	       else {
		  st_file_name(obj, file, &fname);
		  printf("File %s:
", fname);
	       }
	       /* Get handle for first procedure for this file, and the
		* count of procedures in the file.
		*/
	       st_file_proc_start(obj, file, &proc);
	       st_file_proc_count(obj, file, &pcount);

	       /* Loop through the procedures for the file, printing the
		* procedure name if available.	Static procedure names are not
		* available, for example, if the file was not compiled with -g.
		*/
	       for(j=0; j < pcount; j++) {
		  st_file_t fi;
		  char *fn;

		  /* If name lookup fails, get the procedure address */
		  if((ret = st_proc_name(obj, proc, &pname)))
		     st_proc_addr(obj, proc, &paddr);
		  if(!ret)
		     printf("	Procedure %s
", pname);
		  else
		     printf("	Procedure at 0x%p
",paddr);
		  st_file_proc_next(obj, file, proc, &proc);
	       }
	       st_obj_file_next(obj, file, &file);
	    }
	    ret = st_obj_close(obj);
	    if (ret) {
	       printf("close ret = %d
",ret);
	       exit(1);
	    }
	    exit (0);
	 }

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, and file and procedure handles are set to  -1.
       An  exception  to this occurs when 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.

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:    st_addr_to_file(3),    st_cm_setup(3),    st_file_lang(3),    st_get_known_versions(3),	st_lang_str(3),   st_obj_calls(3),
       st_obj_file_start(3), st_obj_open(3), st_objlist_append(3), st_proc_addr(3), st_pt_setup(3), st_strerror(3), st_sym_value(3).

       delim off

																    libst_intro(3)