ldfcn(4)                   DG/UX 4.30                    ldfcn(4)



     NAME
          ldfcn - executable file access routines in DG/UX

     SYNOPSIS
          #include <stdio.h>
          #include <sys/types.h>
          #include <filehdr.h>
          #include <ldfcn.h>

     DESCRIPTION
          The executable file access routines are a collection of
          functions for reading an executable file that is in DG/UX
          executable file format.  Although the calling program must
          know the detailed structure of the parts of the executable
          file that it processes, the routines effectively insulate
          the calling program from knowledge of the overall structure
          of the executable file.

          The interface between the calling program and the executable
          file access routines is based on LDFILE defined as struct
          ldfile, declared in the header file ldfcn.h.  This structure
          provides uniform access to simple executable files and to
          executable 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 archive members and simple executable
                         files.

          IOPTR(ldptr)   The file pointer returned by fopen(3S) and
                         used by the standard input/output functions.

          OFFSET(ldptr)  The file address of the beginning of the
                         executable file; the offset is non-zero if
                         the executable file is a member of an archive
                         file.

          HEADER(ldptr)  The file header structure of the executable
                         file.

          The executable file access functions may be divided into
          four categories:

          (1)  Functions that open or close an executable file




     Licensed material--property of copyright holder(s)         Page 1

     ldfcn(4)                   DG/UX 4.30                    ldfcn(4)



          ldopen(3X) and ldaopen(3X) open an executable file
          ldclose(3X) and ldaclose(3X) close an executable 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 an
          executable file ldshread(3X) read a section header of an
          executable file ldsyshread(3X) read the system header of an
          executable file ldtbread(3X) read a symbol table entry of an
          executable file ldgetname(3X) retrieve a symbol name from a
          symbol table entry.

          (3)  Functions that position an executable file at (seek to)
          the start of a particular section.

          ldohseek(3X) seek to the system header of an executable file
          ldsseek(3X) seek to a section of an executable file
          ldtbseek(3X) seek to the symbol table of an executable file

          (4) The function ldtbindex(3X), which returns the index of a
          particular executable file symbol table entry.

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

          All the functions except ldaopen(3X), ldgetname(3X),
          ldopen(3X), and ldtbindex(3X) return either SUCCESS or
          FAILURE, both constants defined in ldfcn.h.  Ldaopen(3X) and
          ldopen(3X) both return pointers to an LDFILE structure.

          Additional access to an executable 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(ptr, sizeof (*ptr), nitems, ldptr)
               FSEEK(ldptr, offset, ptrname)
               FTELL(ldptr)
               REWIND(ldptr)
               FEOF(ldptr)
               FERROR(ldptr)
               FILENO(ldptr)
               SETBUF(ldptr, buf)



     Licensed material--property of copyright holder(s)         Page 2

     ldfcn(4)                   DG/UX 4.30                    ldfcn(4)



          See the manual entries for the corresponding standard
          input/output library functions for details on these macros.

          The program must be loaded with the executable file access
          routine library libld.a.

     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 because the end of an archive file may not
          be the same as the end of one of its executable file
          members!

     SEE ALSO
          fseek(3S), ldahread(3X), ldclose(3X), ldfhread(3X),
          ldgetname(3X), ldohseek(3X), ldopen(3X), ldshread(3X),
          ldsseek(3X), ldsyshread(3X), ldtbindex(3X), ldtbread(3X),
          ldtbseek(3X), intro(5).

     CAVEATS
          The executable file format is used only for executable files
          (load modules), not for object files.
































     Licensed material--property of copyright holder(s)         Page 3