bfd.texinfo

早期freebsd实现

\input texinfo.tex
@setfilename bfd.info
@c $Id: bfd.texinfo,v 1.12 1991/12/20 00:48:42 pesch Exp $
@tex
% NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE
\global\long\def\example{%
\begingroup
\let\aboveenvbreak=\par
\let\afterenvbreak=\par
\parskip=0pt
\lisp}
\global\long\def\Eexample{%
\Elisp
\endgroup
\vskip -\parskip% to cancel out effect of following \par
}
@end tex
@synindex fn cp

@ifinfo
@format
START-INFO-DIR-ENTRY
* Bfd: (bfd).			The Binary File Descriptor library.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents the BFD library.

Copyright (C) 1991 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, subject to the terms
of the GNU General Public License, which includes the provision that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo
@iftex
@c@finalout
@setchapternewpage on
@c@setchapternewpage odd
@settitle LIB BFD, the Binary File Descriptor Library
@titlepage
@title{libbfd}
@subtitle{The Binary File Descriptor Library}
@sp 1
@subtitle First Edition---BFD version < 2.0
@subtitle April 1991
@author {Steve Chamberlain}
@author {Cygnus Support}
@page

@tex
\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
\xdef\manvers{\$Revision: 1.12 $}  % For use in headers, footers too
{\parskip=0pt
\hfill Cygnus Support\par
\hfill sac\@cygnus.com\par
\hfill {\it BFD}, \manvers\par
\hfill \TeX{}info \texinfoversion\par
}
\global\parindent=0pt % Steve likes it this way
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1991 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, subject to the terms
of the GNU General Public License, which includes the provision that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage
@end iftex

@node Top, Overview, (dir), (dir)
@ifinfo
This file documents the binary file descriptor library libbfd.
@end ifinfo

@menu
* Overview::			Overview of BFD
* BFD front end::		BFD front end
* BFD back end::		BFD back end
* Index::			Index
@end menu

@node Overview, BFD front end, Top, Top
@chapter Introduction
@cindex BFD
@cindex what is it?
Simply put, BFD is a package which allows applications to use the
same routines to operate on object files whatever the object file
format.  A different object file format can be supported simply by
creating a new BFD back end and adding it to the library.

BFD is split into two parts; the front end and the many back ends.
@itemize @bullet
@item The front end of BFD provides the interface to the user. It manages
memory, and various canonical data structures. The front end also
decides which back end to use, and when to call back end routines.
@item The back ends provide BFD its view of the real world. Each back
end provides a set of calls which the BFD front end can use to maintain
its canonical form. The back ends also may keep around information for
their own use, for greater efficiency.
@end itemize
@menu
* History::			History
* How It Works::		How It Works
* What BFD Version 1 Can Do::	What BFD Version 1 Can Do
@end menu

@node History, How It Works, Overview, Overview
@section History

One spur behind BFD was the desire, on the part of the GNU 960 team at
Intel Oregon, for interoperability of applications on their COFF and
b.out file formats.  Cygnus was providing GNU support for the team, and
Cygnus was contracted to provide the required functionality.

The name came from a conversation David Wallace was having with Richard
Stallman about the library: RMS said that it would be quite hard---David
said ``BFD''.  Stallman was right, but the name stuck.

At the same time, Ready Systems wanted much the same thing, but for
different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
coff.

BFD was first implemented by members of Cygnus Support; Steve
Chamberlain (sac@@cygnus.com), John Gilmore (gnu@@cygnus.com), K.
Richard Pixley (rich@@cygnus.com) and David Henkel-Wallace
(gumby@@cygnus.com).



@node How It Works, What BFD Version 1 Can Do, History, Overview
@section How It Works

To use the library, include @code{bfd.h} and link with @code{libbfd.a}.	

BFD provides a common interface to the parts of an object file
for a calling application. 

When an application sucessfully opens a target file (object, archive or
whatever) a pointer to an internal structure is returned. This pointer
points to a structure called @code{bfd}, described in
@code{include/bfd.h}.  Our convention is to call this pointer a BFD, and
instances of it within code @code{abfd}.  All operations on
the target object file are applied as methods to the BFD.  The mapping is
defined within @code{bfd.h} in a set of macros, all beginning
@samp{bfd}_.

For example, this sequence would do what you would probably expect:
return the number of sections in an object file attached to a BFD
@code{abfd}. 

@lisp
@c @cartouche
#include "bfd.h"

unsigned int number_of_sections(abfd)
bfd *abfd;
@{
  return bfd_count_sections(abfd);
@}
@c @end cartouche
@end lisp

The abstraction used within BFD is that an object file has a header,
a number of sections containing raw data, a set of relocations, and some
symbol information. Also, BFDs opened for archives have the
additional attribute of an index and contain subordinate BFDs. This approach is
fine for a.out and coff, but loses efficiency when applied to formats
such as S-records and IEEE-695. 

@node What BFD Version 1 Can Do,  , How It Works, Overview
@section What BFD Version 1 Can Do
As different information from the the object files is required,
BFD reads from different sections of the file and processes them.
For example a very common operation for the linker is processing symbol
tables.  Each BFD back end provides a routine for converting
between the object file's representation of symbols and an internal
canonical format. When the linker asks for the symbol table of an object
file, it calls through the memory pointer to the relevant BFD
back end routine which reads and converts the table into a canonical
form.  The linker then operates upon the canonical form. When the link is
finished and the linker writes the output file's symbol table,
another BFD back end routine is called which takes the newly
created symbol table and converts it into the chosen output format.

@menu
* BFD information loss::	Information Loss
* Mechanism::			Mechanism 
@end menu

@node BFD information loss, Mechanism, What BFD Version 1 Can Do, What BFD Version 1 Can Do
@subsection Information Loss
@emph{Some information is lost due to the nature of the file format.} The output targets
supported by BFD do not provide identical facilities, and
information which may be described in one form has nowhere to go in
another format. One example of this is alignment information in
@code{b.out}. There is nowhere in an @code{a.out} format file to store
alignment information on the contained data, so when a file is linked
from @code{b.out} and an @code{a.out} image is produced, alignment
information will not propagate to the output file. (The linker will
still use the alignment information internally, so the link is performed
correctly).

Another example is COFF section names. COFF files may contain an
unlimited number of sections, each one with a textual section name. If
the target of the link is a format which does not have many sections (eg
@code{a.out}) or has sections without names (eg the Oasys format) the
link cannot be done simply. You can circumvent this problem by
describing the desired input-to-output section mapping with the linker command