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