ldfcn(3X) ldfcn(3X)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 an object file that is in common ob- ject 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 ob- ject 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 ob- ject 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 cal- ling program. The fields of the LDFILE structure may be ac- cessed 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 ob- ject file; the offset is nonzero if the ob- ject 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 ldopen(3X) and ldaopen open a common object file April, 1990 1
ldfcn(3X) ldfcn(3X)ldclose(3X) and ldaclose close a common object file (2) functions that read header or symbol table infor- mation 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 ob- ject 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 com- mon 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 ob- ject 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 con- 2 April, 1990
ldfcn(3X) ldfcn(3X)stants defined in <ldfcn.h>. ldopen and ldaopen both return pointers to a LDFILE structure. Programs using this routine must be loaded with the object file access library libld.a. 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(ptr, size, 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 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 this manual.) 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'' and ``C Object Library'' A/UX Programming Languages and Tools, Volume 1. April, 1990 3