Commit | Line | Data |
---|---|---|
20a9ac22 | 1 | \input texinfo.tex |
a9773c89 | 2 | @setfilename bfd.info |
80d29884 | 3 | @c $Id$ |
20a9ac22 DM |
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 | |
a9773c89 | 18 | @synindex fn cp |
3377d4d2 JG |
19 | |
20 | @ifinfo | |
21 | @format | |
22 | START-INFO-DIR-ENTRY | |
e5c5fbca | 23 | * Bfd:: The Binary File Descriptor library. |
3377d4d2 JG |
24 | END-INFO-DIR-ENTRY |
25 | @end format | |
26 | @end ifinfo | |
27 | ||
80d29884 SC |
28 | @ifinfo |
29 | This file documents the BFD library. | |
30 | ||
31 | Copyright (C) 1991 Free Software Foundation, Inc. | |
32 | ||
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. | |
36 | ||
37 | @ignore | |
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). | |
42 | ||
43 | @end ignore | |
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. | |
49 | ||
50 | Permission is granted to copy and distribute translations of this manual | |
51 | into 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 | |
20a9ac22 | 62 | @subtitle First Edition---BFD version < 3.0 |
80d29884 SC |
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$} % For use in headers, footers too | |
71 | {\parskip=0pt | |
72 | \hfill Cygnus Support\par | |
20a9ac22 | 73 | \hfill sac\@cygnus.com\par |
80d29884 SC |
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 | |
81 | Copyright @copyright{} 1991 Free Software Foundation, Inc. | |
82 | ||
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. | |
86 | ||
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. | |
92 | ||
93 | Permission is granted to copy and distribute translations of this manual | |
94 | into another language, under the above conditions for modified versions. | |
95 | @end titlepage | |
96 | @end iftex | |
97 | ||
98 | @node Top, Overview, (dir), (dir) | |
99 | @ifinfo | |
100 | This file documents the binary file descriptor library libbfd. | |
101 | @end ifinfo | |
102 | ||
103 | @menu | |
104 | * Overview:: Overview of BFD | |
a9773c89 RP |
105 | * BFD front end:: BFD front end |
106 | * BFD back end:: BFD back end | |
80d29884 | 107 | * Index:: Index |
80d29884 SC |
108 | @end menu |
109 | ||
a9773c89 | 110 | @node Overview, BFD front end, Top, Top |
80d29884 SC |
111 | @chapter Introduction |
112 | @cindex BFD | |
113 | @cindex what is it? | |
20a9ac22 | 114 | BFD is a package which allows applications to use the |
80d29884 | 115 | same routines to operate on object files whatever the object file |
20a9ac22 | 116 | format. A new object file format can be supported simply by |
80d29884 SC |
117 | creating a new BFD back end and adding it to the library. |
118 | ||
20a9ac22 DM |
119 | BFD is split into two parts: the front end, and the back ends (one for |
120 | each object file format). | |
80d29884 SC |
121 | @itemize @bullet |
122 | @item The front end of BFD provides the interface to the user. It manages | |
20a9ac22 DM |
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. | |
80d29884 SC |
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. | |
129 | @end itemize | |
a9773c89 RP |
130 | @menu |
131 | * History:: History | |
132 | * How It Works:: How It Works | |
20a9ac22 | 133 | * What BFD Version 2 Can Do:: What BFD Version 2 Can Do |
a9773c89 RP |
134 | @end menu |
135 | ||
136 | @node History, How It Works, Overview, Overview | |
80d29884 SC |
137 | @section History |
138 | ||
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 | |
20a9ac22 | 142 | was contracted to provide the required functionality. |
80d29884 SC |
143 | |
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. | |
147 | ||
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 | |
150 | coff. | |
151 | ||
20a9ac22 | 152 | BFD was first implemented by members of Cygnus Support; Steve |
e5c5fbca KR |
153 | Chamberlain (@code{sac@@cygnus.com}), John Gilmore |
154 | (@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) | |
155 | and David Henkel-Wallace (@code{gumby@@cygnus.com}). | |
20a9ac22 DM |
156 | |
157 | ||
80d29884 | 158 | |
20a9ac22 DM |
159 | @node How It Works, What BFD Version 2 Can Do, History, Overview |
160 | @section How To Use BFD | |
80d29884 | 161 | |
20a9ac22 | 162 | To use the library, include @file{bfd.h} and link with @file{libbfd.a}. |
80d29884 SC |
163 | |
164 | BFD provides a common interface to the parts of an object file | |
165 | for a calling application. | |
166 | ||
20a9ac22 | 167 | When an application sucessfully opens a target file (object, archive, or |
e5c5fbca | 168 | whatever), a pointer to an internal structure is returned. This pointer |
80d29884 | 169 | points to a structure called @code{bfd}, described in |
e5c5fbca | 170 | @file{bfd.h}. Our convention is to call this pointer a BFD, and |
80d29884 SC |
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 | |
20a9ac22 | 174 | with @samp{bfd_} to reduce namespace pollution. |
80d29884 | 175 | |
20a9ac22 | 176 | For example, this sequence does what you would probably expect: |
80d29884 SC |
177 | return the number of sections in an object file attached to a BFD |
178 | @code{abfd}. | |
179 | ||
180 | @lisp | |
a9773c89 | 181 | @c @cartouche |
80d29884 SC |
182 | #include "bfd.h" |
183 | ||
184 | unsigned int number_of_sections(abfd) | |
185 | bfd *abfd; | |
186 | @{ | |
187 | return bfd_count_sections(abfd); | |
188 | @} | |
a9773c89 | 189 | @c @end cartouche |
80d29884 SC |
190 | @end lisp |
191 | ||
e5c5fbca KR |
192 | The abstraction used within BFD is that an object file has: |
193 | ||
194 | @itemize @bullet | |
195 | @item | |
196 | a header, | |
197 | @item | |
198 | a number of sections containing raw data (@pxref{Sections}), | |
199 | @item | |
200 | a set of relocations (@pxref{Relocations}), and | |
201 | @item | |
202 | some symbol information (@pxref{Symbols}). | |
203 | @end itemize | |
204 | @noindent | |
205 | Also, BFDs opened for archives have the additional attribute of an index | |
206 | and contain subordinate BFDs. This approach is fine for a.out and coff, | |
207 | but loses efficiency when applied to formats such as S-records and | |
208 | IEEE-695. | |
80d29884 | 209 | |
20a9ac22 DM |
210 | @node What BFD Version 2 Can Do, , How It Works, Overview |
211 | @section What BFD Version 2 Can Do | |
e5c5fbca | 212 | @include bfdsumm.texi |
a9773c89 RP |
213 | |
214 | @node BFD front end, BFD back end, Overview, Top | |
80d29884 | 215 | @chapter BFD front end |
e5c5fbca | 216 | @include bfd.texi |
80d29884 | 217 | |
a9773c89 RP |
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 | * Constructors:: | |
231 | * Internal:: | |
232 | * File Caching:: | |
233 | @end menu | |
234 | ||
235 | @node Memory Usage, Initialization, BFD front end, BFD front end | |
80d29884 SC |
236 | @section Memory Usage |
237 | BFD keeps all its internal structures in obstacks. There is one obstack | |
238 | per open BFD file, into which the current state is stored. When a BFD is | |
239 | closed, the obstack is deleted, and so everything which has been | |
20a9ac22 | 240 | allocated by @code{libbfd} for the closing file will be thrown away. |
80d29884 SC |
241 | |
242 | BFD will not free anything created by an application, but pointers into | |
243 | @code{bfd} structures will be invalidated on a @code{bfd_close}; for example, | |
244 | after a @code{bfd_close} the vector passed to | |
245 | @code{bfd_canonicalize_symtab} will still be around, since it has been | |
246 | allocated by the application, but the data that it pointed to will be | |
247 | lost. | |
248 | ||
249 | The general rule is not to close a BFD until all operations dependent | |
250 | upon data from the BFD have been completed, or all the data from within | |
20a9ac22 DM |
251 | the file has been copied. To help with the management of memory, there |
252 | is a function (@code{bfd_alloc_size}) which returns the number of bytes | |
253 | in obstacks associated with the supplied BFD. This could be used to | |
254 | select the greediest open BFD, close it to reclaim the memory, perform | |
255 | some operation and reopen the BFD again, to get a fresh copy of the data | |
256 | structures. | |
80d29884 | 257 | |
a9773c89 RP |
258 | @node Initialization, Sections, Memory Usage, BFD front end |
259 | @include init.texi | |
260 | ||
261 | @node Sections, Symbols, Initialization, BFD front end | |
80d29884 SC |
262 | @include section.texi |
263 | ||
a9773c89 | 264 | @node Symbols, Archives, Sections, BFD front end |
80d29884 SC |
265 | @include syms.texi |
266 | ||
a9773c89 | 267 | @node Archives, Formats, Symbols, BFD front end |
80d29884 SC |
268 | @include archive.texi |
269 | ||
a9773c89 | 270 | @node Formats, Relocations, Archives, BFD front end |
80d29884 SC |
271 | @include format.texi |
272 | ||
a9773c89 | 273 | @node Relocations, Core Files, Formats, BFD front end |
80d29884 SC |
274 | @include reloc.texi |
275 | ||
a9773c89 | 276 | @node Core Files, Targets, Relocations, BFD front end |
80d29884 SC |
277 | @include core.texi |
278 | ||
a9773c89 | 279 | @node Targets, Architectures, Core Files, BFD front end |
80d29884 SC |
280 | @include targets.texi |
281 | ||
a9773c89 | 282 | @node Architectures, Opening and Closing, Targets, BFD front end |
80d29884 SC |
283 | @include archures.texi |
284 | ||
a9773c89 | 285 | @node Opening and Closing, Constructors, Architectures, BFD front end |
80d29884 SC |
286 | @include opncls.texi |
287 | ||
a9773c89 RP |
288 | @node Constructors, Internal, Opening and Closing, BFD front end |
289 | @include ctor.texi | |
290 | ||
291 | @node Internal, File Caching, Constructors, BFD front end | |
80d29884 SC |
292 | @include libbfd.texi |
293 | ||
a9773c89 | 294 | @node File Caching, , Internal, BFD front end |
80d29884 SC |
295 | @include cache.texi |
296 | ||
a9773c89 | 297 | @node BFD back end, Index, BFD front end, Top |
80d29884 | 298 | @chapter BFD back end |
80d29884 | 299 | @menu |
20a9ac22 | 300 | * What to Put Where:: |
a9773c89 RP |
301 | * aout :: a.out backends |
302 | * coff :: coff backends | |
e5c5fbca | 303 | * elf :: elf backends |
a9773c89 RP |
304 | @ignore |
305 | * oasys :: oasys backends | |
306 | * ieee :: ieee backend | |
307 | * srecord :: s-record backend | |
308 | @end ignore | |
80d29884 | 309 | @end menu |
a9773c89 | 310 | @node What to Put Where, aout, BFD back end, BFD back end |
80d29884 SC |
311 | All of BFD lives in one directory. |
312 | ||
a9773c89 | 313 | @node aout, coff, What to Put Where, BFD back end |
80d29884 SC |
314 | @include aoutx.texi |
315 | ||
e5c5fbca | 316 | @node coff, elf, aout, BFD back end |
80d29884 SC |
317 | @include coffcode.texi |
318 | ||
e5c5fbca KR |
319 | @node elf, , coff, BFD back end |
320 | @include elf.texi | |
321 | @include elfcode.texi | |
322 | ||
a9773c89 | 323 | @node Index, , BFD back end, Top |
80d29884 SC |
324 | @unnumbered Index |
325 | @printindex cp | |
326 | ||
327 | @tex | |
328 | % I think something like @colophon should be in texinfo. In the | |
329 | % meantime: | |
330 | \long\def\colophon{\hbox to0pt{}\vfill | |
331 | \centerline{The body of this manual is set in} | |
332 | \centerline{\fontname\tenrm,} | |
333 | \centerline{with headings in {\bf\fontname\tenbf}} | |
334 | \centerline{and examples in {\tt\fontname\tentt}.} | |
335 | \centerline{{\it\fontname\tenit\/} and} | |
336 | \centerline{{\sl\fontname\tensl\/}} | |
337 | \centerline{are used for emphasis.}\vfill} | |
338 | \page\colophon | |
339 | % Blame: pesch@cygnus.com, 28mar91. | |
340 | @end tex | |
341 | ||
80d29884 SC |
342 | @contents |
343 | @bye |