LDFCN(4) LDFCN(4)
NAME
ldfcn - common object file access routines
SYNOPSIS
#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(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 and used
by the standard input/output functions.
Page 1 May 1989
LDFCN(4) LDFCN(4)
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
Page 2 May 1989
LDFCN(4) LDFCN(4)
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 function ldtbindex(3X) 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(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)
Page 3 May 1989
LDFCN(4) LDFCN(4)
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), ldlread(3X), ldlseek(3X), ldohseek(3X),
ldopen(3X), ldrseek(3X), ldlseek(3X), ldshread(3X),
ldtbindex(3X), ldtbread(3X), ldtbseek(3X), stdio(3S),
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 archive file may not be
the same as the end of one of its object file members!
Page 4 May 1989