ldfcn(FP)                      6 January 1993                      ldfcn(FP)


 Name

    ldfcn - common object file access routines

 Syntax


    #include <stdio.h>

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

    #include INCDIR/filehdr.h
    #include INCDIR/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 rou-
    tines is based on the defined type LDFILE, defined as struct ldfile,
    declared in the header file ldfcn.h.  The primary purpose of this struc-
    ture is to provide uniform access to both simple object files and to
    object files that are members of an archive file.

    The function ldopen(S) 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 stan-
                   dard input/output functions

    OFFSET(ldptr)  The file address of the beginning of the object file; the
                   offset is non-zero 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 can be divided into the fol-
    lowing categories:

    +  functions that open or close an object file:

      ldopen(S) and ldaopen open a common object file

      ldclose(S) and ldaclose close a common object file

    +  functions that read header or symbol table information:

      ldahread(S) reads the archive header of a member of an archive file

      ldfhread(S) reads the file header of a common object file

      ldshread(S) and ldnshread read a section header of a common object file

      ldtbread(S) reads a symbol table entry of a common object file

      ldgetname(S) retrieves a symbol name from a symbol table entry or from
      the string table

    +  functions that position an object file at (seek to) the start of the
       section, relocation, or line number information for a particular sec-
       tion:

      ldohseek(S) seeks to the optional file header of a common object file

      ldsseek(S) and ldnsseek seek to a section of a common object file

      ldrseek(S) and ldnrseek seek to the relocation information for a sec-
      tion of a common object file

      ldlseek(S) and ldnlseek seek to the line number information for a sec-
      tion of a common object file

      ldtbseek(S) seeks to the symbol table of a common object file

    +  the function ldtbindex(S) which returns the index of a particular com-
       mon object file symbol table entry.

    These functions are described in detail on their respective manual pages.
    All the functions except ldopen(S), ldgetname(S), and ldtbindex(S) return
    either SUCCESS or FAILURE, both constants defined in ldfcn.h.  ldopen(S)
    and ldaopen 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 func-
    tions for details on the use of the rest of the macros.

    The program must be loaded with the object file access library routine
    LIBDIR/elibld.a.

 Notes

    The macro FSEEK defined in the header file ldfcn.h translates into a call
    to the standard input/output function fseek(S).  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.

 See also

    fseek(S), intro(M) ldahread(S), ldclose(S), ldfhread(S), ldgetname(S),
    ldlread(S), ldlseek(S), ldohseek(S), ldopen(S), ldrseek(S), ldshread(S),
    ldtbindex(S), ldtbread(S), ldtbseek(S), stdio(S)