Commit | Line | Data |
---|---|---|
fd8c21f9 | 1 | \input fsf-texi.tex |
a9773c89 | 2 | @setfilename bfd.info |
80d29884 | 3 | @c $Id$ |
a9773c89 | 4 | @synindex fn cp |
3377d4d2 JG |
5 | |
6 | @ifinfo | |
7 | @format | |
8 | START-INFO-DIR-ENTRY | |
9 | * Bfd: (bfd). The Binary File Descriptor library. | |
10 | END-INFO-DIR-ENTRY | |
11 | @end format | |
12 | @end ifinfo | |
13 | ||
80d29884 SC |
14 | @ifinfo |
15 | This file documents the BFD library. | |
16 | ||
17 | Copyright (C) 1991 Free Software Foundation, Inc. | |
18 | ||
19 | Permission is granted to make and distribute verbatim copies of | |
20 | this manual provided the copyright notice and this permission notice | |
21 | are preserved on all copies. | |
22 | ||
23 | @ignore | |
24 | Permission is granted to process this file through Tex and print the | |
25 | results, provided the printed document carries copying permission | |
26 | notice identical to this one except for the removal of this paragraph | |
27 | (this paragraph not being relevant to the printed manual). | |
28 | ||
29 | @end ignore | |
30 | Permission is granted to copy and distribute modified versions of this | |
31 | manual under the conditions for verbatim copying, subject to the terms | |
32 | of the GNU General Public License, which includes the provision that the | |
33 | entire resulting derived work is distributed under the terms of a | |
34 | permission notice identical to this one. | |
35 | ||
36 | Permission is granted to copy and distribute translations of this manual | |
37 | into another language, under the above conditions for modified versions. | |
38 | @end ifinfo | |
39 | @iftex | |
40 | @c@finalout | |
41 | @setchapternewpage on | |
42 | @c@setchapternewpage odd | |
43 | @settitle LIB BFD, the Binary File Descriptor Library | |
44 | @titlepage | |
45 | @title{libbfd} | |
46 | @subtitle{The Binary File Descriptor Library} | |
47 | @sp 1 | |
48 | @subtitle First Edition---BFD version < 2.0 | |
49 | @subtitle April 1991 | |
50 | @author {Steve Chamberlain} | |
51 | @author {Cygnus Support} | |
52 | @page | |
53 | ||
54 | @tex | |
55 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
56 | \xdef\manvers{\$Revision$} % For use in headers, footers too | |
57 | {\parskip=0pt | |
58 | \hfill Cygnus Support\par | |
59 | \hfill steve\@cygnus.com\par | |
60 | \hfill {\it BFD}, \manvers\par | |
61 | \hfill \TeX{}info \texinfoversion\par | |
62 | } | |
63 | \global\parindent=0pt % Steve likes it this way | |
64 | @end tex | |
65 | ||
66 | @vskip 0pt plus 1filll | |
67 | Copyright @copyright{} 1991 Free Software Foundation, Inc. | |
68 | ||
69 | Permission is granted to make and distribute verbatim copies of | |
70 | this manual provided the copyright notice and this permission notice | |
71 | are preserved on all copies. | |
72 | ||
73 | Permission is granted to copy and distribute modified versions of this | |
74 | manual under the conditions for verbatim copying, subject to the terms | |
75 | of the GNU General Public License, which includes the provision that the | |
76 | entire resulting derived work is distributed under the terms of a | |
77 | permission notice identical to this one. | |
78 | ||
79 | Permission is granted to copy and distribute translations of this manual | |
80 | into another language, under the above conditions for modified versions. | |
81 | @end titlepage | |
82 | @end iftex | |
83 | ||
84 | @node Top, Overview, (dir), (dir) | |
85 | @ifinfo | |
86 | This file documents the binary file descriptor library libbfd. | |
87 | @end ifinfo | |
88 | ||
89 | @menu | |
90 | * Overview:: Overview of BFD | |
a9773c89 RP |
91 | * BFD front end:: BFD front end |
92 | * BFD back end:: BFD back end | |
80d29884 | 93 | * Index:: Index |
80d29884 SC |
94 | @end menu |
95 | ||
a9773c89 | 96 | @node Overview, BFD front end, Top, Top |
80d29884 SC |
97 | @chapter Introduction |
98 | @cindex BFD | |
99 | @cindex what is it? | |
100 | Simply put, BFD is a package which allows applications to use the | |
101 | same routines to operate on object files whatever the object file | |
102 | format. A different object file format can be supported simply by | |
103 | creating a new BFD back end and adding it to the library. | |
104 | ||
105 | BFD is split into two parts; the front end and the many back ends. | |
106 | @itemize @bullet | |
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. | |
114 | @end itemize | |
a9773c89 RP |
115 | @menu |
116 | * History:: History | |
117 | * How It Works:: How It Works | |
118 | * What BFD Version 1 Can Do:: What BFD Version 1 Can Do | |
119 | @end menu | |
120 | ||
121 | @node History, How It Works, Overview, Overview | |
80d29884 SC |
122 | @section History |
123 | ||
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 | Cygnus was contracted to provide the required functionality. | |
128 | ||
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. | |
132 | ||
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 | |
135 | coff. | |
136 | ||
137 | BFD was first implemented by Steve Chamberlain (steve@@cygnus.com), | |
138 | John Gilmore (gnu@@cygnus.com), K. Richard Pixley (rich@@cygnus.com) and | |
139 | David Wallace (gumby@@cygnus.com) at Cygnus Support in Palo Alto, | |
140 | California. | |
141 | ||
a9773c89 | 142 | @node How It Works, What BFD Version 1 Can Do, History, Overview |
80d29884 SC |
143 | @section How It Works |
144 | ||
145 | To use the library, include @code{bfd.h} and link with @code{libbfd.a}. | |
146 | ||
147 | BFD provides a common interface to the parts of an object file | |
148 | for a calling application. | |
149 | ||
150 | When an application sucessfully opens a target file (object, archive or | |
151 | whatever) a pointer to an internal structure is returned. This pointer | |
152 | points to a structure called @code{bfd}, described in | |
153 | @code{include/bfd.h}. Our convention is to call this pointer a BFD, and | |
154 | instances of it within code @code{abfd}. All operations on | |
155 | the target object file are applied as methods to the BFD. The mapping is | |
156 | defined within @code{bfd.h} in a set of macros, all beginning | |
157 | @samp{bfd}_. | |
158 | ||
159 | For example, this sequence would do what you would probably expect: | |
160 | return the number of sections in an object file attached to a BFD | |
161 | @code{abfd}. | |
162 | ||
163 | @lisp | |
a9773c89 | 164 | @c @cartouche |
80d29884 SC |
165 | #include "bfd.h" |
166 | ||
167 | unsigned int number_of_sections(abfd) | |
168 | bfd *abfd; | |
169 | @{ | |
170 | return bfd_count_sections(abfd); | |
171 | @} | |
a9773c89 | 172 | @c @end cartouche |
80d29884 SC |
173 | @end lisp |
174 | ||
175 | The abstraction used within BFD is that an object file has a header, | |
176 | a number of sections containing raw data, a set of relocations, and some | |
177 | symbol information. Also, BFDs opened for archives have the | |
178 | additional attribute of an index and contain subordinate BFDs. This approach is | |
179 | fine for a.out and coff, but loses efficiency when applied to formats | |
180 | such as S-records and IEEE-695. | |
181 | ||
a9773c89 | 182 | @node What BFD Version 1 Can Do, , How It Works, Overview |
80d29884 SC |
183 | @section What BFD Version 1 Can Do |
184 | As different information from the the object files is required, | |
185 | BFD reads from different sections of the file and processes them. | |
186 | For example a very common operation for the linker is processing symbol | |
187 | tables. Each BFD back end provides a routine for converting | |
188 | between the object file's representation of symbols and an internal | |
189 | canonical format. When the linker asks for the symbol table of an object | |
190 | file, it calls through the memory pointer to the relevant BFD | |
191 | back end routine which reads and converts the table into a canonical | |
192 | form. The linker then operates upon the canonical form. When the link is | |
193 | finished and the linker writes the output file's symbol table, | |
194 | another BFD back end routine is called which takes the newly | |
195 | created symbol table and converts it into the chosen output format. | |
196 | ||
a9773c89 RP |
197 | @menu |
198 | * BFD information loss:: Information Loss | |
199 | * Mechanism:: Mechanism | |
200 | @end menu | |
201 | ||
202 | @node BFD information loss, Mechanism, What BFD Version 1 Can Do, What BFD Version 1 Can Do | |
80d29884 SC |
203 | @subsection Information Loss |
204 | @emph{Some information is lost due to the nature of the file format.} The output targets | |
205 | supported by BFD do not provide identical facilities, and | |
206 | information which may be described in one form has nowhere to go in | |
207 | another format. One example of this is alignment information in | |
208 | @code{b.out}. There is nowhere in an @code{a.out} format file to store | |
209 | alignment information on the contained data, so when a file is linked | |
210 | from @code{b.out} and an @code{a.out} image is produced, alignment | |
211 | information will not propagate to the output file. (The linker will | |
212 | still use the alignment information internally, so the link is performed | |
213 | correctly). | |
214 | ||
215 | Another example is COFF section names. COFF files may contain an | |
216 | unlimited number of sections, each one with a textual section name. If | |
217 | the target of the link is a format which does not have many sections (eg | |
218 | @code{a.out}) or has sections without names (eg the Oasys format) the | |
219 | link cannot be done simply. You can circumvent this problem by | |
220 | describing the desired input-to-output section mapping with the linker command | |
221 | language. | |
222 | ||
223 | @emph{Information can be lost during canonicalization.} The BFD | |
224 | internal canonical form of the external formats is not exhaustive; there | |
225 | are structures in input formats for which there is no direct | |
226 | representation internally. This means that the BFD back ends | |
227 | cannot maintain all possible data richness through the transformation | |
228 | between external to internal and back to external formats. | |
229 | ||
230 | This limitation is only a problem when an application reads one | |
231 | format and writes another. Each BFD back end is responsible for | |
232 | maintaining as much data as possible, and the internal BFD | |
233 | canonical form has structures which are opaque to the BFD core, | |
234 | and exported only to the back ends. When a file is read in one format, | |
235 | the canonical form is generated for BFD and the application. At the | |
236 | same time, the back end saves away any information which may otherwise | |
237 | be lost. If the data is then written back in the same format, the back | |
238 | end routine will be able to use the canonical form provided by the | |
239 | BFD core as well as the information it prepared earlier. Since | |
240 | there is a great deal of commonality between back ends, this mechanism | |
241 | is very useful. There is no information lost for this reason when | |
242 | linking or copying big endian COFF to little endian COFF, or @code{a.out} to | |
243 | @code{b.out}. When a mixture of formats is linked, the information is | |
244 | only lost from the files whose format differs from the destination. | |
245 | ||
a9773c89 | 246 | @node Mechanism, , BFD information loss, What BFD Version 1 Can Do |
80d29884 SC |
247 | @subsection Mechanism |
248 | The greatest potential for loss of information is when there is least | |
249 | overlap between the information provided by the source format, that | |
250 | stored by the canonical format, and the information needed by the | |
251 | destination format. A brief description of the canonical form may help | |
252 | you appreciate what kinds of data you can count on preserving across | |
253 | conversions. | |
254 | @cindex BFD canonical format | |
255 | @cindex internal object-file format | |
256 | ||
257 | @table @emph | |
258 | @item files | |
259 | Information on target machine architecture, particular implementation | |
260 | and format type are stored on a per-file basis. Other information | |
261 | includes a demand pageable bit and a write protected bit. Note that | |
262 | information like Unix magic numbers is not stored here---only the magic | |
263 | numbers' meaning, so a @code{ZMAGIC} file would have both the demand | |
264 | pageable bit and the write protected text bit set. The byte order of | |
265 | the target is stored on a per-file basis, so that big- and little-endian | |
266 | object files may be linked with one another. | |
267 | @c FIXME: generalize above from "link"? | |
268 | ||
269 | @item sections | |
270 | Each section in the input file contains the name of the section, the | |
271 | original address in the object file, various flags, size and alignment | |
272 | information and pointers into other BFD data structures. | |
273 | ||
274 | @item symbols | |
275 | Each symbol contains a pointer to the object file which originally | |
276 | defined it, its name, its value, and various flag bits. When a | |
277 | BFD back end reads in a symbol table, the back end relocates all | |
278 | symbols to make them relative to the base of the section where they were | |
279 | defined. This ensures that each symbol points to its containing | |
280 | section. Each symbol also has a varying amount of hidden data to contain | |
281 | private data for the BFD back end. Since the symbol points to the | |
282 | original file, the private data format for that symbol is accessible. | |
283 | @code{gld} can operate on a collection of symbols of wildly different | |
284 | formats without problems. | |
285 | ||
286 | Normal global and simple local symbols are maintained on output, so an | |
287 | output file (no matter its format) will retain symbols pointing to | |
288 | functions and to global, static, and common variables. Some symbol | |
289 | information is not worth retaining; in @code{a.out} type information is | |
290 | stored in the symbol table as long symbol names. This information would | |
291 | be useless to most COFF debuggers; the linker has command line switches | |
292 | to allow users to throw it away. | |
293 | ||
294 | There is one word of type information within the symbol, so if the | |
295 | format supports symbol type information within symbols (for example COFF, | |
296 | IEEE, Oasys) and the type is simple enough to fit within one word | |
297 | (nearly everything but aggregates) the information will be preserved. | |
298 | ||
299 | @item relocation level | |
300 | Each canonical BFD relocation record contains a pointer to the symbol to | |
301 | relocate to, the offset of the data to relocate, the section the data | |
302 | is in and a pointer to a relocation type descriptor. Relocation is | |
303 | performed effectively by message passing through the relocation type | |
304 | descriptor and symbol pointer. It allows relocations to be performed | |
305 | on output data using a relocation method only available in one of the | |
306 | input formats. For instance, Oasys provides a byte relocation format. | |
307 | A relocation record requesting this relocation type would point | |
308 | indirectly to a routine to perform this, so the relocation may be | |
309 | performed on a byte being written to a COFF file, even though 68k COFF | |
310 | has no such relocation type. | |
311 | ||
312 | @item line numbers | |
313 | Object formats can contain, for debugging purposes, some form of mapping | |
314 | between symbols, source line numbers, and addresses in the output file. | |
315 | These addresses have to be relocated along with the symbol information. | |
316 | Each symbol with an associated list of line number records points to the | |
317 | first record of the list. The head of a line number list consists of a | |
318 | pointer to the symbol, which allows divination of the address of the | |
319 | function whose line number is being described. The rest of the list is | |
320 | made up of pairs: offsets into the section and line numbers. Any format | |
321 | which can simply derive this information can pass it successfully | |
322 | between formats (COFF, IEEE and Oasys). | |
323 | @end table | |
324 | ||
325 | @c FIXME: what is this line about? Do we want introductory remarks | |
326 | @c FIXME... on back ends? commented out for now. | |
327 | @c What is a backend | |
a9773c89 RP |
328 | |
329 | ||
330 | @node BFD front end, BFD back end, Overview, Top | |
80d29884 SC |
331 | @chapter BFD front end |
332 | @include bfd.texi | |
333 | ||
a9773c89 RP |
334 | @menu |
335 | * Memory Usage:: | |
336 | * Initialization:: | |
337 | * Sections:: | |
338 | * Symbols:: | |
339 | * Archives:: | |
340 | * Formats:: | |
341 | * Relocations:: | |
342 | * Core Files:: | |
343 | * Targets:: | |
344 | * Architectures:: | |
345 | * Opening and Closing:: | |
346 | * Constructors:: | |
347 | * Internal:: | |
348 | * File Caching:: | |
349 | @end menu | |
350 | ||
351 | @node Memory Usage, Initialization, BFD front end, BFD front end | |
80d29884 SC |
352 | @section Memory Usage |
353 | BFD keeps all its internal structures in obstacks. There is one obstack | |
354 | per open BFD file, into which the current state is stored. When a BFD is | |
355 | closed, the obstack is deleted, and so everything which has been | |
356 | allocated by libbfd for the closing file will be thrown away. | |
357 | ||
358 | BFD will not free anything created by an application, but pointers into | |
359 | @code{bfd} structures will be invalidated on a @code{bfd_close}; for example, | |
360 | after a @code{bfd_close} the vector passed to | |
361 | @code{bfd_canonicalize_symtab} will still be around, since it has been | |
362 | allocated by the application, but the data that it pointed to will be | |
363 | lost. | |
364 | ||
365 | The general rule is not to close a BFD until all operations dependent | |
366 | upon data from the BFD have been completed, or all the data from within | |
367 | the file has been copied. To help with the management of memory, there is a function | |
368 | (@code{bfd_alloc_size}) which returns the number of bytes in obstacks | |
369 | associated with the supplied BFD. This could be used to select the | |
370 | greediest open BFD, close it to reclaim the memory, perform some | |
371 | operation and reopen the BFD again, to get a fresh copy of the data structures. | |
372 | ||
a9773c89 RP |
373 | @node Initialization, Sections, Memory Usage, BFD front end |
374 | @include init.texi | |
375 | ||
376 | @node Sections, Symbols, Initialization, BFD front end | |
80d29884 SC |
377 | @include section.texi |
378 | ||
a9773c89 | 379 | @node Symbols, Archives, Sections, BFD front end |
80d29884 SC |
380 | @include syms.texi |
381 | ||
a9773c89 | 382 | @node Archives, Formats, Symbols, BFD front end |
80d29884 SC |
383 | @include archive.texi |
384 | ||
a9773c89 | 385 | @node Formats, Relocations, Archives, BFD front end |
80d29884 SC |
386 | @include format.texi |
387 | ||
a9773c89 | 388 | @node Relocations, Core Files, Formats, BFD front end |
80d29884 SC |
389 | @include reloc.texi |
390 | ||
a9773c89 | 391 | @node Core Files, Targets, Relocations, BFD front end |
80d29884 SC |
392 | @include core.texi |
393 | ||
a9773c89 | 394 | @node Targets, Architectures, Core Files, BFD front end |
80d29884 SC |
395 | @include targets.texi |
396 | ||
a9773c89 | 397 | @node Architectures, Opening and Closing, Targets, BFD front end |
80d29884 SC |
398 | @include archures.texi |
399 | ||
a9773c89 | 400 | @node Opening and Closing, Constructors, Architectures, BFD front end |
80d29884 SC |
401 | @include opncls.texi |
402 | ||
a9773c89 RP |
403 | @node Constructors, Internal, Opening and Closing, BFD front end |
404 | @include ctor.texi | |
405 | ||
406 | @node Internal, File Caching, Constructors, BFD front end | |
80d29884 SC |
407 | @include libbfd.texi |
408 | ||
a9773c89 | 409 | @node File Caching, , Internal, BFD front end |
80d29884 SC |
410 | @include cache.texi |
411 | ||
a9773c89 | 412 | @node BFD back end, Index, BFD front end, Top |
80d29884 | 413 | @chapter BFD back end |
80d29884 | 414 | @menu |
a9773c89 RP |
415 | * What to put where:: |
416 | * aout :: a.out backends | |
417 | * coff :: coff backends | |
418 | @ignore | |
419 | * oasys :: oasys backends | |
420 | * ieee :: ieee backend | |
421 | * srecord :: s-record backend | |
422 | @end ignore | |
80d29884 | 423 | @end menu |
a9773c89 | 424 | @node What to Put Where, aout, BFD back end, BFD back end |
80d29884 SC |
425 | All of BFD lives in one directory. |
426 | ||
a9773c89 | 427 | @node aout, coff, What to Put Where, BFD back end |
80d29884 SC |
428 | @include aoutx.texi |
429 | ||
a9773c89 | 430 | @node coff, , aout, BFD back end |
80d29884 SC |
431 | @include coffcode.texi |
432 | ||
a9773c89 | 433 | @node Index, , BFD back end, Top |
80d29884 SC |
434 | @unnumbered Index |
435 | @printindex cp | |
436 | ||
437 | @tex | |
438 | % I think something like @colophon should be in texinfo. In the | |
439 | % meantime: | |
440 | \long\def\colophon{\hbox to0pt{}\vfill | |
441 | \centerline{The body of this manual is set in} | |
442 | \centerline{\fontname\tenrm,} | |
443 | \centerline{with headings in {\bf\fontname\tenbf}} | |
444 | \centerline{and examples in {\tt\fontname\tentt}.} | |
445 | \centerline{{\it\fontname\tenit\/} and} | |
446 | \centerline{{\sl\fontname\tensl\/}} | |
447 | \centerline{are used for emphasis.}\vfill} | |
448 | \page\colophon | |
449 | % Blame: pesch@cygnus.com, 28mar91. | |
450 | @end tex | |
451 | ||
80d29884 SC |
452 | @contents |
453 | @bye | |
454 | ||
455 |