340 lines
10 KiB
Text
340 lines
10 KiB
Text
|
\input texinfo.tex
|
||
|
|
@setfilename bfd.info
|
||
|
|
@c Copyright (C) 1988-2022 Free Software Foundation, Inc.
|
||
|
|
@c
|
||
|
|
@synindex fn cp
|
||
|
|
|
||
|
|
@ifnottex
|
||
|
|
@dircategory Software development
|
||
|
|
@direntry
|
||
|
|
* Bfd: (bfd). The Binary File Descriptor library.
|
||
|
|
@end direntry
|
||
|
|
@end ifnottex
|
||
|
|
|
||
|
|
@copying
|
||
|
|
This file documents the BFD library.
|
||
|
|
|
||
|
|
Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with the
|
||
|
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
||
|
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
||
|
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
||
|
|
included in the section entitled ``GNU Free Documentation License''.
|
||
|
|
|
||
|
|
(a) The FSF's Front-Cover Text is:
|
||
|
|
|
||
|
|
A GNU Manual
|
||
|
|
|
||
|
|
(b) The FSF's Back-Cover Text is:
|
||
|
|
|
||
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
||
|
|
software. Copies published by the Free Software Foundation raise
|
||
|
|
funds for GNU development.
|
||
|
|
@end copying
|
||
|
|
@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 < 3.0 % Since no product is stable before version 3.0 :-)
|
||
|
|
@subtitle Original Document Created: April 1991
|
||
|
|
@author {Steve Chamberlain}
|
||
|
|
@author {Cygnus Support}
|
||
|
|
@page
|
||
|
|
|
||
|
|
@tex
|
||
|
|
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
|
||
|
|
\xdef\manvers{1.5} % For use in headers, footers too
|
||
|
|
{\parskip=0pt
|
||
|
|
\hfill Free Software Foundation\par
|
||
|
|
\hfill sac\@www.gnu.org\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-2022 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
||
|
|
or any later version published by the Free Software Foundation;
|
||
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
||
|
|
Back-Cover Texts. A copy of the license is included in the
|
||
|
|
section entitled ``GNU Free Documentation License''.
|
||
|
|
|
||
|
|
@end titlepage
|
||
|
|
@end iftex
|
||
|
|
@contents
|
||
|
|
|
||
|
|
@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 ends:: BFD back ends
|
||
|
|
* GNU Free Documentation License:: GNU Free Documentation License
|
||
|
|
* BFD Index:: BFD Index
|
||
|
|
@end menu
|
||
|
|
|
||
|
|
@node Overview, BFD front end, Top, Top
|
||
|
|
@chapter Introduction
|
||
|
|
@cindex BFD
|
||
|
|
@cindex what is it?
|
||
|
|
BFD is a package which allows applications to use the
|
||
|
|
same routines to operate on object files whatever the object file
|
||
|
|
format. A new 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 back ends (one for
|
||
|
|
each object file format).
|
||
|
|
@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 2 Can Do:: What BFD Version 2 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
|
||
|
|
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 (@code{sac@@cygnus.com}), John Gilmore
|
||
|
|
(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com})
|
||
|
|
and David Henkel-Wallace (@code{gumby@@cygnus.com}).
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
@node How It Works, What BFD Version 2 Can Do, History, Overview
|
||
|
|
@section How To Use BFD
|
||
|
|
|
||
|
|
To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
|
||
|
|
|
||
|
|
BFD provides a common interface to the parts of an object file
|
||
|
|
for a calling application.
|
||
|
|
|
||
|
|
When an application successfully 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
|
||
|
|
@file{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
|
||
|
|
with @samp{bfd_} to reduce namespace pollution.
|
||
|
|
|
||
|
|
For example, this sequence does what you would probably expect:
|
||
|
|
return the number of sections in an object file attached to a BFD
|
||
|
|
@code{abfd}.
|
||
|
|
|
||
|
|
@example
|
||
|
|
@c @cartouche
|
||
|
|
#include "bfd.h"
|
||
|
|
|
||
|
|
unsigned int number_of_sections (abfd)
|
||
|
|
bfd *abfd;
|
||
|
|
@{
|
||
|
|
return bfd_count_sections (abfd);
|
||
|
|
@}
|
||
|
|
@c @end cartouche
|
||
|
|
@end example
|
||
|
|
|
||
|
|
The abstraction used within BFD is that an object file has:
|
||
|
|
|
||
|
|
@itemize @bullet
|
||
|
|
@item
|
||
|
|
a header,
|
||
|
|
@item
|
||
|
|
a number of sections containing raw data (@pxref{Sections}),
|
||
|
|
@item
|
||
|
|
a set of relocations (@pxref{Relocations}), and
|
||
|
|
@item
|
||
|
|
some symbol information (@pxref{Symbols}).
|
||
|
|
@end itemize
|
||
|
|
@noindent
|
||
|
|
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 2 Can Do, , How It Works, Overview
|
||
|
|
@section What BFD Version 2 Can Do
|
||
|
|
@include bfdsumm.texi
|
||
|
|
|
||
|
|
@node BFD front end, BFD back ends, Overview, Top
|
||
|
|
@chapter BFD Front End
|
||
|
|
|
||
|
|
@menu
|
||
|
|
* typedef bfd::
|
||
|
|
* Error reporting::
|
||
|
|
* Miscellaneous::
|
||
|
|
* Memory Usage::
|
||
|
|
* Initialization::
|
||
|
|
* Sections::
|
||
|
|
* Symbols::
|
||
|
|
* Archives::
|
||
|
|
* Formats::
|
||
|
|
* Relocations::
|
||
|
|
* Core Files::
|
||
|
|
* Targets::
|
||
|
|
* Architectures::
|
||
|
|
* Opening and Closing::
|
||
|
|
* Internal::
|
||
|
|
* File Caching::
|
||
|
|
* Linker Functions::
|
||
|
|
* Hash Tables::
|
||
|
|
@end menu
|
||
|
|
|
||
|
|
@include bfdt.texi
|
||
|
|
@include bfdio.texi
|
||
|
|
|
||
|
|
@node Memory Usage, Initialization, Miscellaneous, BFD front end
|
||
|
|
@section Memory Usage
|
||
|
|
BFD keeps all of its internal structures in obstacks. There is one obstack
|
||
|
|
per open BFD file, into which the current state is stored. When a BFD is
|
||
|
|
closed, the obstack is deleted, and so everything which has been
|
||
|
|
allocated by BFD for the closing file is thrown away.
|
||
|
|
|
||
|
|
BFD does not free anything created by an application, but pointers into
|
||
|
|
@code{bfd} structures become invalid on a @code{bfd_close}; for example,
|
||
|
|
after a @code{bfd_close} the vector passed to
|
||
|
|
@code{bfd_canonicalize_symtab} is still around, since it has been
|
||
|
|
allocated by the application, but the data that it pointed to are
|
||
|
|
lost.
|
||
|
|
|
||
|
|
The general rule is to not close a BFD until all operations dependent
|
||
|
|
upon data from the BFD have been completed, or all the data from within
|
||
|
|
the file has been copied. To help with the management of memory, there
|
||
|
|
is a function (@code{bfd_alloc_size}) which returns the number of bytes
|
||
|
|
in obstacks associated with the supplied BFD. This could be used to
|
||
|
|
select the greediest open BFD, close it to reclaim the memory, perform
|
||
|
|
some operation and reopen the BFD again, to get a fresh copy of the data
|
||
|
|
structures.
|
||
|
|
|
||
|
|
@node Initialization, Sections, Memory Usage, BFD front end
|
||
|
|
@include init.texi
|
||
|
|
|
||
|
|
@node Sections, Symbols, Initialization, BFD front end
|
||
|
|
@include section.texi
|
||
|
|
|
||
|
|
@node Symbols, Archives, Sections, BFD front end
|
||
|
|
@include syms.texi
|
||
|
|
|
||
|
|
@node Archives, Formats, Symbols, BFD front end
|
||
|
|
@include archive.texi
|
||
|
|
|
||
|
|
@node Formats, Relocations, Archives, BFD front end
|
||
|
|
@include format.texi
|
||
|
|
|
||
|
|
@node Relocations, Core Files, Formats, BFD front end
|
||
|
|
@include reloc.texi
|
||
|
|
|
||
|
|
@node Core Files, Targets, Relocations, BFD front end
|
||
|
|
@include corefile.texi
|
||
|
|
|
||
|
|
@node Targets, Architectures, Core Files, BFD front end
|
||
|
|
@include targets.texi
|
||
|
|
|
||
|
|
@node Architectures, Opening and Closing, Targets, BFD front end
|
||
|
|
@include archures.texi
|
||
|
|
|
||
|
|
@node Opening and Closing, Internal, Architectures, BFD front end
|
||
|
|
@include opncls.texi
|
||
|
|
|
||
|
|
@node Internal, File Caching, Opening and Closing, BFD front end
|
||
|
|
@include libbfd.texi
|
||
|
|
|
||
|
|
@node File Caching, Linker Functions, Internal, BFD front end
|
||
|
|
@include cache.texi
|
||
|
|
|
||
|
|
@node Linker Functions, Hash Tables, File Caching, BFD front end
|
||
|
|
@include linker.texi
|
||
|
|
|
||
|
|
@node Hash Tables, , Linker Functions, BFD front end
|
||
|
|
@include hash.texi
|
||
|
|
|
||
|
|
@node BFD back ends, GNU Free Documentation License, BFD front end, Top
|
||
|
|
@chapter BFD back ends
|
||
|
|
@menu
|
||
|
|
* What to Put Where::
|
||
|
|
* aout :: a.out backends
|
||
|
|
* coff :: coff backends
|
||
|
|
* elf :: elf backends
|
||
|
|
* mmo :: mmo backend
|
||
|
|
@ignore
|
||
|
|
* srecord :: s-record backend
|
||
|
|
@end ignore
|
||
|
|
@end menu
|
||
|
|
@node What to Put Where, aout, BFD back ends, BFD back ends
|
||
|
|
@section What to Put Where
|
||
|
|
All of BFD lives in one directory.
|
||
|
|
|
||
|
|
@node aout, coff, What to Put Where, BFD back ends
|
||
|
|
@include aoutx.texi
|
||
|
|
|
||
|
|
@node coff, elf, aout, BFD back ends
|
||
|
|
@include coffcode.texi
|
||
|
|
|
||
|
|
@node elf, mmo, coff, BFD back ends
|
||
|
|
@include elf.texi
|
||
|
|
@c Leave this out until the file has some actual contents...
|
||
|
|
@c @include elfcode.texi
|
||
|
|
|
||
|
|
@node mmo, , elf, BFD back ends
|
||
|
|
@include mmo.texi
|
||
|
|
|
||
|
|
@node GNU Free Documentation License, BFD Index, BFD back ends, Top
|
||
|
|
@include fdl.texi
|
||
|
|
|
||
|
|
@node BFD Index, , GNU Free Documentation License, Top
|
||
|
|
@unnumbered BFD Index
|
||
|
|
@printindex cp
|
||
|
|
|
||
|
|
@tex
|
||
|
|
% I think something like @@colophon should be in texinfo. In the
|
||
|
|
% meantime:
|
||
|
|
\long\def\colophon{\hbox to0pt{}\vfill
|
||
|
|
\centerline{The body of this manual is set in}
|
||
|
|
\centerline{\fontname\tenrm,}
|
||
|
|
\centerline{with headings in {\bf\fontname\tenbf}}
|
||
|
|
\centerline{and examples in {\tt\fontname\tentt}.}
|
||
|
|
\centerline{{\it\fontname\tenit\/} and}
|
||
|
|
\centerline{{\sl\fontname\tensl\/}}
|
||
|
|
\centerline{are used for emphasis.}\vfill}
|
||
|
|
\page\colophon
|
||
|
|
% Blame: doc@@cygnus.com, 28mar91.
|
||
|
|
@end tex
|
||
|
|
|
||
|
|
@bye
|