ldfcn(5) — RISC

Name

ldfcn − common object file access routines

Syntax

#include <stdio.h>
#include <filehdr.h>
#include <syms.h>
#include <ldfcn.h>

Description

The common object file access routines are a collection of functions that read an object file that is in common object file form. The calling program must know the detailed structure of the parts of the object file that it processes, but the calling program does not have to know the overall structure of the object file as the routines handle this function.

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() 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 individually 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() 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 nonzero.

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.

PFD(ldptr) The file table associated with the symbol table.

SYMTAB(ldptr) A pointer to a copy of the symbol table in memory. It is accessed through the pCHDR structure (see cmplrs/stsupport.h). If no symbol table is present, this field is NULL. 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 that if you use libmld routines, all structures, except the optional header and auxiliaries, are swapped.

The object file access functions can be divided into four categories:

(1) Functions that open or close an object file

ldopen() and ldaopen

open a common object file

ldclose() and ldaclose

close a common object file

(2) Functions that return header or symbol table information

ldahread()

read the archive header of a member of an archive file

ldfhread()

read the file header of a common object file

ldshread() and ldnshread

read a section header of a common object file

ldtbread()

read a symbol table entry of a common object file

ldgetname()

retrieve a symbol name from a symbol table entry or from the string table

ldgetaux()

retrieve a pointer into the aux table for the specified ldptr

ldgetsymstr()

create a type string (for example, C declarations) for the specified symbol

ldgetpd()

retrieve a procedure descriptor

ldgetrfd()

retrieve a relative file table entry

(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()

seek to the optional file header of a common object file

ldsseek() and ldnsseek

seek to a section of a common object file

ldrseek() and ldnrseek

seek to the relocation information for a section of a common object file

ldlseek() and ldnlseek

seek to the line number information for a section of a common object file

ldtbseek()

seek to the symbol table of a common object file

(4) Miscellaneous functions

ldtbindex()

return the index of a particular common object file symbol table entry

ranhashinit()

initialize the tables and constants so that the archive hash and lookup routines can work

ranhash()

give a string return the hash index for it

ranlookup()

return an archive hash bucket that is empty or matches the string argument

disassembler()

print MIPS assembly instructions

ldreadst()

cause a section of the symbol table to be read

These functions are described in detail in the manual pages identified for each function.

The ldopen and ldaopen functions 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 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)
FREADM((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 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 the reference pages.)

Restrictions

The macro FSEEK defined in the header file <ldfcn.h> translates into a call to the standard input/output function fseek(.). 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.

Museum