Commit | Line | Data |
---|---|---|
252b5132 RH |
1 | \input texinfo.tex |
2 | @setfilename bfd.info | |
9553c638 | 3 | @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000, |
7ca01ed9 | 4 | @c 2001, 2002, 2003, 2006, 2007, 2008, 2009, 2013 |
7898deda NC |
5 | @c Free Software Foundation, Inc. |
6 | @c | |
252b5132 RH |
7 | @synindex fn cp |
8 | ||
9160ea82 AM |
9 | @ifnottex |
10 | @dircategory Software development | |
11 | @direntry | |
252b5132 | 12 | * Bfd: (bfd). The Binary File Descriptor library. |
9160ea82 AM |
13 | @end direntry |
14 | @end ifnottex | |
252b5132 | 15 | |
0e9517a9 | 16 | @copying |
252b5132 RH |
17 | This file documents the BFD library. |
18 | ||
7ca01ed9 NC |
19 | Copyright @copyright{} 1991, 2000, 2001, 2003, 2006, 2007, 2008, 2013 |
20 | Free Software Foundation, Inc. | |
252b5132 | 21 | |
0e9517a9 | 22 | Permission is granted to copy, distribute and/or modify this document |
793c5807 | 23 | under the terms of the GNU Free Documentation License, Version 1.3 or |
0e9517a9 NC |
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''. | |
252b5132 | 29 | |
0e9517a9 | 30 | (a) The FSF's Front-Cover Text is: |
252b5132 | 31 | |
0e9517a9 NC |
32 | A GNU Manual |
33 | ||
34 | (b) The FSF's Back-Cover Text is: | |
35 | ||
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. | |
39 | @end copying | |
252b5132 RH |
40 | @iftex |
41 | @c@finalout | |
42 | @setchapternewpage on | |
43 | @c@setchapternewpage odd | |
44 | @settitle LIB BFD, the Binary File Descriptor Library | |
45 | @titlepage | |
46 | @title{libbfd} | |
47 | @subtitle{The Binary File Descriptor Library} | |
48 | @sp 1 | |
b45619c0 | 49 | @subtitle First Edition---BFD version < 3.0 % Since no product is stable before version 3.0 :-) |
07d8a891 | 50 | @subtitle Original Document Created: April 1991 |
252b5132 RH |
51 | @author {Steve Chamberlain} |
52 | @author {Cygnus Support} | |
53 | @page | |
54 | ||
55 | @tex | |
56 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
27c5d6c9 | 57 | \xdef\manvers{1.5} % For use in headers, footers too |
252b5132 | 58 | {\parskip=0pt |
07d8a891 NC |
59 | \hfill Free Software Foundation\par |
60 | \hfill sac\@www.gnu.org\par | |
252b5132 RH |
61 | \hfill {\it BFD}, \manvers\par |
62 | \hfill \TeX{}info \texinfoversion\par | |
63 | } | |
64 | \global\parindent=0pt % Steve likes it this way | |
65 | @end tex | |
66 | ||
67 | @vskip 0pt plus 1filll | |
7ca01ed9 NC |
68 | Copyright @copyright{} 1991, 2001, 2003, 2006, 2008, 2013 |
69 | Free Software Foundation, Inc. | |
252b5132 | 70 | |
4a8e467a | 71 | Permission is granted to copy, distribute and/or modify this document |
793c5807 | 72 | under the terms of the GNU Free Documentation License, Version 1.3 |
4a8e467a NC |
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 | |
53954f5e | 76 | section entitled ``GNU Free Documentation License''. |
252b5132 | 77 | |
252b5132 RH |
78 | @end titlepage |
79 | @end iftex | |
4ecceb71 | 80 | @contents |
252b5132 RH |
81 | |
82 | @node Top, Overview, (dir), (dir) | |
83 | @ifinfo | |
84 | This file documents the binary file descriptor library libbfd. | |
85 | @end ifinfo | |
86 | ||
87 | @menu | |
88 | * Overview:: Overview of BFD | |
89 | * BFD front end:: BFD front end | |
90 | * BFD back ends:: BFD back ends | |
4a8e467a | 91 | * GNU Free Documentation License:: GNU Free Documentation License |
370b66a1 | 92 | * BFD Index:: BFD Index |
252b5132 RH |
93 | @end menu |
94 | ||
95 | @node Overview, BFD front end, Top, Top | |
96 | @chapter Introduction | |
97 | @cindex BFD | |
98 | @cindex what is it? | |
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. | |
103 | ||
104 | BFD is split into two parts: the front end, and the back ends (one for | |
105 | each object file format). | |
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 | |
115 | @menu | |
116 | * History:: History | |
117 | * How It Works:: How It Works | |
118 | * What BFD Version 2 Can Do:: What BFD Version 2 Can Do | |
119 | @end menu | |
120 | ||
121 | @node History, How It Works, Overview, Overview | |
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 | 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 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}). | |
141 | ||
142 | ||
143 | ||
144 | @node How It Works, What BFD Version 2 Can Do, History, Overview | |
145 | @section How To Use BFD | |
146 | ||
147 | To use the library, include @file{bfd.h} and link with @file{libbfd.a}. | |
148 | ||
149 | BFD provides a common interface to the parts of an object file | |
150 | for a calling application. | |
151 | ||
b45619c0 | 152 | When an application successfully opens a target file (object, archive, or |
252b5132 RH |
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. | |
160 | ||
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 | |
163 | @code{abfd}. | |
164 | ||
53954f5e | 165 | @example |
252b5132 RH |
166 | @c @cartouche |
167 | #include "bfd.h" | |
168 | ||
53954f5e | 169 | unsigned int number_of_sections (abfd) |
252b5132 RH |
170 | bfd *abfd; |
171 | @{ | |
53954f5e | 172 | return bfd_count_sections (abfd); |
252b5132 RH |
173 | @} |
174 | @c @end cartouche | |
53954f5e | 175 | @end example |
252b5132 RH |
176 | |
177 | The abstraction used within BFD is that an object file has: | |
178 | ||
179 | @itemize @bullet | |
180 | @item | |
181 | a header, | |
182 | @item | |
183 | a number of sections containing raw data (@pxref{Sections}), | |
184 | @item | |
185 | a set of relocations (@pxref{Relocations}), and | |
186 | @item | |
187 | some symbol information (@pxref{Symbols}). | |
188 | @end itemize | |
189 | @noindent | |
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 | |
193 | IEEE-695. | |
194 | ||
195 | @node What BFD Version 2 Can Do, , How It Works, Overview | |
196 | @section What BFD Version 2 Can Do | |
197 | @include bfdsumm.texi | |
198 | ||
199 | @node BFD front end, BFD back ends, Overview, Top | |
53954f5e | 200 | @chapter BFD Front End |
252b5132 | 201 | @include bfdt.texi |
93509525 | 202 | @include bfdio.texi |
252b5132 RH |
203 | |
204 | @menu | |
205 | * Memory Usage:: | |
206 | * Initialization:: | |
207 | * Sections:: | |
208 | * Symbols:: | |
209 | * Archives:: | |
210 | * Formats:: | |
211 | * Relocations:: | |
212 | * Core Files:: | |
213 | * Targets:: | |
214 | * Architectures:: | |
215 | * Opening and Closing:: | |
216 | * Internal:: | |
217 | * File Caching:: | |
218 | * Linker Functions:: | |
219 | * Hash Tables:: | |
220 | @end menu | |
221 | ||
222 | @node Memory Usage, Initialization, BFD front end, BFD front end | |
53954f5e | 223 | @section Memory Usage |
252b5132 RH |
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. | |
228 | ||
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 | |
234 | lost. | |
235 | ||
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 | |
243 | structures. | |
244 | ||
245 | @node Initialization, Sections, Memory Usage, BFD front end | |
246 | @include init.texi | |
247 | ||
248 | @node Sections, Symbols, Initialization, BFD front end | |
249 | @include section.texi | |
250 | ||
251 | @node Symbols, Archives, Sections, BFD front end | |
252 | @include syms.texi | |
253 | ||
254 | @node Archives, Formats, Symbols, BFD front end | |
255 | @include archive.texi | |
256 | ||
257 | @node Formats, Relocations, Archives, BFD front end | |
258 | @include format.texi | |
259 | ||
260 | @node Relocations, Core Files, Formats, BFD front end | |
261 | @include reloc.texi | |
262 | ||
263 | @node Core Files, Targets, Relocations, BFD front end | |
264 | @include core.texi | |
265 | ||
266 | @node Targets, Architectures, Core Files, BFD front end | |
267 | @include targets.texi | |
268 | ||
269 | @node Architectures, Opening and Closing, Targets, BFD front end | |
270 | @include archures.texi | |
271 | ||
272 | @node Opening and Closing, Internal, Architectures, BFD front end | |
273 | @include opncls.texi | |
274 | ||
275 | @node Internal, File Caching, Opening and Closing, BFD front end | |
276 | @include libbfd.texi | |
277 | ||
278 | @node File Caching, Linker Functions, Internal, BFD front end | |
279 | @include cache.texi | |
280 | ||
281 | @node Linker Functions, Hash Tables, File Caching, BFD front end | |
282 | @include linker.texi | |
283 | ||
284 | @node Hash Tables, , Linker Functions, BFD front end | |
285 | @include hash.texi | |
286 | ||
4a8e467a | 287 | @node BFD back ends, GNU Free Documentation License, BFD front end, Top |
252b5132 RH |
288 | @chapter BFD back ends |
289 | @menu | |
290 | * What to Put Where:: | |
291 | * aout :: a.out backends | |
292 | * coff :: coff backends | |
293 | * elf :: elf backends | |
3c3bdf30 | 294 | * mmo :: mmo backend |
252b5132 RH |
295 | @ignore |
296 | * oasys :: oasys backends | |
297 | * ieee :: ieee backend | |
298 | * srecord :: s-record backend | |
299 | @end ignore | |
300 | @end menu | |
301 | @node What to Put Where, aout, BFD back ends, BFD back ends | |
9cd73268 | 302 | @section What to Put Where |
252b5132 RH |
303 | All of BFD lives in one directory. |
304 | ||
305 | @node aout, coff, What to Put Where, BFD back ends | |
306 | @include aoutx.texi | |
307 | ||
308 | @node coff, elf, aout, BFD back ends | |
309 | @include coffcode.texi | |
310 | ||
3c3bdf30 | 311 | @node elf, mmo, coff, BFD back ends |
252b5132 RH |
312 | @include elf.texi |
313 | @c Leave this out until the file has some actual contents... | |
314 | @c @include elfcode.texi | |
315 | ||
3c3bdf30 NC |
316 | @node mmo, , elf, BFD back ends |
317 | @include mmo.texi | |
318 | ||
370b66a1 | 319 | @node GNU Free Documentation License, BFD Index, BFD back ends, Top |
53954f5e NC |
320 | @include fdl.texi |
321 | ||
370b66a1 CD |
322 | @node BFD Index, , GNU Free Documentation License, Top |
323 | @unnumbered BFD Index | |
252b5132 RH |
324 | @printindex cp |
325 | ||
326 | @tex | |
7ca01ed9 | 327 | % I think something like @@colophon should be in texinfo. In the |
252b5132 RH |
328 | % meantime: |
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} | |
337 | \page\colophon | |
7ca01ed9 | 338 | % Blame: doc@@cygnus.com, 28mar91. |
252b5132 RH |
339 | @end tex |
340 | ||
252b5132 | 341 | @bye |