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