LDFCN(F)                             UNIX System V



     Name
          ldfcn - common object file access routines


     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,
          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(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 standard 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 may  be  divided
          into four categories:

               (1)  functions that open or close an object file

                    ldopen(S) and ldaopen[see ldopen(S)]
                         open a common object file
          ldclose(S) and ldaclose[see ldclose(S)]
          close a common object file

          (2)  functions that read header or symbol table information

               ldahread(S)
                    read the archive header of a member of an  archive
                    file
          ldfhread(S)
          read the file header of a common object file
          ldshread(S) and ldnshread[see ldshread(S)]
          read a section header of a common object file
          ldtbread(S)
          read a symbol table entry of a common object file
          ldgetname(S)
          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(S)
                    seek to the  optional  file  header  of  a  common
                    object file
          ldsseek(S) and ldnsseek[see ldsseek(S)]
          seek to a section of a common object file
          ldrseek(S) and ldnrseek[see ldrseek(S)]
          seek to the relocation information for a section of a common
          object file
          ldlseek(S) and ldnlseek[see ldlseek(S)]
          seek to the line number  information  for  a  section  of  a
          common object file
          ldtbseek(S)
          seek to the symbol table of a common object file

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

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

          All   the   functions   except   ldopen(S),    ldgetname(S),
          ldtbindex(S)   return   either   SUCCESS  or  FAILURE,  both
          constants defined in ldfcn.h.   Ldopen(S)  and  ldaopen[(see
          ldopen(S)] 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(S),     ldahread(S),     ldclose(S),     ldgetname(S),
          ldfhread(S), ldlread(S), ldlseek(S), ldohseek(S), ldopen(S),
          ldrseek(S),    ldlseek(S),    ldshread(S),     ldtbindex(S),
          ldtbread(S), ldtbseek(S), stdio(S), intro(M)


     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.


     (printed 2/15/90)                                   LDFCN(F)