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