 |
Index for
Section 3 |
|
 |
Alphabetical
listing for L |
|
 |
Bottom of
page |
|
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 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
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 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.
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 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 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);
}
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
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for L |
|
 |
Top of
page |
|