NAME

st_file_lang, st_file_name, st_is_file_locally_stripped, st_file_proc_start, st_file_proc_count, st_file_proc_next, st_file_sym_start −  Access information about the files in an object

LIBRARY

Symbol Table and Object File Access Library (libst.a)

SYNOPSIS

#include <st.h>

st_status_t  st_file_lang (
        st_obj_t ∗obj,
        st_file_t file,
        unsigned int ∗lang );

st_status_t st_file_name (
        st_obj_t ∗obj,
        st_file_t file,
        char ∗∗fname );

st_status_t st_is_file_locally_stripped (
        st_obj_t  ∗obj,
        st_file_t file,
        st_bool_t ∗stripped );

st_status_t st_file_proc_start (
        st_obj_t  ∗obj,
        st_file_t file,
        st_proc_t ∗pstart );

st_status_t st_file_proc_count (
        st_obj_t ∗obj,
        st_file_t file,
        unsigned int ∗pcount );

st_status_t st_file_proc_next (
        st_obj_t ∗obj,
        st_file_t file,
        st_proc_t pcur,
        st_proc_t ∗pnext );

st_status_t st_file_sym_start (
        st_obj_t ∗obj,
        st_file_t file,
        st_sym_t ∗isym );

PARAMETERS

objSpecifies an object handle, as returned by the st_obj_open function. 

fileSpecifies a file handle, as returned by functions such as st_obj_file_start. 

langSpecifies an address to which st_file_lang returns the source language type of the specified file.  Source language types are defined in /usr/include/symconst.h. 

fname
Specifies an address to which st_file_name writes a pointer to a null-terminated string containing the filename of the specified file.  The returned filename is for read-access only.  A copy should be made before modifications are made to the string by the calling program. 

stripped
Specifies an address to which st_is_file_locally_stripped returns a Boolean value of TRUE if the specified file has been partially stripped. 

pstart
Specifies an address to which st_file_proc_start returns the handle of the first procedure in the specified file. 

pcount
Specifies an address to which st_file_proc_count writes the number of procedures within the specified file. 

pcurSpecifies the handle of a procedure within the specified file.  st_file_proc_next uses this handle to determine pnext. 

pnext
Specifies an address to which st_file_proc_next returns the handle of the procedure following pcur in the specified file.  If pcur equals or exceeds the number of procedures in the specified file, st_file_proc_next returns ST_E_PROC_RANGE and returns a -1 to the location to which pnext points. 

isym
Specifies an address to which st_file_sym_start writes the handle of the first symbol for the specified file. 

DESCRIPTION

All of the functions described in this reference page return information about the files in an object:

st_file_lang
Identifies the source language (for example, C++) of the specified file.

st_file_name
Returns a pointer to a null-terminated string containing the filename of the specified file. (Note: The returned filename is for read-access only. The calling program must make any modifications to a copy of the filename string.)

st_is_file_locally_stripped
Checks whether the file has been partially stripped.  A partially stripped file does not contain a complete set of symbolic information (for instance, if it was not compiled with the −g flag). 

st_file_proc_start
Returns the handle of the first procedure in the specified file.

st_file_proc_count
Returns the number of procedures within the specified file.

st_file_proc_next
Returns the handle of the procedure following pcur in the specified file.  If pcur equals or exceeds the number of procedures for the specified file, st_file_proc_next returns ST_E_PROC_RANGE and sets pnext to −1. 

st_file_sym_start
Returns the handle of the first symbol for the given file handle.

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

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

/usr/include/symconst.h
header file that defines source language types returned by the st_file_lang function. 

RELATED INFORMATION

Commands: atom(1)

Functions: libst_intro(3), st_addr_to_file(3), st_obj_file_start(3), st_obj_open(3), st_objlist_append(3), st_proc_addr(3), st_sym_value(3)