3 @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000,
4 @c 2001, 2002, 2003, 2006, 2007, 2008, 2009, 2013
5 @c Free Software Foundation, Inc.
10 @dircategory Software development
12 * Bfd: (bfd). The Binary File Descriptor library.
17 This file documents the BFD library.
19 Copyright @copyright{} 1991, 2000, 2001, 2003, 2006, 2007, 2008, 2013
20 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.3 or
24 any later version published by the Free Software Foundation; with the
25 Invariant Sections being ``GNU General Public License'' and ``Funding
26 Free Software'', the Front-Cover texts being (a) (see below), and with
27 the Back-Cover Texts being (b) (see below). A copy of the license is
28 included in the section entitled ``GNU Free Documentation License''.
30 (a) The FSF's Front-Cover Text is:
34 (b) The FSF's Back-Cover Text is:
36 You have freedom to copy and modify this GNU Manual, like GNU
37 software. Copies published by the Free Software Foundation raise
38 funds for GNU development.
43 @c@setchapternewpage odd
44 @settitle LIB BFD, the Binary File Descriptor Library
47 @subtitle{The Binary File Descriptor Library}
49 @subtitle First Edition---BFD version < 3.0 % Since no product is stable before version 3.0 :-)
50 @subtitle Original Document Created: April 1991
51 @author {Steve Chamberlain}
52 @author {Cygnus Support}
56 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
57 \xdef\manvers{1.5} % For use in headers, footers too
59 \hfill Free Software Foundation\par
60 \hfill sac\@www.gnu.org\par
61 \hfill {\it BFD}, \manvers\par
62 \hfill \TeX{}info \texinfoversion\par
64 \global\parindent=0pt % Steve likes it this way
67 @vskip 0pt plus 1filll
68 Copyright @copyright{} 1991, 2001, 2003, 2006, 2008, 2013
69 Free Software Foundation, Inc.
71 Permission is granted to copy, distribute and/or modify this document
72 under the terms of the GNU Free Documentation License, Version 1.3
73 or any later version published by the Free Software Foundation;
74 with no Invariant Sections, with no Front-Cover Texts, and with no
75 Back-Cover Texts. A copy of the license is included in the
76 section entitled ``GNU Free Documentation License''.
82 @node Top, Overview, (dir), (dir)
84 This file documents the binary file descriptor library libbfd.
88 * Overview:: Overview of BFD
89 * BFD front end:: BFD front end
90 * BFD back ends:: BFD back ends
91 * GNU Free Documentation License:: GNU Free Documentation License
92 * BFD Index:: BFD Index
95 @node Overview, BFD front end, Top, Top
99 BFD is a package which allows applications to use the
100 same routines to operate on object files whatever the object file
101 format. A new object file format can be supported simply by
102 creating a new BFD back end and adding it to the library.
104 BFD is split into two parts: the front end, and the back ends (one for
105 each object file format).
107 @item The front end of BFD provides the interface to the user. It manages
108 memory and various canonical data structures. The front end also
109 decides which back end to use and when to call back end routines.
110 @item The back ends provide BFD its view of the real world. Each back
111 end provides a set of calls which the BFD front end can use to maintain
112 its canonical form. The back ends also may keep around information for
113 their own use, for greater efficiency.
117 * How It Works:: How It Works
118 * What BFD Version 2 Can Do:: What BFD Version 2 Can Do
121 @node History, How It Works, Overview, Overview
124 One spur behind BFD was the desire, on the part of the GNU 960 team at
125 Intel Oregon, for interoperability of applications on their COFF and
126 b.out file formats. Cygnus was providing GNU support for the team, and
127 was contracted to provide the required functionality.
129 The name came from a conversation David Wallace was having with Richard
130 Stallman about the library: RMS said that it would be quite hard---David
131 said ``BFD''. Stallman was right, but the name stuck.
133 At the same time, Ready Systems wanted much the same thing, but for
134 different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
137 BFD was first implemented by members of Cygnus Support; Steve
138 Chamberlain (@code{sac@@cygnus.com}), John Gilmore
139 (@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com})
140 and David Henkel-Wallace (@code{gumby@@cygnus.com}).
144 @node How It Works, What BFD Version 2 Can Do, History, Overview
145 @section How To Use BFD
147 To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
149 BFD provides a common interface to the parts of an object file
150 for a calling application.
152 When an application successfully opens a target file (object, archive, or
153 whatever), a pointer to an internal structure is returned. This pointer
154 points to a structure called @code{bfd}, described in
155 @file{bfd.h}. Our convention is to call this pointer a BFD, and
156 instances of it within code @code{abfd}. All operations on
157 the target object file are applied as methods to the BFD. The mapping is
158 defined within @code{bfd.h} in a set of macros, all beginning
159 with @samp{bfd_} to reduce namespace pollution.
161 For example, this sequence does what you would probably expect:
162 return the number of sections in an object file attached to a BFD
169 unsigned int number_of_sections (abfd)
172 return bfd_count_sections (abfd);
177 The abstraction used within BFD is that an object file has:
183 a number of sections containing raw data (@pxref{Sections}),
185 a set of relocations (@pxref{Relocations}), and
187 some symbol information (@pxref{Symbols}).
190 Also, BFDs opened for archives have the additional attribute of an index
191 and contain subordinate BFDs. This approach is fine for a.out and coff,
192 but loses efficiency when applied to formats such as S-records and
195 @node What BFD Version 2 Can Do, , How It Works, Overview
196 @section What BFD Version 2 Can Do
197 @include bfdsumm.texi
199 @node BFD front end, BFD back ends, Overview, Top
200 @chapter BFD Front End
215 * Opening and Closing::
222 @node Memory Usage, Initialization, BFD front end, BFD front end
223 @section Memory Usage
224 BFD keeps all of its internal structures in obstacks. There is one obstack
225 per open BFD file, into which the current state is stored. When a BFD is
226 closed, the obstack is deleted, and so everything which has been
227 allocated by BFD for the closing file is thrown away.
229 BFD does not free anything created by an application, but pointers into
230 @code{bfd} structures become invalid on a @code{bfd_close}; for example,
231 after a @code{bfd_close} the vector passed to
232 @code{bfd_canonicalize_symtab} is still around, since it has been
233 allocated by the application, but the data that it pointed to are
236 The general rule is to not close a BFD until all operations dependent
237 upon data from the BFD have been completed, or all the data from within
238 the file has been copied. To help with the management of memory, there
239 is a function (@code{bfd_alloc_size}) which returns the number of bytes
240 in obstacks associated with the supplied BFD. This could be used to
241 select the greediest open BFD, close it to reclaim the memory, perform
242 some operation and reopen the BFD again, to get a fresh copy of the data
245 @node Initialization, Sections, Memory Usage, BFD front end
248 @node Sections, Symbols, Initialization, BFD front end
249 @include section.texi
251 @node Symbols, Archives, Sections, BFD front end
254 @node Archives, Formats, Symbols, BFD front end
255 @include archive.texi
257 @node Formats, Relocations, Archives, BFD front end
260 @node Relocations, Core Files, Formats, BFD front end
263 @node Core Files, Targets, Relocations, BFD front end
266 @node Targets, Architectures, Core Files, BFD front end
267 @include targets.texi
269 @node Architectures, Opening and Closing, Targets, BFD front end
270 @include archures.texi
272 @node Opening and Closing, Internal, Architectures, BFD front end
275 @node Internal, File Caching, Opening and Closing, BFD front end
278 @node File Caching, Linker Functions, Internal, BFD front end
281 @node Linker Functions, Hash Tables, File Caching, BFD front end
284 @node Hash Tables, , Linker Functions, BFD front end
287 @node BFD back ends, GNU Free Documentation License, BFD front end, Top
288 @chapter BFD back ends
290 * What to Put Where::
291 * aout :: a.out backends
292 * coff :: coff backends
293 * elf :: elf backends
296 * oasys :: oasys backends
297 * ieee :: ieee backend
298 * srecord :: s-record backend
301 @node What to Put Where, aout, BFD back ends, BFD back ends
302 @section What to Put Where
303 All of BFD lives in one directory.
305 @node aout, coff, What to Put Where, BFD back ends
308 @node coff, elf, aout, BFD back ends
309 @include coffcode.texi
311 @node elf, mmo, coff, BFD back ends
313 @c Leave this out until the file has some actual contents...
314 @c @include elfcode.texi
316 @node mmo, , elf, BFD back ends
319 @node GNU Free Documentation License, BFD Index, BFD back ends, Top
322 @node BFD Index, , GNU Free Documentation License, Top
323 @unnumbered BFD Index
327 % I think something like @@colophon should be in texinfo. In the
329 \long\def\colophon{\hbox to0pt{}\vfill
330 \centerline{The body of this manual is set in}
331 \centerline{\fontname\tenrm,}
332 \centerline{with headings in {\bf\fontname\tenbf}}
333 \centerline{and examples in {\tt\fontname\tentt}.}
334 \centerline{{\it\fontname\tenit\/} and}
335 \centerline{{\sl\fontname\tensl\/}}
336 \centerline{are used for emphasis.}\vfill}
338 % Blame: doc@@cygnus.com, 28mar91.