Printed 11/19/92 Page 1
LDFCN(4) RISC/os Reference Manual LDFCN(4)
NAME
ldfcn - common object file access routines
SYNOPSIS
#include <stdio.h>
#include <filehdr.h>
#include <syms.h>
#include <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>. Primarily, this structure provides uniform
access to simple object files and object files that are
members of an archive file.
The function ldopen(3X) allocates and initializes the LDFILE
structure, reads in the symbol table header, if present, and
returns a pointer to the structure to the calling program.
The fields of the LDFILE structure can be accessed individu-
ally through macros defined in <ldfcn.h>. The fields 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; if the object file is a member
of an archive file, the offset is non-zero.
HEADER(ldptr) The file header structure of the object file.
SYMHEADER(ldptr)
The symbolic header structure for the symbol
table associated with the object file.
MIPS Computer Systems Printed 11/19/92 Page 1
LDFCN(4) RISC/os Reference Manual LDFCN(4)
PFD(ldptr) The file table associated with the symbol
table.
SYMTAB(ldptr) A pointer to a copy of the symbol table in
memory. It's accessed through the pCHDR
structure (see cmplrs/stsupport.h). If no
symbol table is present, this field is NULL.
NOTE: This macro causes the whole symbol
table to be read.
LDSWAP(ldptr) If the header and symbol table structures are
swapped within the object file and all access
requires using libsex, this field is set to
true. NOTE: If you use libmld routines, all
structures, except the optional header and
auxiliaries, are swapped.
The object file access functions can be divided into five
categories:
(1) functions that open or close an object file
ldopen(3X) and ldaopen
open a common object file
ldclose(3X) and ldaclose
close a common object file
(2) functions that return 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
ldgetaux(3X)
retrieve a pointer into the aux table for the
specified ldptr
ldgetpd(3X)
retrieve a procedure descriptor
(3) functions that position an object file at (seek
to) the start of the section, relocation, or line
number information for a particular section
Page 2 Printed 11/19/92 MIPS Computer Systems
LDFCN(4) RISC/os Reference Manual LDFCN(4)
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 sec-
tion 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) miscellaneous functions
ldtbindex(3X)
return the index of a particular common
object file symbol table entry
ranhashinit (see ranhash(3X))
initialize the tables and constants so that
the archive hash and lookup routines can work
ranhash(3X)
give a string return the hash index for it
ranlookup (see ranhash(3X))
return an archive hash bucket that is empty
or matches the string argument
disassembler(3X)
print MIPS assembly instructions
These functions are described in detail in the manual
pages identified for each function.
ldopen and ldaopen both return pointers to a LDFILE
structure.
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. They translate a reference of the LDFILE struc-
ture 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)
MIPS Computer Systems Printed 11/19/92 Page 3
LDFCN(4) RISC/os Reference Manual LDFCN(4)
FTELL(ldptr)
REWIND(ldptr)
FEOF(ldptr)
FERROR(ldptr)
FILENO(ldptr)
SETBUF(ldptr, buf)
STROFFSET(ldptr)
The STROFFSET macro calculates the address of the local
symbol's string table in an 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 rou-
tine library libmld.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 cannot 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), ldshread(3X),
ldtbread(3X), ldtbseek(3X).
ar(1) in the User's Reference Manual.
COFF in the RISCompiler and C Programmer's Guide.
Page 4 Printed 11/19/92 MIPS Computer Systems