ldfcn(4) ldfcn(4)
NAME
ldfcn - common object file access routines
SYNOPSIS
#include <stdio.h>
#include <filehdr.h>
#include <ldfcn.h>
#include INCDIR/filehdr.h
#include INCDIR/ldfcn.h
DESCRIPTION
The common object file access routines are a collection of
functions for reading an object file that is in common
object file form. 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), which is declared in the header
file <ldfcn.h>. The primary purpose of this structure is to
provide uniform access to both simple object files and
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 archive members and simple object
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
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 may be divided into four
categories:
(1) functions that open or close an object file
Page 1 (last mod. 1/14/87)
ldfcn(4) ldfcn(4)
ldopen(3X) and ldaopen
open a common object file
ldclose(3X) and ldaclose
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
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
seek to a section of a common object file
ldrseek(3X) and ldnrseek
seek to the relocation information for a
section of a common object file
ldlseek(3X) and ldnlseek
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 function ldtbindex(3X) which returns the index
of a particular common object file symbol table entry
These functions are described in detail in the manual pages
identified for each function.
All the functions except ldopen, ldgetname(3X), ldaopen, and
ldtbindex return either SUCCESS or FAILURE, which are
constants defined in <ldfcn.h>. ldopen and both return
pointers to a LDFILE structure.
Page 2 (last mod. 1/14/87)
ldfcn(4) ldfcn(4)
MACROS
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 in a object file. See the manual entries for the
corresponding standard input/output library functions for
details on the use of these macros. (The functions are
identified as 3S in Section 3 of this manual.)
The program must be loaded with the object file access
routine library libld.a.
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 since the end of an archive file may not be
the same as the end of one of its object file members.
SEE ALSO
fopen(3S), fseek(3S), ldahread(3X), ldclose(3X),
ldfhread(3X), ldgetname(3X), ldlread(3X), ldlseek(3X),
ldohseek(3X), ldopen(3X), ldrseek(3X), ldlseek(3X),
ldshread(3X), ldtbindex(3X), ldtbread(3X), ldtbseek(3X).
``COFF Reference'' Oreo Programming Languages and Tools,
Volume 2.
Page 3 (last mod. 1/14/87)