LDOPEN(3X)                           BSD                            LDOPEN(3X)



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

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

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

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

DESCRIPTION
     ldopen and ldclose(3X) are designed to provide uniform access to both
     simple object files and object files that are members of archive files.
     Thus 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, then ldopen will open filename and allocate
     and initialize the LDFILE structure, and return a pointer to the
     structure to the calling program.

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

     ldopen and ldclose(3X) are designed to work in concert.  ldclose will
     return 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, in
     particular whenever 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(3X).

          /* for each filename to be processed */

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

     If the value of oldptr is not NULL, ldaopen will open filename anew and
     allocate and initialize a new LDFILE structure, copying the TYPE, OFFSET,
     and HEADER 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 may be used concurrently to read separate parts
     of the object file.  For example, one pointer may be used to step
     sequentially through the relocation information, while the other is used
     to read indexed symbol table entries.

     Both ldopen and ldaopen open filename for reading.  Both functions return

     NULL if filename cannot be opened, or if memory for the LDFILE structure
     cannot be allocated.  A successful open does not insure that the given
     file is a common object file or an archived object file.

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

SEE ALSO
     fopen(3S), ldclose(3X), ldfcn(5).

BUGS
     ldopen and ldaopen return NULL if the file pointed to by filename is
     small (19 bytes or less).  Since files this size are smaller than the
     filehdr structure (see <filehdr.h>), they necessarily are not in common
     object file format.