3 @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000,
5 @c Free Software Foundation, Inc.
12 * Bfd: (bfd). The Binary File Descriptor library.
18 This file documents the BFD library.
20 Copyright (C) 1991, 2000, 2001, 2003 Free Software Foundation, Inc.
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''.
30 Permission is granted to process this file through Tex and print the
31 results, provided the printed document carries copying permission
32 notice identical to this one except for the removal of this paragraph
33 (this paragraph not being relevant to the printed manual).
40 @c@setchapternewpage odd
41 @settitle LIB BFD, the Binary File Descriptor Library
44 @subtitle{The Binary File Descriptor Library}
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}
53 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
54 \xdef\manvers{1.5} % For use in headers, footers too
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
61 \global\parindent=0pt % Steve likes it this way
64 @vskip 0pt plus 1filll
65 Copyright @copyright{} 1991, 2001, 2003 Free Software Foundation, Inc.
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''.
77 @node Top, Overview, (dir), (dir)
79 This file documents the binary file descriptor library libbfd.
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 * BFD Index:: BFD Index
90 @node Overview, BFD front end, Top, Top
94 BFD is a package which allows applications to use the
95 same routines to operate on object files whatever the object file
96 format. A new object file format can be supported simply by
97 creating a new BFD back end and adding it to the library.
99 BFD is split into two parts: the front end, and the back ends (one for
100 each object file format).
102 @item The front end of BFD provides the interface to the user. It manages
103 memory and various canonical data structures. The front end also
104 decides 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
106 end provides a set of calls which the BFD front end can use to maintain
107 its canonical form. The back ends also may keep around information for
108 their own use, for greater efficiency.
112 * How It Works:: How It Works
113 * What BFD Version 2 Can Do:: What BFD Version 2 Can Do
116 @node History, How It Works, Overview, Overview
119 One spur behind BFD was the desire, on the part of the GNU 960 team at
120 Intel Oregon, for interoperability of applications on their COFF and
121 b.out file formats. Cygnus was providing GNU support for the team, and
122 was contracted to provide the required functionality.
124 The name came from a conversation David Wallace was having with Richard
125 Stallman about the library: RMS said that it would be quite hard---David
126 said ``BFD''. Stallman was right, but the name stuck.
128 At the same time, Ready Systems wanted much the same thing, but for
129 different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
132 BFD was first implemented by members of Cygnus Support; Steve
133 Chamberlain (@code{sac@@cygnus.com}), John Gilmore
134 (@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com})
135 and David Henkel-Wallace (@code{gumby@@cygnus.com}).
139 @node How It Works, What BFD Version 2 Can Do, History, Overview
140 @section How To Use BFD
142 To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
144 BFD provides a common interface to the parts of an object file
145 for a calling application.
147 When an application sucessfully opens a target file (object, archive, or
148 whatever), a pointer to an internal structure is returned. This pointer
149 points to a structure called @code{bfd}, described in
150 @file{bfd.h}. Our convention is to call this pointer a BFD, and
151 instances of it within code @code{abfd}. All operations on
152 the target object file are applied as methods to the BFD. The mapping is
153 defined within @code{bfd.h} in a set of macros, all beginning
154 with @samp{bfd_} to reduce namespace pollution.
156 For example, this sequence does what you would probably expect:
157 return the number of sections in an object file attached to a BFD
164 unsigned int number_of_sections (abfd)
167 return bfd_count_sections (abfd);
172 The abstraction used within BFD is that an object file has:
178 a number of sections containing raw data (@pxref{Sections}),
180 a set of relocations (@pxref{Relocations}), and
182 some symbol information (@pxref{Symbols}).
185 Also, BFDs opened for archives have the additional attribute of an index
186 and contain subordinate BFDs. This approach is fine for a.out and coff,
187 but loses efficiency when applied to formats such as S-records and
190 @node What BFD Version 2 Can Do, , How It Works, Overview
191 @section What BFD Version 2 Can Do
192 @include bfdsumm.texi
194 @node BFD front end, BFD back ends, Overview, Top
195 @chapter BFD Front End
210 * Opening and Closing::
217 @node Memory Usage, Initialization, BFD front end, BFD front end
218 @section Memory Usage
219 BFD keeps all of its internal structures in obstacks. There is one obstack
220 per open BFD file, into which the current state is stored. When a BFD is
221 closed, the obstack is deleted, and so everything which has been
222 allocated by BFD for the closing file is thrown away.
224 BFD does not free anything created by an application, but pointers into
225 @code{bfd} structures become invalid on a @code{bfd_close}; for example,
226 after a @code{bfd_close} the vector passed to
227 @code{bfd_canonicalize_symtab} is still around, since it has been
228 allocated by the application, but the data that it pointed to are
231 The general rule is to not close a BFD until all operations dependent
232 upon data from the BFD have been completed, or all the data from within
233 the file has been copied. To help with the management of memory, there
234 is a function (@code{bfd_alloc_size}) which returns the number of bytes
235 in obstacks associated with the supplied BFD. This could be used to
236 select the greediest open BFD, close it to reclaim the memory, perform
237 some operation and reopen the BFD again, to get a fresh copy of the data
240 @node Initialization, Sections, Memory Usage, BFD front end
243 @node Sections, Symbols, Initialization, BFD front end
244 @include section.texi
246 @node Symbols, Archives, Sections, BFD front end
249 @node Archives, Formats, Symbols, BFD front end
250 @include archive.texi
252 @node Formats, Relocations, Archives, BFD front end
255 @node Relocations, Core Files, Formats, BFD front end
258 @node Core Files, Targets, Relocations, BFD front end
261 @node Targets, Architectures, Core Files, BFD front end
262 @include targets.texi
264 @node Architectures, Opening and Closing, Targets, BFD front end
265 @include archures.texi
267 @node Opening and Closing, Internal, Architectures, BFD front end
270 @node Internal, File Caching, Opening and Closing, BFD front end
273 @node File Caching, Linker Functions, Internal, BFD front end
276 @node Linker Functions, Hash Tables, File Caching, BFD front end
279 @node Hash Tables, , Linker Functions, BFD front end
282 @node BFD back ends, GNU Free Documentation License, BFD front end, Top
283 @chapter BFD back ends
285 * What to Put Where::
286 * aout :: a.out backends
287 * coff :: coff backends
288 * elf :: elf backends
291 * oasys :: oasys backends
292 * ieee :: ieee backend
293 * srecord :: s-record backend
296 @node What to Put Where, aout, BFD back ends, BFD back ends
297 @section What to Put Where
298 All of BFD lives in one directory.
300 @node aout, coff, What to Put Where, BFD back ends
303 @node coff, elf, aout, BFD back ends
304 @include coffcode.texi
306 @node elf, mmo, coff, BFD back ends
308 @c Leave this out until the file has some actual contents...
309 @c @include elfcode.texi
311 @node mmo, , elf, BFD back ends
314 @node GNU Free Documentation License, BFD Index, BFD back ends, Top
317 @node BFD Index, , GNU Free Documentation License, Top
318 @unnumbered BFD Index
322 % I think something like @colophon should be in texinfo. In the
324 \long\def\colophon{\hbox to0pt{}\vfill
325 \centerline{The body of this manual is set in}
326 \centerline{\fontname\tenrm,}
327 \centerline{with headings in {\bf\fontname\tenbf}}
328 \centerline{and examples in {\tt\fontname\tentt}.}
329 \centerline{{\it\fontname\tenit\/} and}
330 \centerline{{\sl\fontname\tensl\/}}
331 \centerline{are used for emphasis.}\vfill}
333 % Blame: doc@cygnus.com, 28mar91.