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