bfd.texinfo revision 38889
133965Sjdp\input texinfo.tex 233965Sjdp@setfilename bfd.info 338889Sjdp@c $Id: bfd.texinfo,v 1.29 1997/07/22 18:47:29 ian Exp $ 433965Sjdp@tex 533965Sjdp% NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE 633965Sjdp\global\long\def\example{% 733965Sjdp\begingroup 833965Sjdp\let\aboveenvbreak=\par 933965Sjdp\let\afterenvbreak=\par 1033965Sjdp\parskip=0pt 1133965Sjdp\lisp} 1233965Sjdp\global\long\def\Eexample{% 1333965Sjdp\Elisp 1433965Sjdp\endgroup 1533965Sjdp\vskip -\parskip% to cancel out effect of following \par 1633965Sjdp} 1733965Sjdp@end tex 1833965Sjdp@synindex fn cp 1933965Sjdp 2033965Sjdp@ifinfo 2133965Sjdp@format 2233965SjdpSTART-INFO-DIR-ENTRY 2333965Sjdp* Bfd: (bfd). The Binary File Descriptor library. 2433965SjdpEND-INFO-DIR-ENTRY 2533965Sjdp@end format 2633965Sjdp@end ifinfo 2733965Sjdp 2833965Sjdp@ifinfo 2933965SjdpThis file documents the BFD library. 3033965Sjdp 3133965SjdpCopyright (C) 1991 Free Software Foundation, Inc. 3233965Sjdp 3333965SjdpPermission is granted to make and distribute verbatim copies of 3433965Sjdpthis manual provided the copyright notice and this permission notice 3533965Sjdpare preserved on all copies. 3633965Sjdp 3733965Sjdp@ignore 3833965SjdpPermission is granted to process this file through Tex and print the 3933965Sjdpresults, provided the printed document carries copying permission 4033965Sjdpnotice identical to this one except for the removal of this paragraph 4133965Sjdp(this paragraph not being relevant to the printed manual). 4233965Sjdp 4333965Sjdp@end ignore 4433965SjdpPermission is granted to copy and distribute modified versions of this 4533965Sjdpmanual under the conditions for verbatim copying, subject to the terms 4633965Sjdpof the GNU General Public License, which includes the provision that the 4733965Sjdpentire resulting derived work is distributed under the terms of a 4833965Sjdppermission notice identical to this one. 4933965Sjdp 5033965SjdpPermission is granted to copy and distribute translations of this manual 5133965Sjdpinto another language, under the above conditions for modified versions. 5233965Sjdp@end ifinfo 5333965Sjdp@iftex 5433965Sjdp@c@finalout 5533965Sjdp@setchapternewpage on 5633965Sjdp@c@setchapternewpage odd 5733965Sjdp@settitle LIB BFD, the Binary File Descriptor Library 5833965Sjdp@titlepage 5933965Sjdp@title{libbfd} 6033965Sjdp@subtitle{The Binary File Descriptor Library} 6133965Sjdp@sp 1 6233965Sjdp@subtitle First Edition---BFD version < 3.0 6333965Sjdp@subtitle April 1991 6433965Sjdp@author {Steve Chamberlain} 6533965Sjdp@author {Cygnus Support} 6633965Sjdp@page 6733965Sjdp 6833965Sjdp@tex 6933965Sjdp\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ 7038889Sjdp\xdef\manvers{\$Revision: 1.29 $} % For use in headers, footers too 7133965Sjdp{\parskip=0pt 7233965Sjdp\hfill Cygnus Support\par 7333965Sjdp\hfill sac\@cygnus.com\par 7433965Sjdp\hfill {\it BFD}, \manvers\par 7533965Sjdp\hfill \TeX{}info \texinfoversion\par 7633965Sjdp} 7733965Sjdp\global\parindent=0pt % Steve likes it this way 7833965Sjdp@end tex 7933965Sjdp 8033965Sjdp@vskip 0pt plus 1filll 8133965SjdpCopyright @copyright{} 1991 Free Software Foundation, Inc. 8233965Sjdp 8333965SjdpPermission is granted to make and distribute verbatim copies of 8433965Sjdpthis manual provided the copyright notice and this permission notice 8533965Sjdpare preserved on all copies. 8633965Sjdp 8733965SjdpPermission is granted to copy and distribute modified versions of this 8833965Sjdpmanual under the conditions for verbatim copying, subject to the terms 8933965Sjdpof the GNU General Public License, which includes the provision that the 9033965Sjdpentire resulting derived work is distributed under the terms of a 9133965Sjdppermission notice identical to this one. 9233965Sjdp 9333965SjdpPermission is granted to copy and distribute translations of this manual 9433965Sjdpinto another language, under the above conditions for modified versions. 9533965Sjdp@end titlepage 9633965Sjdp@end iftex 9733965Sjdp 9833965Sjdp@node Top, Overview, (dir), (dir) 9933965Sjdp@ifinfo 10033965SjdpThis file documents the binary file descriptor library libbfd. 10133965Sjdp@end ifinfo 10233965Sjdp 10333965Sjdp@menu 10433965Sjdp* Overview:: Overview of BFD 10533965Sjdp* BFD front end:: BFD front end 10633965Sjdp* BFD back ends:: BFD back ends 10733965Sjdp* Index:: Index 10833965Sjdp@end menu 10933965Sjdp 11033965Sjdp@node Overview, BFD front end, Top, Top 11133965Sjdp@chapter Introduction 11233965Sjdp@cindex BFD 11333965Sjdp@cindex what is it? 11433965SjdpBFD is a package which allows applications to use the 11533965Sjdpsame routines to operate on object files whatever the object file 11633965Sjdpformat. A new object file format can be supported simply by 11733965Sjdpcreating a new BFD back end and adding it to the library. 11833965Sjdp 11933965SjdpBFD is split into two parts: the front end, and the back ends (one for 12033965Sjdpeach object file format). 12133965Sjdp@itemize @bullet 12233965Sjdp@item The front end of BFD provides the interface to the user. It manages 12333965Sjdpmemory and various canonical data structures. The front end also 12433965Sjdpdecides which back end to use and when to call back end routines. 12533965Sjdp@item The back ends provide BFD its view of the real world. Each back 12633965Sjdpend provides a set of calls which the BFD front end can use to maintain 12733965Sjdpits canonical form. The back ends also may keep around information for 12833965Sjdptheir own use, for greater efficiency. 12933965Sjdp@end itemize 13033965Sjdp@menu 13133965Sjdp* History:: History 13233965Sjdp* How It Works:: How It Works 13333965Sjdp* What BFD Version 2 Can Do:: What BFD Version 2 Can Do 13433965Sjdp@end menu 13533965Sjdp 13633965Sjdp@node History, How It Works, Overview, Overview 13733965Sjdp@section History 13833965Sjdp 13933965SjdpOne spur behind BFD was the desire, on the part of the GNU 960 team at 14033965SjdpIntel Oregon, for interoperability of applications on their COFF and 14133965Sjdpb.out file formats. Cygnus was providing GNU support for the team, and 14233965Sjdpwas contracted to provide the required functionality. 14333965Sjdp 14433965SjdpThe name came from a conversation David Wallace was having with Richard 14533965SjdpStallman about the library: RMS said that it would be quite hard---David 14633965Sjdpsaid ``BFD''. Stallman was right, but the name stuck. 14733965Sjdp 14833965SjdpAt the same time, Ready Systems wanted much the same thing, but for 14933965Sjdpdifferent object file formats: IEEE-695, Oasys, Srecords, a.out and 68k 15033965Sjdpcoff. 15133965Sjdp 15233965SjdpBFD was first implemented by members of Cygnus Support; Steve 15333965SjdpChamberlain (@code{sac@@cygnus.com}), John Gilmore 15433965Sjdp(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) 15533965Sjdpand David Henkel-Wallace (@code{gumby@@cygnus.com}). 15633965Sjdp 15733965Sjdp 15833965Sjdp 15933965Sjdp@node How It Works, What BFD Version 2 Can Do, History, Overview 16033965Sjdp@section How To Use BFD 16133965Sjdp 16233965SjdpTo use the library, include @file{bfd.h} and link with @file{libbfd.a}. 16333965Sjdp 16433965SjdpBFD provides a common interface to the parts of an object file 16533965Sjdpfor a calling application. 16633965Sjdp 16733965SjdpWhen an application sucessfully opens a target file (object, archive, or 16833965Sjdpwhatever), a pointer to an internal structure is returned. This pointer 16933965Sjdppoints to a structure called @code{bfd}, described in 17033965Sjdp@file{bfd.h}. Our convention is to call this pointer a BFD, and 17133965Sjdpinstances of it within code @code{abfd}. All operations on 17233965Sjdpthe target object file are applied as methods to the BFD. The mapping is 17333965Sjdpdefined within @code{bfd.h} in a set of macros, all beginning 17433965Sjdpwith @samp{bfd_} to reduce namespace pollution. 17533965Sjdp 17633965SjdpFor example, this sequence does what you would probably expect: 17733965Sjdpreturn the number of sections in an object file attached to a BFD 17833965Sjdp@code{abfd}. 17933965Sjdp 18033965Sjdp@lisp 18133965Sjdp@c @cartouche 18233965Sjdp#include "bfd.h" 18333965Sjdp 18433965Sjdpunsigned int number_of_sections(abfd) 18533965Sjdpbfd *abfd; 18633965Sjdp@{ 18733965Sjdp return bfd_count_sections(abfd); 18833965Sjdp@} 18933965Sjdp@c @end cartouche 19033965Sjdp@end lisp 19133965Sjdp 19233965SjdpThe abstraction used within BFD is that an object file has: 19333965Sjdp 19433965Sjdp@itemize @bullet 19533965Sjdp@item 19633965Sjdpa header, 19733965Sjdp@item 19833965Sjdpa number of sections containing raw data (@pxref{Sections}), 19933965Sjdp@item 20033965Sjdpa set of relocations (@pxref{Relocations}), and 20133965Sjdp@item 20233965Sjdpsome symbol information (@pxref{Symbols}). 20333965Sjdp@end itemize 20433965Sjdp@noindent 20533965SjdpAlso, BFDs opened for archives have the additional attribute of an index 20633965Sjdpand contain subordinate BFDs. This approach is fine for a.out and coff, 20733965Sjdpbut loses efficiency when applied to formats such as S-records and 20833965SjdpIEEE-695. 20933965Sjdp 21033965Sjdp@node What BFD Version 2 Can Do, , How It Works, Overview 21133965Sjdp@section What BFD Version 2 Can Do 21233965Sjdp@include bfdsumm.texi 21333965Sjdp 21433965Sjdp@node BFD front end, BFD back ends, Overview, Top 21533965Sjdp@chapter BFD front end 21638889Sjdp@include bfdt.texi 21733965Sjdp 21833965Sjdp@menu 21933965Sjdp* Memory Usage:: 22033965Sjdp* Initialization:: 22133965Sjdp* Sections:: 22233965Sjdp* Symbols:: 22333965Sjdp* Archives:: 22433965Sjdp* Formats:: 22533965Sjdp* Relocations:: 22633965Sjdp* Core Files:: 22733965Sjdp* Targets:: 22833965Sjdp* Architectures:: 22933965Sjdp* Opening and Closing:: 23033965Sjdp* Internal:: 23133965Sjdp* File Caching:: 23233965Sjdp* Linker Functions:: 23333965Sjdp* Hash Tables:: 23433965Sjdp@end menu 23533965Sjdp 23633965Sjdp@node Memory Usage, Initialization, BFD front end, BFD front end 23733965Sjdp@section Memory usage 23833965SjdpBFD keeps all of its internal structures in obstacks. There is one obstack 23933965Sjdpper open BFD file, into which the current state is stored. When a BFD is 24033965Sjdpclosed, the obstack is deleted, and so everything which has been 24133965Sjdpallocated by BFD for the closing file is thrown away. 24233965Sjdp 24333965SjdpBFD does not free anything created by an application, but pointers into 24433965Sjdp@code{bfd} structures become invalid on a @code{bfd_close}; for example, 24533965Sjdpafter a @code{bfd_close} the vector passed to 24633965Sjdp@code{bfd_canonicalize_symtab} is still around, since it has been 24733965Sjdpallocated by the application, but the data that it pointed to are 24833965Sjdplost. 24933965Sjdp 25033965SjdpThe general rule is to not close a BFD until all operations dependent 25133965Sjdpupon data from the BFD have been completed, or all the data from within 25233965Sjdpthe file has been copied. To help with the management of memory, there 25333965Sjdpis a function (@code{bfd_alloc_size}) which returns the number of bytes 25433965Sjdpin obstacks associated with the supplied BFD. This could be used to 25533965Sjdpselect the greediest open BFD, close it to reclaim the memory, perform 25633965Sjdpsome operation and reopen the BFD again, to get a fresh copy of the data 25733965Sjdpstructures. 25833965Sjdp 25933965Sjdp@node Initialization, Sections, Memory Usage, BFD front end 26033965Sjdp@include init.texi 26133965Sjdp 26233965Sjdp@node Sections, Symbols, Initialization, BFD front end 26333965Sjdp@include section.texi 26433965Sjdp 26533965Sjdp@node Symbols, Archives, Sections, BFD front end 26633965Sjdp@include syms.texi 26733965Sjdp 26833965Sjdp@node Archives, Formats, Symbols, BFD front end 26933965Sjdp@include archive.texi 27033965Sjdp 27133965Sjdp@node Formats, Relocations, Archives, BFD front end 27233965Sjdp@include format.texi 27333965Sjdp 27433965Sjdp@node Relocations, Core Files, Formats, BFD front end 27533965Sjdp@include reloc.texi 27633965Sjdp 27733965Sjdp@node Core Files, Targets, Relocations, BFD front end 27833965Sjdp@include core.texi 27933965Sjdp 28033965Sjdp@node Targets, Architectures, Core Files, BFD front end 28133965Sjdp@include targets.texi 28233965Sjdp 28333965Sjdp@node Architectures, Opening and Closing, Targets, BFD front end 28433965Sjdp@include archures.texi 28533965Sjdp 28633965Sjdp@node Opening and Closing, Internal, Architectures, BFD front end 28733965Sjdp@include opncls.texi 28833965Sjdp 28933965Sjdp@node Internal, File Caching, Opening and Closing, BFD front end 29033965Sjdp@include libbfd.texi 29133965Sjdp 29233965Sjdp@node File Caching, Linker Functions, Internal, BFD front end 29333965Sjdp@include cache.texi 29433965Sjdp 29533965Sjdp@node Linker Functions, Hash Tables, File Caching, BFD front end 29633965Sjdp@include linker.texi 29733965Sjdp 29833965Sjdp@node Hash Tables, , Linker Functions, BFD front end 29933965Sjdp@include hash.texi 30033965Sjdp 30133965Sjdp@node BFD back ends, Index, BFD front end, Top 30233965Sjdp@chapter BFD back ends 30333965Sjdp@menu 30433965Sjdp* What to Put Where:: 30533965Sjdp* aout :: a.out backends 30633965Sjdp* coff :: coff backends 30733965Sjdp* elf :: elf backends 30833965Sjdp@ignore 30933965Sjdp* oasys :: oasys backends 31033965Sjdp* ieee :: ieee backend 31133965Sjdp* srecord :: s-record backend 31233965Sjdp@end ignore 31333965Sjdp@end menu 31433965Sjdp@node What to Put Where, aout, BFD back ends, BFD back ends 31533965SjdpAll of BFD lives in one directory. 31633965Sjdp 31733965Sjdp@node aout, coff, What to Put Where, BFD back ends 31833965Sjdp@include aoutx.texi 31933965Sjdp 32033965Sjdp@node coff, elf, aout, BFD back ends 32133965Sjdp@include coffcode.texi 32233965Sjdp 32333965Sjdp@node elf, , coff, BFD back ends 32433965Sjdp@include elf.texi 32533965Sjdp@c Leave this out until the file has some actual contents... 32633965Sjdp@c @include elfcode.texi 32733965Sjdp 32833965Sjdp@node Index, , BFD back ends , Top 32933965Sjdp@unnumbered Index 33033965Sjdp@printindex cp 33133965Sjdp 33233965Sjdp@tex 33333965Sjdp% I think something like @colophon should be in texinfo. In the 33433965Sjdp% meantime: 33533965Sjdp\long\def\colophon{\hbox to0pt{}\vfill 33633965Sjdp\centerline{The body of this manual is set in} 33733965Sjdp\centerline{\fontname\tenrm,} 33833965Sjdp\centerline{with headings in {\bf\fontname\tenbf}} 33933965Sjdp\centerline{and examples in {\tt\fontname\tentt}.} 34033965Sjdp\centerline{{\it\fontname\tenit\/} and} 34133965Sjdp\centerline{{\sl\fontname\tensl\/}} 34233965Sjdp\centerline{are used for emphasis.}\vfill} 34333965Sjdp\page\colophon 34433965Sjdp% Blame: doc@cygnus.com, 28mar91. 34533965Sjdp@end tex 34633965Sjdp 34733965Sjdp@contents 34833965Sjdp@bye 349