LDFCN(3x,L)                 AIX Technical Reference                 LDFCN(3x,L)



-------------------------------------------------------------------------------
ldfcn



PURPOSE

Common object file access routines.

LIBRARY

Object File Access Routine Library (libld.a)

SYNTAX

#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, which is defined as struct ldfile and
declared in the header file ldfcn.h.  The primary purpose of this structure is
to provide uniform access to both simple 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 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.



Processed November 7, 1990        LDFCN(3x,L)                                 1






LDFCN(3x,L)                 AIX Technical Reference                 LDFCN(3x,L)




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

  o Functions that open or close an object file:

          ldopen and ldaopen
                 open a common object file
          ldclose and ldaclose
                 close a common object file

  o Functions that read header or symbol table information:

          ldahread
                 reads the archive header of a member of an archive file
          ldfhread
                 reads the file header of a common object file
          ldshread and ldnshread
                 read a section header of a common object file
          ldtbread
                 reads a symbol table entry of a common object file
          ldgetname
                 retrieves a symbol name from a symbol table entry or
                 from the string table

  o Functions that position an object file at the start of the section,
    relocation, or line number information for a particular section of a common
    object file:

          ldohseek
                 seeks to the optional file header of a common object file
          ldsseek and ldnsseek
                 seek to a section of a common object file
          ldrseek and ldnrseek
                 seek to the relocation information for a section of a
                 common object file
          ldlseek and ldnlseek
                 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

  o The function ldtbindex, which returns the index of a particular common
    object file symbol table entry.

All the functions except ldopen, ldgetname, ldaopen, and ldtbindex return
either SUCCESS or FAILURE, constants which are defined in ldfcn.h.  The ldopen
and ldaopen functions 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




Processed November 7, 1990        LDFCN(3x,L)                                 2






LDFCN(3x,L)                 AIX Technical Reference                 LDFCN(3x,L)



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)

   FWRITE((char *) ptr, sizeof (*ptr), nitems,ldptr)

   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 in a COFF-format
object file.

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

RELATED INFORMATION

In this book:  "fseek, rewind, ftell," "ldahread," "ldclose, ldaclose,"
"ldfhread," "ldgetname," "ldlread, ldlinit, ldlitem," "ldlseek, ldnlseek,"
"ldohseek," "ldopen, ldaopen," "ldrseek, ldnrseek," "ldshread, ldnshread,"
"ldtbindex," "ldtbread," and "ldtbseek."






Processed November 7, 1990        LDFCN(3x,L)                                 3