st_ar_member_next, st_file_is_archive, st_is_obj_archive,
st_obj_close, st_obj_open, st_object_type - routines to
check whether an object is an archive and to process
object files within an archive
#include <st.h>
st_status_t st_obj_open(
st_obj_t **obj,
const char *file,
unsigned int flags ); st_status_t st_obj_close(
st_obj_t *obj ); st_status_t st_object_type(
const char *file,
st_object_type_t *otype ); st_status_t
st_is_obj_archive(
st_obj_t *obj,
st_bool_t *is_archive ); st_status_t
st_file_is_archive(
char *file,
st_bool_t *is_archive ); st_status_t st_ar_member_next(
st_obj_t *obj );
Symbol Table and Object File Access Library (libst.a)
Specifies an address to which st_obj_open() returns an
object handle if it successfully opens the file specified
in the file parameter. For st_obj_close(), specifies an
object handle, as returned by the st_obj_open() function.
Specifies the file name of the object to be opened or
closed, or for which an object type is requested. Specifies
how the object is to be opened. The open flags
defined in /usr/include/st.h include the following: Opens
the file for read-only access. This is the default. Disables
name demangling for C++ names. By default, C++ name
demangling is enabled when a file is opened. Overrides
version checking for object and symbol table formats.
Specifies an address to which st_object_type() returns a
value identifying the object type. The following object
types are defined in usr/include/st.h: Unknown object type
Archive library OMAGIC file NMAGIC file ZMAGIC file A
boolean variable set to true if the file is an archive.
The st_obj_open() function opens the named object file for
read access. It maps the file in memory using mmap(), if
possible. If mmap() fails, it dynamically allocates memory
in which to read the file. The flags parameter indicates
how the file is to be opened. If it succeeds in opening
the file, it returns an opaque handle for the object to
the obj parameter. You can use this object handle as an
input argument in subsequent calls to other object file
access routines.
The st_obj_close() function releases memory dynamically
allocated for processing the object and unmaps memory to
which the file was mapped when it was opened.
The st_object_type() function returns the object type of
the specified filename object to the otype parameter. It
does not create an object handle, nor does it open the
object.
If the named file is an archive file, st_obj_open() initializes
archive information in the obj structure and
returns successfully.
Archive member objects are processed sequentially. After
an archive has been successfully opened, call the
st_ar_member_next() routine. It reads in an archive member
each time it is called, and it returns ST_E_ARCHIVE_END
when there are no more members. If the archive contains no
members, st_ar_member_next() returns ST_E_ARCHIVE_EMPTY.
(See the code fragment in the EXAMPLE section for proper
usage of st_ar_member_next().)
The routines st_is_obj_archive() and st_file_is_archive()
can be used to detect whether a file or object handle is
an archive. Use st_file_is_archive() before calling
st_obj_open() or st_obj_is_archive() after calling
st_obj_open().
The st_obj_open() function tests the object and symbol
table format versions of the named object file. If either
format version includes a major version number that is not
supported by this implementation of the libst interfaces,
st_obj_open() will return ST_E_MAJ_OBJ_VER (for object
format mismatches) or ST_E_MAJ_SYM_VER (for symbol table
format mismatches.) If the ST_FORCE flag is included in
the st_obj_open() flags parameter, it will not perform the
format version testing.
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 nonzero return status is the recommended method for
detecting an error return from a libst function.
The following code fragment illustrates how to use libst
routines to open object files or archive libraries:
#include <st.h>
char *objname; st_bool_t archive; st_status_t status;
st_obj_t *obj;
...
if (argc != 2)
return; objname = argv[1];
if (status = st_obj_open(&obj, objname, ST_RDONLY))
return status;
st_is_obj_archive(obj, &archive);
if (archive)
while ((status = st_ar_member_next(obj)) == 0) {
/* process member object */
} else
/* process object */
st_obj_close(obj);
...
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: mmap(2), libst_intro(3), st_addr_to_file(3),
st_file_lang(3), st_obj_calls(3), st_obj_file_start(3),
st_objlist_append(3), st_proc_addr(3), st_sym_value(3)
st_obj_open(3)
[ Back ] |
