5 % NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE
6 \global\long\def\example{%
8 \let\aboveenvbreak=\par
9 \let\afterenvbreak=\par
12 \global\long\def\Eexample{%
15 \vskip -\parskip% to cancel out effect of following \par
23 * Bfd: (bfd). The Binary File Descriptor library.
29 This file documents the BFD library.
31 Copyright (C) 1991 Free Software Foundation, Inc.
33 Permission is granted to make and distribute verbatim copies of
34 this manual provided the copyright notice and this permission notice
35 are preserved on all copies.
38 Permission is granted to process this file through Tex and print the
39 results, provided the printed document carries copying permission
40 notice identical to this one except for the removal of this paragraph
41 (this paragraph not being relevant to the printed manual).
44 Permission is granted to copy and distribute modified versions of this
45 manual under the conditions for verbatim copying, subject to the terms
46 of the GNU General Public License, which includes the provision that the
47 entire resulting derived work is distributed under the terms of a
48 permission notice identical to this one.
50 Permission is granted to copy and distribute translations of this manual
51 into another language, under the above conditions for modified versions.
56 @c@setchapternewpage odd
57 @settitle LIB BFD, the Binary File Descriptor Library
60 @subtitle{The Binary File Descriptor Library}
62 @subtitle First Edition---BFD version < 3.0
64 @author {Steve Chamberlain}
65 @author {Cygnus Support}
69 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
70 \xdef\manvers{\$Revision$} % For use in headers, footers too
72 \hfill Cygnus Support\par
73 \hfill sac\@cygnus.com\par
74 \hfill {\it BFD}, \manvers\par
75 \hfill \TeX{}info \texinfoversion\par
77 \global\parindent=0pt % Steve likes it this way
80 @vskip 0pt plus 1filll
81 Copyright @copyright{} 1991 Free Software Foundation, Inc.
83 Permission is granted to make and distribute verbatim copies of
84 this manual provided the copyright notice and this permission notice
85 are preserved on all copies.
87 Permission is granted to copy and distribute modified versions of this
88 manual under the conditions for verbatim copying, subject to the terms
89 of the GNU General Public License, which includes the provision that the
90 entire resulting derived work is distributed under the terms of a
91 permission notice identical to this one.
93 Permission is granted to copy and distribute translations of this manual
94 into another language, under the above conditions for modified versions.
98 @node Top, Overview, (dir), (dir)
100 This file documents the binary file descriptor library libbfd.
104 * Overview:: Overview of BFD
105 * BFD front end:: BFD front end
106 * BFD back end:: BFD back end
110 @node Overview, BFD front end, Top, Top
111 @chapter Introduction
114 BFD is a package which allows applications to use the
115 same routines to operate on object files whatever the object file
116 format. A new object file format can be supported simply by
117 creating a new BFD back end and adding it to the library.
119 BFD is split into two parts: the front end, and the back ends (one for
120 each object file format).
122 @item The front end of BFD provides the interface to the user. It manages
123 memory and various canonical data structures. The front end also
124 decides 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
126 end provides a set of calls which the BFD front end can use to maintain
127 its canonical form. The back ends also may keep around information for
128 their own use, for greater efficiency.
132 * How It Works:: How It Works
133 * What BFD Version 2 Can Do:: What BFD Version 2 Can Do
136 @node History, How It Works, Overview, Overview
139 One spur behind BFD was the desire, on the part of the GNU 960 team at
140 Intel Oregon, for interoperability of applications on their COFF and
141 b.out file formats. Cygnus was providing GNU support for the team, and
142 was contracted to provide the required functionality.
144 The name came from a conversation David Wallace was having with Richard
145 Stallman about the library: RMS said that it would be quite hard---David
146 said ``BFD''. Stallman was right, but the name stuck.
148 At the same time, Ready Systems wanted much the same thing, but for
149 different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
152 BFD was first implemented by members of Cygnus Support; Steve
153 Chamberlain (@file{sac@@cygnus.com}), John Gilmore
154 (@file{gnu@@cygnus.com}), K. Richard Pixley (@file{rich@@cygnus.com})
155 and David Henkel-Wallace (@file{gumby@@cygnus.com}).
159 @node How It Works, What BFD Version 2 Can Do, History, Overview
160 @section How To Use BFD
162 To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
164 BFD provides a common interface to the parts of an object file
165 for a calling application.
167 When an application sucessfully opens a target file (object, archive, or
168 whatever) a pointer to an internal structure is returned. This pointer
169 points to a structure called @code{bfd}, described in
170 @file{include/bfd.h}. Our convention is to call this pointer a BFD, and
171 instances of it within code @code{abfd}. All operations on
172 the target object file are applied as methods to the BFD. The mapping is
173 defined within @code{bfd.h} in a set of macros, all beginning
174 with @samp{bfd_} to reduce namespace pollution.
176 For example, this sequence does what you would probably expect:
177 return the number of sections in an object file attached to a BFD
184 unsigned int number_of_sections(abfd)
187 return bfd_count_sections(abfd);
192 The abstraction used within BFD is that an object file has a header,
193 a number of sections containing raw data, a set of relocations, and some
194 symbol information. Also, BFDs opened for archives have the
195 additional attribute of an index and contain subordinate BFDs. This approach is
196 fine for a.out and coff, but loses efficiency when applied to formats
197 such as S-records and IEEE-695.
199 @node What BFD Version 2 Can Do, , How It Works, Overview
200 @section What BFD Version 2 Can Do
201 As different information from the the object files is required,
202 BFD reads from different sections of the file and processes them.
203 For example, a very common operation for the linker is processing symbol
204 tables. Each BFD back end provides a routine for converting
205 between the object file's representation of symbols and an internal
206 canonical format. When the linker asks for the symbol table of an object
207 file, it calls through the memory pointer to a routine from the
208 relevant BFD back end which reads and converts the table into a canonical
209 form. The linker then operates upon the canonical form. When the link is
210 finished and the linker writes the output file's symbol table,
211 another BFD back end routine is called to take the newly
212 created symbol table and convert it into the chosen output format.
215 * BFD information loss:: Information Loss
216 * Mechanism:: Mechanism
219 @node BFD information loss, Mechanism, What BFD Version 2 Can Do, What BFD Version 2 Can Do
220 @subsection Information Loss
221 @emph{Some information is lost due to the nature of the file format.} The output targets
222 supported by BFD do not provide identical facilities, and
223 information which can be described in one form has nowhere to go in
224 another format. One example of this is alignment information in
225 @code{b.out}. There is nowhere in an @code{a.out} format file to store
226 alignment information on the contained data, so when a file is linked
227 from @code{b.out} and an @code{a.out} image is produced, alignment
228 information will not propagate to the output file. (The linker will
229 still use the alignment information internally, so the link is performed
232 Another example is COFF section names. COFF files may contain an
233 unlimited number of sections, each one with a textual section name. If
234 the target of the link is a format which does not have many sections (e.g.,
235 @code{a.out}) or has sections without names (e.g., the Oasys format), the
236 link cannot be done simply. You can circumvent this problem by
237 describing the desired input-to-output section mapping with the linker command
240 @emph{Information can be lost during canonicalization.} The BFD
241 internal canonical form of the external formats is not exhaustive; there
242 are structures in input formats for which there is no direct
243 representation internally. This means that the BFD back ends
244 cannot maintain all possible data richness through the transformation
245 between external to internal and back to external formats.
247 This limitation is only a problem when an application reads one
248 format and writes another. Each BFD back end is responsible for
249 maintaining as much data as possible, and the internal BFD
250 canonical form has structures which are opaque to the BFD core,
251 and exported only to the back ends. When a file is read in one format,
252 the canonical form is generated for BFD and the application. At the
253 same time, the back end saves away any information which may otherwise
254 be lost. If the data is then written back in the same format, the back
255 end routine will be able to use the canonical form provided by the
256 BFD core as well as the information it prepared earlier. Since
257 there is a great deal of commonality between back ends,
258 there is no information lost when
259 linking or copying big endian COFF to little endian COFF, or @code{a.out} to
260 @code{b.out}. When a mixture of formats is linked, the information is
261 only lost from the files whose format differs from the destination.
263 @node Mechanism, , BFD information loss, What BFD Version 2 Can Do
264 @subsection Mechanism
265 The greatest potential for loss of information is when there is least
266 overlap between the information provided by the source format, that
267 stored by the canonical format, and the information needed by the
268 destination format. A brief description of the canonical form may help
269 you appreciate what kinds of data you can count on preserving across
271 @cindex BFD canonical format
272 @cindex internal object-file format
276 Information on target machine architecture, particular implementation
277 and format type are stored on a per-file basis. Other information
278 includes a demand pageable bit and a write protected bit. Note that
279 information like Unix magic numbers is not stored here---only the magic
280 numbers' meaning, so a @code{ZMAGIC} file would have both the demand
281 pageable bit and the write protected text bit set. The byte order of
282 the target is stored on a per-file basis, so that big- and little-endian
283 object files may be used with one another.
286 Each section in the input file contains the name of the section, the
287 original address in the object file, various flags, size and alignment
288 information and pointers into other BFD data structures.
291 Each symbol contains a pointer to the object file which originally
292 defined it, its name, its value, and various flag bits. When a
293 BFD back end reads in a symbol table, the back end relocates all
294 symbols to make them relative to the base of the section where they were
295 defined. This ensures that each symbol points to its containing
296 section. Each symbol also has a varying amount of hidden data to contain
297 private data for the BFD back end. Since the symbol points to the
298 original file, the private data format for that symbol is accessible.
299 @code{gld} can operate on a collection of symbols of wildly different
300 formats without problems.
302 Normal global and simple local symbols are maintained on output, so an
303 output file (no matter its format) will retain symbols pointing to
304 functions and to global, static, and common variables. Some symbol
305 information is not worth retaining; in @code{a.out} type information is
306 stored in the symbol table as long symbol names. This information would
307 be useless to most COFF debuggers; the linker has command line switches
308 to allow users to throw it away.
310 There is one word of type information within the symbol, so if the
311 format supports symbol type information within symbols (for example COFF,
312 IEEE, Oasys) and the type is simple enough to fit within one word
313 (nearly everything but aggregates) the information will be preserved.
315 @item relocation level
316 Each canonical BFD relocation record contains a pointer to the symbol to
317 relocate to (if any), the offset of the data to relocate, the section the data
318 is in and a pointer to a relocation type descriptor. Relocation is
319 performed effectively by message passing through the relocation type
320 descriptor and symbol pointer. It allows relocations to be performed
321 on output data using a relocation method only available in one of the
322 input formats. For instance, Oasys provides a byte relocation format.
323 A relocation record requesting this relocation type would point
324 indirectly to a routine to perform this, so the relocation may be
325 performed on a byte being written to a 68k COFF file, even though 68k COFF
326 has no such relocation type.
329 Object formats can contain, for debugging purposes, some form of mapping
330 between symbols, source line numbers, and addresses in the output file.
331 These addresses have to be relocated along with the symbol information.
332 Each symbol with an associated list of line number records points to the
333 first record of the list. The head of a line number list consists of a
334 pointer to the symbol, which allows divination of the address of the
335 function whose line number is being described. The rest of the list is
336 made up of pairs: offsets into the section and line numbers. Any format
337 which can simply derive this information can pass it successfully
338 between formats (COFF, IEEE and Oasys).
341 @c FIXME: what is this line about? Do we want introductory remarks
342 @c FIXME... on back ends? commented out for now.
346 @node BFD front end, BFD back end, Overview, Top
347 @chapter BFD front end
361 * Opening and Closing::
367 @node Memory Usage, Initialization, BFD front end, BFD front end
368 @section Memory Usage
369 BFD keeps all its internal structures in obstacks. There is one obstack
370 per open BFD file, into which the current state is stored. When a BFD is
371 closed, the obstack is deleted, and so everything which has been
372 allocated by @code{libbfd} for the closing file will be thrown away.
374 BFD will not free anything created by an application, but pointers into
375 @code{bfd} structures will be invalidated on a @code{bfd_close}; for example,
376 after a @code{bfd_close} the vector passed to
377 @code{bfd_canonicalize_symtab} will still be around, since it has been
378 allocated by the application, but the data that it pointed to will be
381 The general rule is not to close a BFD until all operations dependent
382 upon data from the BFD have been completed, or all the data from within
383 the file has been copied. To help with the management of memory, there
384 is a function (@code{bfd_alloc_size}) which returns the number of bytes
385 in obstacks associated with the supplied BFD. This could be used to
386 select the greediest open BFD, close it to reclaim the memory, perform
387 some operation and reopen the BFD again, to get a fresh copy of the data
390 @node Initialization, Sections, Memory Usage, BFD front end
393 @node Sections, Symbols, Initialization, BFD front end
394 @include section.texi
396 @node Symbols, Archives, Sections, BFD front end
399 @node Archives, Formats, Symbols, BFD front end
400 @include archive.texi
402 @node Formats, Relocations, Archives, BFD front end
405 @node Relocations, Core Files, Formats, BFD front end
408 @node Core Files, Targets, Relocations, BFD front end
411 @node Targets, Architectures, Core Files, BFD front end
412 @include targets.texi
414 @node Architectures, Opening and Closing, Targets, BFD front end
415 @include archures.texi
417 @node Opening and Closing, Constructors, Architectures, BFD front end
420 @node Constructors, Internal, Opening and Closing, BFD front end
423 @node Internal, File Caching, Constructors, BFD front end
426 @node File Caching, , Internal, BFD front end
429 @node BFD back end, Index, BFD front end, Top
430 @chapter BFD back end
432 * What to Put Where::
433 * aout :: a.out backends
434 * coff :: coff backends
436 * oasys :: oasys backends
437 * ieee :: ieee backend
438 * srecord :: s-record backend
441 @node What to Put Where, aout, BFD back end, BFD back end
442 All of BFD lives in one directory.
444 @node aout, coff, What to Put Where, BFD back end
447 @node coff, , aout, BFD back end
448 @include coffcode.texi
450 @node Index, , BFD back end, Top
455 % I think something like @colophon should be in texinfo. In the
457 \long\def\colophon{\hbox to0pt{}\vfill
458 \centerline{The body of this manual is set in}
459 \centerline{\fontname\tenrm,}
460 \centerline{with headings in {\bf\fontname\tenbf}}
461 \centerline{and examples in {\tt\fontname\tentt}.}
462 \centerline{{\it\fontname\tenit\/} and}
463 \centerline{{\sl\fontname\tensl\/}}
464 \centerline{are used for emphasis.}\vfill}
466 % Blame: pesch@cygnus.com, 28mar91.