133965Sjdp\input texinfo.tex 233965Sjdp@setfilename bfd.info 3218822Sdim@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000, 4218822Sdim@c 2001, 2002, 2003, 2006, 2007 578828Sobrien@c Free Software Foundation, Inc. 678828Sobrien@c 733965Sjdp@synindex fn cp 833965Sjdp 933965Sjdp@ifinfo 1033965Sjdp@format 1133965SjdpSTART-INFO-DIR-ENTRY 1233965Sjdp* Bfd: (bfd). The Binary File Descriptor library. 1333965SjdpEND-INFO-DIR-ENTRY 1433965Sjdp@end format 1533965Sjdp@end ifinfo 1633965Sjdp 17218822Sdim@copying 1833965SjdpThis file documents the BFD library. 1933965Sjdp 20218822SdimCopyright @copyright{} 1991, 2000, 2001, 2003, 2006, 2007 Free Software Foundation, Inc. 2133965Sjdp 22218822SdimPermission is granted to copy, distribute and/or modify this document 23218822Sdimunder the terms of the GNU Free Documentation License, Version 1.1 or 24218822Sdimany later version published by the Free Software Foundation; with the 25218822SdimInvariant Sections being ``GNU General Public License'' and ``Funding 26218822SdimFree Software'', the Front-Cover texts being (a) (see below), and with 27218822Sdimthe Back-Cover Texts being (b) (see below). A copy of the license is 28218822Sdimincluded in the section entitled ``GNU Free Documentation License''. 2933965Sjdp 30218822Sdim(a) The FSF's Front-Cover Text is: 3133965Sjdp 32218822Sdim A GNU Manual 33218822Sdim 34218822Sdim(b) The FSF's Back-Cover Text is: 35218822Sdim 36218822Sdim You have freedom to copy and modify this GNU Manual, like GNU 37218822Sdim software. Copies published by the Free Software Foundation raise 38218822Sdim funds for GNU development. 39218822Sdim@end copying 4033965Sjdp@iftex 4133965Sjdp@c@finalout 4233965Sjdp@setchapternewpage on 4333965Sjdp@c@setchapternewpage odd 4433965Sjdp@settitle LIB BFD, the Binary File Descriptor Library 4533965Sjdp@titlepage 4633965Sjdp@title{libbfd} 4733965Sjdp@subtitle{The Binary File Descriptor Library} 4833965Sjdp@sp 1 49218822Sdim@subtitle First Edition---BFD version < 3.0 % Since no product is stable before version 3.0 :-) 5089857Sobrien@subtitle Original Document Created: April 1991 5133965Sjdp@author {Steve Chamberlain} 5233965Sjdp@author {Cygnus Support} 5333965Sjdp@page 5433965Sjdp 5533965Sjdp@tex 5633965Sjdp\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ 57130561Sobrien\xdef\manvers{1.5} % For use in headers, footers too 5833965Sjdp{\parskip=0pt 5989857Sobrien\hfill Free Software Foundation\par 6089857Sobrien\hfill sac\@www.gnu.org\par 6133965Sjdp\hfill {\it BFD}, \manvers\par 6233965Sjdp\hfill \TeX{}info \texinfoversion\par 6333965Sjdp} 6433965Sjdp\global\parindent=0pt % Steve likes it this way 6533965Sjdp@end tex 6633965Sjdp 6733965Sjdp@vskip 0pt plus 1filll 68218822SdimCopyright @copyright{} 1991, 2001, 2003, 2006 Free Software Foundation, Inc. 6933965Sjdp 7077298Sobrien Permission is granted to copy, distribute and/or modify this document 7177298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 7277298Sobrien or any later version published by the Free Software Foundation; 7377298Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 7477298Sobrien Back-Cover Texts. A copy of the license is included in the 75130561Sobrien section entitled ``GNU Free Documentation License''. 7633965Sjdp 7733965Sjdp@end titlepage 7833965Sjdp@end iftex 79218822Sdim@contents 8033965Sjdp 8133965Sjdp@node Top, Overview, (dir), (dir) 8233965Sjdp@ifinfo 8333965SjdpThis file documents the binary file descriptor library libbfd. 8433965Sjdp@end ifinfo 8533965Sjdp 8633965Sjdp@menu 8733965Sjdp* Overview:: Overview of BFD 8833965Sjdp* BFD front end:: BFD front end 8933965Sjdp* BFD back ends:: BFD back ends 9077298Sobrien* GNU Free Documentation License:: GNU Free Documentation License 91218822Sdim* BFD Index:: BFD Index 9233965Sjdp@end menu 9333965Sjdp 9433965Sjdp@node Overview, BFD front end, Top, Top 9533965Sjdp@chapter Introduction 9633965Sjdp@cindex BFD 9733965Sjdp@cindex what is it? 9833965SjdpBFD is a package which allows applications to use the 9933965Sjdpsame routines to operate on object files whatever the object file 10033965Sjdpformat. A new object file format can be supported simply by 10133965Sjdpcreating a new BFD back end and adding it to the library. 10233965Sjdp 10333965SjdpBFD is split into two parts: the front end, and the back ends (one for 10433965Sjdpeach object file format). 10533965Sjdp@itemize @bullet 10633965Sjdp@item The front end of BFD provides the interface to the user. It manages 10733965Sjdpmemory and various canonical data structures. The front end also 10833965Sjdpdecides which back end to use and when to call back end routines. 10933965Sjdp@item The back ends provide BFD its view of the real world. Each back 11033965Sjdpend provides a set of calls which the BFD front end can use to maintain 11133965Sjdpits canonical form. The back ends also may keep around information for 11233965Sjdptheir own use, for greater efficiency. 11333965Sjdp@end itemize 11433965Sjdp@menu 11533965Sjdp* History:: History 11633965Sjdp* How It Works:: How It Works 11733965Sjdp* What BFD Version 2 Can Do:: What BFD Version 2 Can Do 11833965Sjdp@end menu 11933965Sjdp 12033965Sjdp@node History, How It Works, Overview, Overview 12133965Sjdp@section History 12233965Sjdp 12333965SjdpOne spur behind BFD was the desire, on the part of the GNU 960 team at 12433965SjdpIntel Oregon, for interoperability of applications on their COFF and 12533965Sjdpb.out file formats. Cygnus was providing GNU support for the team, and 12633965Sjdpwas contracted to provide the required functionality. 12733965Sjdp 12833965SjdpThe name came from a conversation David Wallace was having with Richard 12933965SjdpStallman about the library: RMS said that it would be quite hard---David 13033965Sjdpsaid ``BFD''. Stallman was right, but the name stuck. 13133965Sjdp 13233965SjdpAt the same time, Ready Systems wanted much the same thing, but for 13333965Sjdpdifferent object file formats: IEEE-695, Oasys, Srecords, a.out and 68k 13433965Sjdpcoff. 13533965Sjdp 13633965SjdpBFD was first implemented by members of Cygnus Support; Steve 13733965SjdpChamberlain (@code{sac@@cygnus.com}), John Gilmore 13833965Sjdp(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) 13933965Sjdpand David Henkel-Wallace (@code{gumby@@cygnus.com}). 14033965Sjdp 14133965Sjdp 14233965Sjdp 14333965Sjdp@node How It Works, What BFD Version 2 Can Do, History, Overview 14433965Sjdp@section How To Use BFD 14533965Sjdp 14633965SjdpTo use the library, include @file{bfd.h} and link with @file{libbfd.a}. 14733965Sjdp 14833965SjdpBFD provides a common interface to the parts of an object file 14933965Sjdpfor a calling application. 15033965Sjdp 151218822SdimWhen an application successfully opens a target file (object, archive, or 15233965Sjdpwhatever), a pointer to an internal structure is returned. This pointer 15333965Sjdppoints to a structure called @code{bfd}, described in 15433965Sjdp@file{bfd.h}. Our convention is to call this pointer a BFD, and 15533965Sjdpinstances of it within code @code{abfd}. All operations on 15633965Sjdpthe target object file are applied as methods to the BFD. The mapping is 15733965Sjdpdefined within @code{bfd.h} in a set of macros, all beginning 15833965Sjdpwith @samp{bfd_} to reduce namespace pollution. 15933965Sjdp 16033965SjdpFor example, this sequence does what you would probably expect: 16133965Sjdpreturn the number of sections in an object file attached to a BFD 16233965Sjdp@code{abfd}. 16333965Sjdp 164130561Sobrien@example 16533965Sjdp@c @cartouche 16633965Sjdp#include "bfd.h" 16733965Sjdp 168130561Sobrienunsigned int number_of_sections (abfd) 16933965Sjdpbfd *abfd; 17033965Sjdp@{ 171130561Sobrien return bfd_count_sections (abfd); 17233965Sjdp@} 17333965Sjdp@c @end cartouche 174130561Sobrien@end example 17533965Sjdp 17633965SjdpThe abstraction used within BFD is that an object file has: 17733965Sjdp 17833965Sjdp@itemize @bullet 17933965Sjdp@item 18033965Sjdpa header, 18133965Sjdp@item 18233965Sjdpa number of sections containing raw data (@pxref{Sections}), 18333965Sjdp@item 18433965Sjdpa set of relocations (@pxref{Relocations}), and 18533965Sjdp@item 18633965Sjdpsome symbol information (@pxref{Symbols}). 18733965Sjdp@end itemize 18833965Sjdp@noindent 18933965SjdpAlso, BFDs opened for archives have the additional attribute of an index 19033965Sjdpand contain subordinate BFDs. This approach is fine for a.out and coff, 19133965Sjdpbut loses efficiency when applied to formats such as S-records and 19233965SjdpIEEE-695. 19333965Sjdp 19433965Sjdp@node What BFD Version 2 Can Do, , How It Works, Overview 19533965Sjdp@section What BFD Version 2 Can Do 19633965Sjdp@include bfdsumm.texi 19733965Sjdp 19833965Sjdp@node BFD front end, BFD back ends, Overview, Top 199130561Sobrien@chapter BFD Front End 20038889Sjdp@include bfdt.texi 201130561Sobrien@include bfdio.texi 20233965Sjdp 20333965Sjdp@menu 20433965Sjdp* Memory Usage:: 20533965Sjdp* Initialization:: 20633965Sjdp* Sections:: 20733965Sjdp* Symbols:: 20833965Sjdp* Archives:: 20933965Sjdp* Formats:: 21033965Sjdp* Relocations:: 21133965Sjdp* Core Files:: 21233965Sjdp* Targets:: 21333965Sjdp* Architectures:: 21433965Sjdp* Opening and Closing:: 21533965Sjdp* Internal:: 21633965Sjdp* File Caching:: 21733965Sjdp* Linker Functions:: 21833965Sjdp* Hash Tables:: 21933965Sjdp@end menu 22033965Sjdp 22133965Sjdp@node Memory Usage, Initialization, BFD front end, BFD front end 222130561Sobrien@section Memory Usage 22333965SjdpBFD keeps all of its internal structures in obstacks. There is one obstack 22433965Sjdpper open BFD file, into which the current state is stored. When a BFD is 22533965Sjdpclosed, the obstack is deleted, and so everything which has been 22633965Sjdpallocated by BFD for the closing file is thrown away. 22733965Sjdp 22833965SjdpBFD does not free anything created by an application, but pointers into 22933965Sjdp@code{bfd} structures become invalid on a @code{bfd_close}; for example, 23033965Sjdpafter a @code{bfd_close} the vector passed to 23133965Sjdp@code{bfd_canonicalize_symtab} is still around, since it has been 23233965Sjdpallocated by the application, but the data that it pointed to are 23333965Sjdplost. 23433965Sjdp 23533965SjdpThe general rule is to not close a BFD until all operations dependent 23633965Sjdpupon data from the BFD have been completed, or all the data from within 23733965Sjdpthe file has been copied. To help with the management of memory, there 23833965Sjdpis a function (@code{bfd_alloc_size}) which returns the number of bytes 23933965Sjdpin obstacks associated with the supplied BFD. This could be used to 24033965Sjdpselect the greediest open BFD, close it to reclaim the memory, perform 24133965Sjdpsome operation and reopen the BFD again, to get a fresh copy of the data 24233965Sjdpstructures. 24333965Sjdp 24433965Sjdp@node Initialization, Sections, Memory Usage, BFD front end 24533965Sjdp@include init.texi 24633965Sjdp 24733965Sjdp@node Sections, Symbols, Initialization, BFD front end 24833965Sjdp@include section.texi 24933965Sjdp 25033965Sjdp@node Symbols, Archives, Sections, BFD front end 25133965Sjdp@include syms.texi 25233965Sjdp 25333965Sjdp@node Archives, Formats, Symbols, BFD front end 25433965Sjdp@include archive.texi 25533965Sjdp 25633965Sjdp@node Formats, Relocations, Archives, BFD front end 25733965Sjdp@include format.texi 25833965Sjdp 25933965Sjdp@node Relocations, Core Files, Formats, BFD front end 26033965Sjdp@include reloc.texi 26133965Sjdp 26233965Sjdp@node Core Files, Targets, Relocations, BFD front end 26333965Sjdp@include core.texi 26433965Sjdp 26533965Sjdp@node Targets, Architectures, Core Files, BFD front end 26633965Sjdp@include targets.texi 26733965Sjdp 26833965Sjdp@node Architectures, Opening and Closing, Targets, BFD front end 26933965Sjdp@include archures.texi 27033965Sjdp 27133965Sjdp@node Opening and Closing, Internal, Architectures, BFD front end 27233965Sjdp@include opncls.texi 27333965Sjdp 27433965Sjdp@node Internal, File Caching, Opening and Closing, BFD front end 27533965Sjdp@include libbfd.texi 27633965Sjdp 27733965Sjdp@node File Caching, Linker Functions, Internal, BFD front end 27833965Sjdp@include cache.texi 27933965Sjdp 28033965Sjdp@node Linker Functions, Hash Tables, File Caching, BFD front end 28133965Sjdp@include linker.texi 28233965Sjdp 28333965Sjdp@node Hash Tables, , Linker Functions, BFD front end 28433965Sjdp@include hash.texi 28533965Sjdp 28677298Sobrien@node BFD back ends, GNU Free Documentation License, BFD front end, Top 28733965Sjdp@chapter BFD back ends 28833965Sjdp@menu 28933965Sjdp* What to Put Where:: 29033965Sjdp* aout :: a.out backends 29133965Sjdp* coff :: coff backends 29233965Sjdp* elf :: elf backends 29389857Sobrien* mmo :: mmo backend 29433965Sjdp@ignore 29533965Sjdp* oasys :: oasys backends 29633965Sjdp* ieee :: ieee backend 29733965Sjdp* srecord :: s-record backend 29833965Sjdp@end ignore 29933965Sjdp@end menu 30033965Sjdp@node What to Put Where, aout, BFD back ends, BFD back ends 301218822Sdim@section What to Put Where 30233965SjdpAll of BFD lives in one directory. 30333965Sjdp 30433965Sjdp@node aout, coff, What to Put Where, BFD back ends 30533965Sjdp@include aoutx.texi 30633965Sjdp 30733965Sjdp@node coff, elf, aout, BFD back ends 30833965Sjdp@include coffcode.texi 30933965Sjdp 31089857Sobrien@node elf, mmo, coff, BFD back ends 31133965Sjdp@include elf.texi 31233965Sjdp@c Leave this out until the file has some actual contents... 31333965Sjdp@c @include elfcode.texi 31433965Sjdp 31589857Sobrien@node mmo, , elf, BFD back ends 31689857Sobrien@include mmo.texi 31789857Sobrien 318218822Sdim@node GNU Free Documentation License, BFD Index, BFD back ends, Top 319130561Sobrien@include fdl.texi 32077298Sobrien 321218822Sdim@node BFD Index, , GNU Free Documentation License, Top 322218822Sdim@unnumbered BFD Index 32333965Sjdp@printindex cp 32433965Sjdp 32533965Sjdp@tex 32633965Sjdp% I think something like @colophon should be in texinfo. In the 32733965Sjdp% meantime: 32833965Sjdp\long\def\colophon{\hbox to0pt{}\vfill 32933965Sjdp\centerline{The body of this manual is set in} 33033965Sjdp\centerline{\fontname\tenrm,} 33133965Sjdp\centerline{with headings in {\bf\fontname\tenbf}} 33233965Sjdp\centerline{and examples in {\tt\fontname\tentt}.} 33333965Sjdp\centerline{{\it\fontname\tenit\/} and} 33433965Sjdp\centerline{{\sl\fontname\tensl\/}} 33533965Sjdp\centerline{are used for emphasis.}\vfill} 33633965Sjdp\page\colophon 33733965Sjdp% Blame: doc@cygnus.com, 28mar91. 33833965Sjdp@end tex 33933965Sjdp 34033965Sjdp@bye 341