unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

LDFCN(3)                   Library Functions Manual                   LDFCN(3)



NAME
       ldfcn - common object file access routines

SYNOPSIS
       #include <&lt;stdio.h>&gt;
       #include <&lt;filehdr.h>&gt;
       #include <&lt;ldfcn.h>&gt;

AVAILABILITY
       Available  only  on  Sun  386i systems running a SunOS 4.0.x release or
       earlier.  Not a SunOS 4.1 release feature.

DESCRIPTION
       These routines are for reading COFF object files and archives  contain-
       ing  COFF  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 ar-
                      chive 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 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

              (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(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) The unction ldtbindex(3X), which returns the index of a par-
              ticular common object file symbol table entry.

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

       All  the  functions  except  ldopen(3X),  ldgetname(3X),  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), ldfhread(3X), ldl-
       read(3X),    ldlseek(3X),    ldohseek(3X),   ldopen(3X),   ldrseek(3X),
       ldlseek(3X), ldshread(3X), ldtbindex(3X),  ldtbread(3X),  ldtbseek(3X),
       stdio(3V), intro(5)

WARNING
       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 ar-
       chive file may not be the same as the end of one  of  its  object  file
       members.



                               19 February 1988                       LDFCN(3)