1\input texinfo.tex 2@setfilename bfd.info 3@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000, 4@c 2001, 2002, 2003, 2006, 2007 5@c Free Software Foundation, Inc. 6@c 7@synindex fn cp 8 9@ifinfo 10@format 11START-INFO-DIR-ENTRY 12* Bfd: (bfd). The Binary File Descriptor library. 13END-INFO-DIR-ENTRY 14@end format 15@end ifinfo 16 17@copying 18This file documents the BFD library. 19 20Copyright @copyright{} 1991, 2000, 2001, 2003, 2006, 2007 Free Software Foundation, Inc. 21 22Permission is granted to copy, distribute and/or modify this document 23under the terms of the GNU Free Documentation License, Version 1.1 or 24any later version published by the Free Software Foundation; with the 25Invariant Sections being ``GNU General Public License'' and ``Funding 26Free Software'', the Front-Cover texts being (a) (see below), and with 27the Back-Cover Texts being (b) (see below). A copy of the license is 28included in the section entitled ``GNU Free Documentation License''. 29 30(a) The FSF's Front-Cover Text is: 31 32 A GNU Manual 33 34(b) The FSF's Back-Cover Text is: 35 36 You have freedom to copy and modify this GNU Manual, like GNU 37 software. Copies published by the Free Software Foundation raise 38 funds for GNU development. 39@end copying 40@iftex 41@c@finalout 42@setchapternewpage on 43@c@setchapternewpage odd 44@settitle LIB BFD, the Binary File Descriptor Library 45@titlepage 46@title{libbfd} 47@subtitle{The Binary File Descriptor Library} 48@sp 1 49@subtitle First Edition---BFD version < 3.0 % Since no product is stable before version 3.0 :-) 50@subtitle Original Document Created: April 1991 51@author {Steve Chamberlain} 52@author {Cygnus Support} 53@page 54 55@tex 56\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ 57\xdef\manvers{1.5} % For use in headers, footers too 58{\parskip=0pt 59\hfill Free Software Foundation\par 60\hfill sac\@www.gnu.org\par 61\hfill {\it BFD}, \manvers\par 62\hfill \TeX{}info \texinfoversion\par 63} 64\global\parindent=0pt % Steve likes it this way 65@end tex 66 67@vskip 0pt plus 1filll 68Copyright @copyright{} 1991, 2001, 2003, 2006 Free Software Foundation, Inc. 69 70 Permission is granted to copy, distribute and/or modify this document 71 under the terms of the GNU Free Documentation License, Version 1.1 72 or any later version published by the Free Software Foundation; 73 with no Invariant Sections, with no Front-Cover Texts, and with no 74 Back-Cover Texts. A copy of the license is included in the 75 section entitled ``GNU Free Documentation License''. 76 77@end titlepage 78@end iftex 79@contents 80 81@node Top, Overview, (dir), (dir) 82@ifinfo 83This file documents the binary file descriptor library libbfd. 84@end ifinfo 85 86@menu 87* Overview:: Overview of BFD 88* BFD front end:: BFD front end 89* BFD back ends:: BFD back ends 90* GNU Free Documentation License:: GNU Free Documentation License 91* BFD Index:: BFD Index 92@end menu 93 94@node Overview, BFD front end, Top, Top 95@chapter Introduction 96@cindex BFD 97@cindex what is it? 98BFD is a package which allows applications to use the 99same routines to operate on object files whatever the object file 100format. A new object file format can be supported simply by 101creating a new BFD back end and adding it to the library. 102 103BFD is split into two parts: the front end, and the back ends (one for 104each object file format). 105@itemize @bullet 106@item The front end of BFD provides the interface to the user. It manages 107memory and various canonical data structures. The front end also 108decides which back end to use and when to call back end routines. 109@item The back ends provide BFD its view of the real world. Each back 110end provides a set of calls which the BFD front end can use to maintain 111its canonical form. The back ends also may keep around information for 112their own use, for greater efficiency. 113@end itemize 114@menu 115* History:: History 116* How It Works:: How It Works 117* What BFD Version 2 Can Do:: What BFD Version 2 Can Do 118@end menu 119 120@node History, How It Works, Overview, Overview 121@section History 122 123One spur behind BFD was the desire, on the part of the GNU 960 team at 124Intel Oregon, for interoperability of applications on their COFF and 125b.out file formats. Cygnus was providing GNU support for the team, and 126was contracted to provide the required functionality. 127 128The name came from a conversation David Wallace was having with Richard 129Stallman about the library: RMS said that it would be quite hard---David 130said ``BFD''. Stallman was right, but the name stuck. 131 132At the same time, Ready Systems wanted much the same thing, but for 133different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k 134coff. 135 136BFD was first implemented by members of Cygnus Support; Steve 137Chamberlain (@code{sac@@cygnus.com}), John Gilmore 138(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) 139and David Henkel-Wallace (@code{gumby@@cygnus.com}). 140 141 142 143@node How It Works, What BFD Version 2 Can Do, History, Overview 144@section How To Use BFD 145 146To use the library, include @file{bfd.h} and link with @file{libbfd.a}. 147 148BFD provides a common interface to the parts of an object file 149for a calling application. 150 151When an application successfully opens a target file (object, archive, or 152whatever), a pointer to an internal structure is returned. This pointer 153points to a structure called @code{bfd}, described in 154@file{bfd.h}. Our convention is to call this pointer a BFD, and 155instances of it within code @code{abfd}. All operations on 156the target object file are applied as methods to the BFD. The mapping is 157defined within @code{bfd.h} in a set of macros, all beginning 158with @samp{bfd_} to reduce namespace pollution. 159 160For example, this sequence does what you would probably expect: 161return the number of sections in an object file attached to a BFD 162@code{abfd}. 163 164@example 165@c @cartouche 166#include "bfd.h" 167 168unsigned int number_of_sections (abfd) 169bfd *abfd; 170@{ 171 return bfd_count_sections (abfd); 172@} 173@c @end cartouche 174@end example 175 176The abstraction used within BFD is that an object file has: 177 178@itemize @bullet 179@item 180a header, 181@item 182a number of sections containing raw data (@pxref{Sections}), 183@item 184a set of relocations (@pxref{Relocations}), and 185@item 186some symbol information (@pxref{Symbols}). 187@end itemize 188@noindent 189Also, BFDs opened for archives have the additional attribute of an index 190and contain subordinate BFDs. This approach is fine for a.out and coff, 191but loses efficiency when applied to formats such as S-records and 192IEEE-695. 193 194@node What BFD Version 2 Can Do, , How It Works, Overview 195@section What BFD Version 2 Can Do 196@include bfdsumm.texi 197 198@node BFD front end, BFD back ends, Overview, Top 199@chapter BFD Front End 200@include bfdt.texi 201@include bfdio.texi 202 203@menu 204* Memory Usage:: 205* Initialization:: 206* Sections:: 207* Symbols:: 208* Archives:: 209* Formats:: 210* Relocations:: 211* Core Files:: 212* Targets:: 213* Architectures:: 214* Opening and Closing:: 215* Internal:: 216* File Caching:: 217* Linker Functions:: 218* Hash Tables:: 219@end menu 220 221@node Memory Usage, Initialization, BFD front end, BFD front end 222@section Memory Usage 223BFD keeps all of its internal structures in obstacks. There is one obstack 224per open BFD file, into which the current state is stored. When a BFD is 225closed, the obstack is deleted, and so everything which has been 226allocated by BFD for the closing file is thrown away. 227 228BFD does not free anything created by an application, but pointers into 229@code{bfd} structures become invalid on a @code{bfd_close}; for example, 230after a @code{bfd_close} the vector passed to 231@code{bfd_canonicalize_symtab} is still around, since it has been 232allocated by the application, but the data that it pointed to are 233lost. 234 235The general rule is to not close a BFD until all operations dependent 236upon data from the BFD have been completed, or all the data from within 237the file has been copied. To help with the management of memory, there 238is a function (@code{bfd_alloc_size}) which returns the number of bytes 239in obstacks associated with the supplied BFD. This could be used to 240select the greediest open BFD, close it to reclaim the memory, perform 241some operation and reopen the BFD again, to get a fresh copy of the data 242structures. 243 244@node Initialization, Sections, Memory Usage, BFD front end 245@include init.texi 246 247@node Sections, Symbols, Initialization, BFD front end 248@include section.texi 249 250@node Symbols, Archives, Sections, BFD front end 251@include syms.texi 252 253@node Archives, Formats, Symbols, BFD front end 254@include archive.texi 255 256@node Formats, Relocations, Archives, BFD front end 257@include format.texi 258 259@node Relocations, Core Files, Formats, BFD front end 260@include reloc.texi 261 262@node Core Files, Targets, Relocations, BFD front end 263@include core.texi 264 265@node Targets, Architectures, Core Files, BFD front end 266@include targets.texi 267 268@node Architectures, Opening and Closing, Targets, BFD front end 269@include archures.texi 270 271@node Opening and Closing, Internal, Architectures, BFD front end 272@include opncls.texi 273 274@node Internal, File Caching, Opening and Closing, BFD front end 275@include libbfd.texi 276 277@node File Caching, Linker Functions, Internal, BFD front end 278@include cache.texi 279 280@node Linker Functions, Hash Tables, File Caching, BFD front end 281@include linker.texi 282 283@node Hash Tables, , Linker Functions, BFD front end 284@include hash.texi 285 286@node BFD back ends, GNU Free Documentation License, BFD front end, Top 287@chapter BFD back ends 288@menu 289* What to Put Where:: 290* aout :: a.out backends 291* coff :: coff backends 292* elf :: elf backends 293* mmo :: mmo backend 294@ignore 295* oasys :: oasys backends 296* ieee :: ieee backend 297* srecord :: s-record backend 298@end ignore 299@end menu 300@node What to Put Where, aout, BFD back ends, BFD back ends 301@section What to Put Where 302All of BFD lives in one directory. 303 304@node aout, coff, What to Put Where, BFD back ends 305@include aoutx.texi 306 307@node coff, elf, aout, BFD back ends 308@include coffcode.texi 309 310@node elf, mmo, coff, BFD back ends 311@include elf.texi 312@c Leave this out until the file has some actual contents... 313@c @include elfcode.texi 314 315@node mmo, , elf, BFD back ends 316@include mmo.texi 317 318@node GNU Free Documentation License, BFD Index, BFD back ends, Top 319@include fdl.texi 320 321@node BFD Index, , GNU Free Documentation License, Top 322@unnumbered BFD Index 323@printindex cp 324 325@tex 326% I think something like @colophon should be in texinfo. In the 327% meantime: 328\long\def\colophon{\hbox to0pt{}\vfill 329\centerline{The body of this manual is set in} 330\centerline{\fontname\tenrm,} 331\centerline{with headings in {\bf\fontname\tenbf}} 332\centerline{and examples in {\tt\fontname\tentt}.} 333\centerline{{\it\fontname\tenit\/} and} 334\centerline{{\sl\fontname\tensl\/}} 335\centerline{are used for emphasis.}\vfill} 336\page\colophon 337% Blame: doc@cygnus.com, 28mar91. 338@end tex 339 340@bye 341