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