bfd.texi revision 1.1.1.1
1\input texinfo.tex 2@setfilename bfd.info 3@c Copyright (C) 1988-2018 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-2018 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-2018 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* Miscellaneous:: 202* Memory Usage:: 203* Initialization:: 204* Sections:: 205* Symbols:: 206* Archives:: 207* Formats:: 208* Relocations:: 209* Core Files:: 210* Targets:: 211* Architectures:: 212* Opening and Closing:: 213* Internal:: 214* File Caching:: 215* Linker Functions:: 216* Hash Tables:: 217@end menu 218 219@include bfdt.texi 220@include bfdio.texi 221 222@node Memory Usage, Initialization, Miscellaneous, BFD front end 223@section Memory Usage 224BFD keeps all of its internal structures in obstacks. There is one obstack 225per open BFD file, into which the current state is stored. When a BFD is 226closed, the obstack is deleted, and so everything which has been 227allocated by BFD for the closing file is thrown away. 228 229BFD does not free anything created by an application, but pointers into 230@code{bfd} structures become invalid on a @code{bfd_close}; for example, 231after a @code{bfd_close} the vector passed to 232@code{bfd_canonicalize_symtab} is still around, since it has been 233allocated by the application, but the data that it pointed to are 234lost. 235 236The general rule is to not close a BFD until all operations dependent 237upon data from the BFD have been completed, or all the data from within 238the file has been copied. To help with the management of memory, there 239is a function (@code{bfd_alloc_size}) which returns the number of bytes 240in obstacks associated with the supplied BFD. This could be used to 241select the greediest open BFD, close it to reclaim the memory, perform 242some operation and reopen the BFD again, to get a fresh copy of the data 243structures. 244 245@node Initialization, Sections, Memory Usage, BFD front end 246@include init.texi 247 248@node Sections, Symbols, Initialization, BFD front end 249@include section.texi 250 251@node Symbols, Archives, Sections, BFD front end 252@include syms.texi 253 254@node Archives, Formats, Symbols, BFD front end 255@include archive.texi 256 257@node Formats, Relocations, Archives, BFD front end 258@include format.texi 259 260@node Relocations, Core Files, Formats, BFD front end 261@include reloc.texi 262 263@node Core Files, Targets, Relocations, BFD front end 264@include core.texi 265 266@node Targets, Architectures, Core Files, BFD front end 267@include targets.texi 268 269@node Architectures, Opening and Closing, Targets, BFD front end 270@include archures.texi 271 272@node Opening and Closing, Internal, Architectures, BFD front end 273@include opncls.texi 274 275@node Internal, File Caching, Opening and Closing, BFD front end 276@include libbfd.texi 277 278@node File Caching, Linker Functions, Internal, BFD front end 279@include cache.texi 280 281@node Linker Functions, Hash Tables, File Caching, BFD front end 282@include linker.texi 283 284@node Hash Tables, , Linker Functions, BFD front end 285@include hash.texi 286 287@node BFD back ends, GNU Free Documentation License, BFD front end, Top 288@chapter BFD back ends 289@menu 290* What to Put Where:: 291* aout :: a.out backends 292* coff :: coff backends 293* elf :: elf backends 294* mmo :: mmo backend 295@ignore 296* srecord :: s-record backend 297@end ignore 298@end menu 299@node What to Put Where, aout, BFD back ends, BFD back ends 300@section What to Put Where 301All of BFD lives in one directory. 302 303@node aout, coff, What to Put Where, BFD back ends 304@include aoutx.texi 305 306@node coff, elf, aout, BFD back ends 307@include coffcode.texi 308 309@node elf, mmo, coff, BFD back ends 310@include elf.texi 311@c Leave this out until the file has some actual contents... 312@c @include elfcode.texi 313 314@node mmo, , elf, BFD back ends 315@include mmo.texi 316 317@node GNU Free Documentation License, BFD Index, BFD back ends, Top 318@include fdl.texi 319 320@node BFD Index, , GNU Free Documentation License, Top 321@unnumbered BFD Index 322@printindex cp 323 324@tex 325% I think something like @@colophon should be in texinfo. In the 326% meantime: 327\long\def\colophon{\hbox to0pt{}\vfill 328\centerline{The body of this manual is set in} 329\centerline{\fontname\tenrm,} 330\centerline{with headings in {\bf\fontname\tenbf}} 331\centerline{and examples in {\tt\fontname\tentt}.} 332\centerline{{\it\fontname\tenit\/} and} 333\centerline{{\sl\fontname\tensl\/}} 334\centerline{are used for emphasis.}\vfill} 335\page\colophon 336% Blame: doc@@cygnus.com, 28mar91. 337@end tex 338 339@bye 340