LDFCN(5)                             BSD                              LDFCN(5)



NAME
     ldfcn - common object file access routines

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

DESCRIPTION
     The common object file access routines are a collection of functions for
     reading common object files and archives containing common object files.
     Although the calling program must know the detailed structure of the
     parts of the object file that it processes, the routines effectively
     insulate the calling program from knowledge of the overall structure of
     the object file.

     The interface between the calling program and the object file access
     routines is based on the defined type LDFILE, defined as struct ldfile,
     declared in the header file ldfcn.h.  The primary purpose of this
     structure is to provide uniform access to both simple object files and to
     object files that are members of an archive file.

     The function ldopen(3X) allocates and initializes the LDFILE structure
     and returns a pointer to the structure to the calling program.  The
     fields of the LDFILE structure may be accessed individually through
     macros defined in ldfcn.h and contain the following information:

     LDFILE          *ldptr;

     TYPE(ldptr)     The file magic number used to distinguish between archive
                     members and simple object files.

     IOPTR(ldptr)    The file pointer returned by fopen and used by the
                     standard input/output functions.

     OFFSET(ldptr)   The file address of the beginning of the object file; the
                     offset is nonzero if the object file is a member of an
                     archive file.

     HEADER(ldptr)   The file header structure of the object file.

     The object file access functions themselves may be divided into four
     categories:

     1.  Functions that open or close an object file:

         ⊕  ldopen(3X) and ldaopen (see ldopen(3X)).  Open a common object
            file.

         ⊕  ldclose(3X) and ldaclose see ldclose(3X)).  Close a common object
            file.

     2.  Functions that read header or symbol table information:

         ⊕  ldahread(3X).  Read the archive header of a member of an archive
            file.

         ⊕  ldfhread(3X).  Read the file header of a common object file.

         ⊕  ldshread(3X) and ldnshread (see ldshread(3X)).  Read a section
            header of a common object file.

         ⊕  ldtbread(3X).  Read a symbol table entry of a common object file.

         ⊕  ldgetname(3X).  Retrieve a symbol name from a symbol table entry
            or from the string table.

         ⊕  ldgetarname(3X).  Retrieve the filename of a member of an archive
            file.

         ⊕  ldgetstring(3X).  Retrieve string from common object file string
            table.

         ⊕  ldsgetname(3X).  Retrieve section name for common object file
            entry.

     3.  Functions that seek to given points within an object file:

         ⊕  ldohseek(3X).  Seek to the optional file header of a common object
            file.

         ⊕  ldsseek(3X) and ldnsseek (see ldsseek(3X)).  Seek to a section of
            a common object file.

         ⊕  ldrseek(3X) and ldnrseek (see ldrseek(3X)).  Seek to the
            relocation information for a section of a common object file.

         ⊕  ldlseek(3X) and ldnlseek (see ldlseek(3X)).  Seek to the line
            number information for a section of a common object file.

         ⊕  ldtbseek(3X) Seek to the symbol table of a common object file.

     4.  Functions which return the index of a particular common object file
         symbol table entry:  ldtbindex(3X).

     These functions are described in detail on their respective manual pages.

     All the functions except ldgetname(3X), ldgetstring(3X), ldopen(3X),
     ldsgetarname(3X), ldsgetname(3X), and ldtbindex(3X) return either SUCCESS
     or FAILURE, both constants defined in <ldfcn.h>.  ldopen(3X) and ldaopen
     (see ldopen(3X)) both return pointers to an LDFILE structure.

     Additional access to an object file is provided through a set of macros
     defined in <ldfcn.h>.  These macros parallel the standard input/output
     file reading and manipulating functions, translating a reference of the
     LDFILE structure into a reference to its file descriptor field.

     The following macros are provided:

          GETC(ldptr)
          FGETC(ldptr)
          GETW(ldptr)
          UNGETC(c, ldptr)
          FGETS(s, n, ldptr)
          FREAD((char *) ptr, sizeof (*ptr), nitems, ldptr)
          FSEEK(ldptr, offset, ptrname)
          FTELL(ldptr)
          REWIND(ldptr)
          FEOF(ldptr)
          FERROR(ldptr)
          FILENO(ldptr)
          SETBUF(ldptr, buf)
          STROFFSET(ldptr)

     The STROFFSET macro calculates the address of the string table.  See the
     manual entries for the corresponding standard input/output library
     functions for details on the use of the rest of the macros.

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

SEE ALSO
     fseek(3S), ldahread(3X), ldclose(3X), ldgetname(3X), ldgetstring(3X),
     ldfhread(3X), ldlread(3X), ldlseek(3X), ldohseek(3X), ldopen(3X),
     ldrseek(3X), ldlseek(3X), ldsgetarname(3X), ldsgetname(3X), ldshread(3X),
     ldtbindex(3X), ldtbread(3X), ldtbseek(3X), stdio(3S).

WARNINGS
     The macro FSEEK defined in the header file <ldfcn.h> translates into a
     call to the standard input/output function fseek(3S).  FSEEK should not
     be used to seek from the end of an archive file since the end of an
     archive file may not be the same as the end of one of its object file
     members!