*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> st_ar_member_next (3)              



NAME    [Toc]    [Back]

       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    [Toc]    [Back]

       #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_obj_t *obj,
               st_bool_t      *is_archive      );     st_status_t
               char *file,
               st_bool_t *is_archive  );  st_status_t  st_ar_member_next(

               st_obj_t *obj );

LIBRARY    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

       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.

DESCRIPTION    [Toc]    [Back]

       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

       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

       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    [Toc]    [Back]

       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

       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    [Toc]    [Back]

       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 */



FILES    [Toc]    [Back]

       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    [Toc]    [Back]

       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)

[ Back ]
 Similar pages
Name OS Title
elfdump IRIX dumps selected parts of a 32-bit or a 64-bit ELF object file/archive and displays them in ELF style
ldahread Tru64 read the archive header of a member of an archive file
ldahread IRIX read the archive header of a member of an archive file
pax HP-UX Extracts, writes, and lists archive files; copies files and directory hierarchies
cpio Tru64 Copies files to and from archive storage.
shar FreeBSD create a shell archive of files
shar OpenBSD create a shell archive of files
tar FreeBSD tape archiver; manipulate "tar" archive files
pax Tru64 Extracts, writes, and lists archive files
updadmin Tru64 Invokes the Update Installation Cleanup utility to remove or archive backup files created by an Upda...
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service