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