unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field





































































ldfcn(4)							     ldfcn(4)



NAME

  ldfcn	- Common object	file access routines

SYNOPSIS

  #include <&lt;stdio.h>&gt;
  #include <&lt;filehdr.h>&gt;
  #include <&lt;syms.h>&gt;
  #include <&lt;ldfcn.h>&gt;

DESCRIPTION

  The common object file access	routines are a collection of functions for
  reading an object file that is in common object file form (COFF).  Although
  the calling program must know	the detailed structure of the parts of the
  object file that it processes, the routines effectively insulate the cal-
  ling program from knowledge of the overall structure of the object file.

  The interface	between	the calling program and	the object file	access rou-
  tines	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 struc-
  ture to the calling program.	The fields of the LDFILE structure can be
  accessed individually	through	macros defined in ldfcn.h.  The	fields con-
  tain the following information:

  LDFILE *ldptr;

  TYPE(ldptr)	 The file magic	number,	used to	distinguish between archive
		 members and simple object files.

  IOPTR(ldptr)	 Not used because files	are memory mapped.

  OFFSET(ldptr)	 The file address of the beginning of the object file or
		 archive entry;	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 associ-
		 ated 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
		 /usr/include/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 four categories:

   1.  Functions that open or close an object file:

       - ldopen	and ldaopen open an object file.

       - ldclose and ldaclose close an object file.

   2.  Functions that return header or symbol table information:

       - ldahread reads	the archive header of a	member of an archive file.

       - ldfhread reads	the file header	of an object file.

       - ldshread and ldnshread	read a section header of an object file.

       - ldtbread reads	a symbol table entry of	an object file.

       - ldgetname retrieves a symbol name from	a symbol table entry or	from
	 the string table.

       - ldgetaux retrieves a pointer into the aux table for the specified
	 ldptr.

       - ldgetpd retrieves a procedure descriptor.

   3.  Functions that seek to specified	portions of an object file:

       - ldohseek seeks	to the optional	file header of an object file.
	 ldsseek and ldnsseek seek to a	section	of an object file.

       - ldrseek and ldnrseek seek to the relocation information for a sec-
	 tion of an object file.

       - ldlseek and ldnlseek seek to the line number information for an
	 object	file.  ldlseek and ldnlseek ignore section number and name
	 arguments, respectively.

       - ldtbseek seeks	to the symbol table of an object file.

   4.  Miscellaneous functions

       - ranhashinit (see ranhash(3)) initializes the tables and constants so
	 that the archive hash and lookup routines can work.

       - Given a string, ranhash returns the hash index	for it.

       - ranlookup returns an archive hash bucket that is empty	or matches
	 the string argument.

       - disassembler prints assembly instructions.

  These	functions are described	in detail in their own reference pages.

  The ldopen and ldaopen functions both	return pointers	to a LDFILE struc-
  ture.

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 reference pages for	the corresponding
  standard input/output	library	functions for details on the use of these
  macros.

  The program must be loaded with the object file access routine library
  libmld.a.

WARNINGS

  The FSEEK macro 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 because the end of an archive file
  cannot be the	same as	the end	of one of its object file members.

RELATED	INFORMATION

  Commands: ar(1)

  Functions: fopen(3), fseek(3), ldahread(3), ldclose(3), ldfhread(3), ldget-
  name(3), ldlseek(3), ldohseek(3), ldopen(3), ldrseek(3), ldshread(3),
  ldtbread(3), ldtbseek(3).