ldfcn(0)                            CLIX                            ldfcn(0)



  NAME

    ldfcn - Common object file access functions

  SYNOPSIS

    #include <stdio.h>

    #include <filehdr.h>

    #include <ldfcn.h>

    #include "INCDIR/filehdr.h"

    #include "INCDIR/ldfcn.h"

  DESCRIPTION

    The common object file access functions 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 functions 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
    functions 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() 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 stdin/stdout
           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)



  2/94 - Intergraph Corporation                                              1

  ldfcn(0)                            CLIX                            ldfcn(0)



           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()
        ldaopen()   (see ldopen()) Open a common object file

        ldclose())
        ldaclose()  (see ldclose()) Close a common object file

    2.  Functions that read header or symbol table information

        ldahread()    Read the archive header of a member of an archive file

        ldfhread()    Read the file header of a common object file

        ldshread()
        ldnshread()   (see ldshread()) Read a section header of a common
                      object file

        ldtbread()    Read a symbol table entry of a common object file

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

    3.  Functions that position an object file at (seek to) the start of the
        section, relocation, or line number information for a particular
        section.

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

        ldsseek()
        ldnsseek()   (see ldsseek()) Seek to a section of a common object file

        ldrseek()
        ldnrseek()   (see ldrseek()) Seek to the relocation information for a
                     section of a common object file

        ldlseek()
        ldnlseek()   (see ldlseek()) Seek to the line number information for a
                     section of a common object file

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

    4.  The function ldtbindex() which returns the index of a particular
        common object file symbol table entry.

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



  2                                              Intergraph Corporation - 2/94

  ldfcn(0)                            CLIX                            ldfcn(0)



    All the functions except ldopen(), ldgetname(), ldtbindex() return either
    SUCCESS or FAILURE, both constants defined in ldfcn.h.  The functions
    ldopen() and ldaopen() (see ldopen()) 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 stdin/stdout 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 stdin/stdout library functions for
    details on the use of the rest of the macros.

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

  CAUTIONS

    The macro FSEEK() defined in the header file ldfcn.h translates into a
    call to stdin/stdout function fseek().  SEEK() should not be used to seek



  2/94 - Intergraph Corporation                                              3

  ldfcn(0)                            CLIX                            ldfcn(0)



    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!

  RELATED INFORMATION

    Functions: fseek(3), ldahread(3), ldclose(3), ldgetname(3), ldfhread(3),
    ldlread(3), ldlseek(3), ldohseek(3), ldopen(3), ldrseek(3), ldlseek(3),
    ldshread(3), ldtbindex(3), ldtbread(3), ldtbseek(3), stdio(3)














































  4                                              Intergraph Corporation - 2/94