libst_intro man page on OSF1

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
OSF1 logo
[printable version]

libst_intro(3)							libst_intro(3)

NAME
       libst_intro, libst - symbol table and object file access library

SYNOPSIS
       #include <st.h>

DESCRIPTION
       The  library  libst.a  contains a collection of functions for accessing
       object file data and symbol table information. These  functions	effec‐
       tively  insulate	 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  per‐
       formance 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 applications
       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	proce‐
       dures  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  example.	 If  a	thread
       changes	name  demangling  for an object, you should both set the name-
       demangling option 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  synchroniza‐
       tion.

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, 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 nonzero return status is	 the  recommended  method  for
       detecting an error return from a libst function.

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  libdeman‐
       gle.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\n");
	     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\n",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\n", 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:\n");
	     else {
		st_file_name(obj, file, &fname);
		printf("File %s:\n", 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\n", pname);
		else
		   printf("   Procedure at 0x%p\n",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\n",ret);
	     exit(1);
	  }
	  exit (0); }

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

								libst_intro(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OSF1

List of man pages available for OSF1

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net