Index for Section 3

Alphabetical listing for S

Bottom of page

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

  file
      Specifies the file name of the object to be opened or closed, or for
      which an object type is requested.

  flags
      Specifies how the object is to be opened. The open flags defined in
      /usr/include/st.h include the following:

      ST_RDONLY
	      Opens the file for read-only access. This is the default.

      ST_MANGLE_NAMES
	      Disables name demangling for C++ names. By default, C++ name
	      demangling is enabled when a file is opened.

      ST_FORCE
	      Overrides version checking for object and symbol table formats.

  otype
      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:

      ST_OTYPE_UNKNOWN
	      Unknown object type

      ST_ARCHIVE
	      Archive library

      ST_OMAGIC
	      OMAGIC file

      ST_NMAGIC
	      NMAGIC file

      ST_ZMAGIC
	      ZMAGIC file

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

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 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
  /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: 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)

Index for Section 3

Alphabetical listing for S

Top of page