ldopen(3X)

NAME
     ldopen, ldaopen - Opens a common object file for reading

SYNOPSIS
     #include <stdio.h>
     #include <filehdr.h>
     #include <syms.h>
     #include <ldfcn.h>

     LDFILE *ldopen ("filename,ldptr")
     char *filename;
     LDFILE *ldptr;

     LDFILE *ldaopen ("filename,oldptr")
     char *filename;
     LDFILE *oldptr;

     int ldreadst ("ldptr,flags")
     LDFILE *ldptr;
     int flags;

DESCRIPTION
     This routine is available for o32 ABI only.

     ldopen and ldclose(3X) provide uniform access to simple object files
     and to object files that are members of archive files.  An archive of
     common object files can be processed as if it were a series of simple
     common object files.

     If ldptr has the value NULL, ldopen opens filename, allocates and
     initializes the LDFILE structure, and returns a pointer to the
     structure to the calling program.

     If ldptr is valid and TYPE(ldptr) is the archive magic number, ldopen
     reinitializes the LDFILE structure for the next archive member of
     filename.

     ldopen and ldclose work in concert.  ldclose returns FAILURE only when
     TYPE(ldptr) is the archive magic number and there is another file in
     the archive to be processed.  Only then should ldopen be called with
     the current value of ldptr.  In all other cases, and particularly when
     a new filename is opened, ldopen should be called with a NULL ldptr
     argument.

     The following is a prototype for the use of ldopen and ldclose.  It
     handles individual object (or a.out) files and (via the while-loop) an
     archive file of object files.

          /* for each filename to be processed */

          ldptr = NULL;
          do  {
               if ( (ldptr = ldopen(filename, ldptr)) != NULL )
               {
                    /* check magic number */
                    /* process a single object file */
               }
          } while (ldclose(ldptr) == FAILURE );

     If the value of oldptr is not NULL, ldaopen opens filename anew and
     allocates and initializes a new LDFILE structure, copying the fields
     from oldptr.  ldaopen returns a pointer to the new LDFILE structure.
     This new pointer is independent of the old pointer, oldptr.  The two
     pointers can be used concurrently to read separate parts of the object
     file.  For example, one pointer can be used to step sequentially
     through the relocation information while the other is used to read
     indexed symbol table entries.

     ldopen and ldaopen open filename for reading.  If filename cannot be
     opened or if memory for the LDFILE structure cannot be allocated, both
     functions return NULL.  A successful open does not ensure that the
     given file is a common object file or an archived object file.  When
     calling ldopen on a given a.out (rather than an archive) for the first
     time be sure the second argument you pass is a NULL pointer [(LDFILE
     *)0] (this is the only way to ensure the LDFILE * is initialized
     properly for that a.out file).

     ldreadst reads in the portions of the symbol table implied by the
     flags argument.  A flags argument of -1 reads in the entire symbol
     table.  Because the other routines, for example, ldtbread, ensure that
     the relevant portions of the symbol table have been read in, you need
     not call ldreadst to use the other routines.  ldreadst(ldptr,-1) would
     simply ensure the whole symbol table is read in at once, which is not
     necessary.  ldreadst returns SUCCESS if it has read in the symbol
     table successfully or FAILURE if it cannot.  If a symbol table has
     been truncated or damaged, there is a small probability that ldreadst
     will core dump rather than return FAILURE.

     ldopen causes the symbol table header and file descriptor table to be
     read.  Further access, using ldptr, causes other appropriate sections
     of the symbol table to be read (for example, if you call ldtbread, the
     symbols or externals are read).  To force sections of the symbol table
     into memory, call ldreadst with ST_P* constants ORed together from
     <cmplrs/stsupport.h>.

     The program must be loaded with the object file access routine library
     libmld.a.

SEE ALSO
     fopen(3S), ldclose(3X)

     ldfcn(4)