libst_intro, libst - symbol table and object file access
library
#include <st.h>
The library libst.a contains a collection of functions for
accessing object file data and symbol table information.
These functions effectively 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 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 applications may also need to include the
<cmplrs/demangle_string.h> header file to control namedemangling
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 callshared
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 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 synchronization.
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 nonzero return status is the recommended
method for detecting an error return from a libst function.
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\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); }
Header file that contains all definitions and function
prototypes for libst.a functions Header file that controls
name-demangling operations for C++ objects
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)
[ Back ] |
