ldfcn(4)                       DG/UX R4.11MU05                      ldfcn(4)


NAME
       ldfcn - COFF executable file access routines

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 a COFF 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
            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) reads the archive header of a member of an archive
            file
            ldfhread(3X) reads the file header of an executable file
            ldshread(3X) reads a section header of an executable file
            ldsyshread(3X) reads the system header of an executable file
            ldtbread(3X) reads a symbol table entry of an executable file
            ldgetname(3X) retrieves 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) seeks to the system header of an executable file
            ldsseek(3X) seeks to a section of an executable file
            ldtbseek(3X) seeks to the symbol table of an executable file

       (4)  The function ldtbindex(3X) 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
       inputoutput 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)

       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.

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

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

WARNINGS
       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!

       Note that <ldfcn.h> must not be included in a file where <regexp.h>
       is also included, as the macros defined in <ldfcn.h> conflict with
       the macros expected in <regexp.h>.


Licensed material--property of copyright holder(s)