st_obj_open(3)st_obj_open(3)NAME
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
SYNOPSIS
#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 );
LIBRARY
Symbol Table and Object File Access Library (libst.a)
PARAMETERS
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. Speci‐
fies 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.
DESCRIPTION
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 sub‐
sequent 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 con‐
tains 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_mem‐
ber_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_ar‐
chive() 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.
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 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.
EXAMPLE
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);
...
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: 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)
