OpenCores
URL https://opencores.org/ocsvn/open8_urisc/open8_urisc/trunk

Subversion Repositories open8_urisc

[/] [open8_urisc/] [trunk/] [gnu/] [binutils/] [bfd/] [doc/] [bfd.texinfo] - Blame information for rev 148

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 14 khays
\input texinfo.tex
2
@setfilename bfd.info
3
@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1997, 2000,
4
@c 2001, 2002, 2003, 2006, 2007, 2008, 2009
5
@c Free Software Foundation, Inc.
6
@c
7
@synindex fn cp
8
 
9
@ifnottex
10
@dircategory Software development
11
@direntry
12
* Bfd: (bfd).                   The Binary File Descriptor library.
13
@end direntry
14
@end ifnottex
15
 
16
@copying
17
This file documents the BFD library.
18
 
19
Copyright @copyright{} 1991, 2000, 2001, 2003, 2006, 2007, 2008 Free Software Foundation, Inc.
20
 
21
Permission is granted to copy, distribute and/or modify this document
22
under the terms of the GNU Free Documentation License, Version 1.3 or
23
any later version published by the Free Software Foundation; with the
24
Invariant Sections being ``GNU General Public License'' and ``Funding
25
Free Software'', the Front-Cover texts being (a) (see below), and with
26
the Back-Cover Texts being (b) (see below).  A copy of the license is
27
included in the section entitled ``GNU Free Documentation License''.
28
 
29
(a) The FSF's Front-Cover Text is:
30
 
31
     A GNU Manual
32
 
33
(b) The FSF's Back-Cover Text is:
34
 
35
     You have freedom to copy and modify this GNU Manual, like GNU
36
     software.  Copies published by the Free Software Foundation raise
37
     funds for GNU development.
38
@end copying
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 < 3.0  % Since no product is stable before version 3.0 :-)
49
@subtitle Original Document Created: 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{1.5}  % For use in headers, footers too
57
{\parskip=0pt
58
\hfill Free Software Foundation\par
59
\hfill sac\@www.gnu.org\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, 2001, 2003, 2006, 2008 Free Software Foundation, Inc.
68
 
69
      Permission is granted to copy, distribute and/or modify this document
70
      under the terms of the GNU Free Documentation License, Version 1.3
71
      or any later version published by the Free Software Foundation;
72
      with no Invariant Sections, with no Front-Cover Texts, and with no
73
      Back-Cover Texts.  A copy of the license is included in the
74
      section entitled ``GNU Free Documentation License''.
75
 
76
@end titlepage
77
@end iftex
78
@contents
79
 
80
@node Top, Overview, (dir), (dir)
81
@ifinfo
82
This file documents the binary file descriptor library libbfd.
83
@end ifinfo
84
 
85
@menu
86
* Overview::                    Overview of BFD
87
* BFD front end::               BFD front end
88
* BFD back ends::               BFD back ends
89
* GNU Free Documentation License::  GNU Free Documentation License
90
* BFD Index::           BFD Index
91
@end menu
92
 
93
@node Overview, BFD front end, Top, Top
94
@chapter Introduction
95
@cindex BFD
96
@cindex what is it?
97
BFD is a package which allows applications to use the
98
same routines to operate on object files whatever the object file
99
format.  A new object file format can be supported simply by
100
creating a new BFD back end and adding it to the library.
101
 
102
BFD is split into two parts: the front end, and the back ends (one for
103
each object file format).
104
@itemize @bullet
105
@item The front end of BFD provides the interface to the user. It manages
106
memory and various canonical data structures. The front end also
107
decides which back end to use and when to call back end routines.
108
@item The back ends provide BFD its view of the real world. Each back
109
end provides a set of calls which the BFD front end can use to maintain
110
its canonical form. The back ends also may keep around information for
111
their own use, for greater efficiency.
112
@end itemize
113
@menu
114
* History::                     History
115
* How It Works::                How It Works
116
* What BFD Version 2 Can Do::   What BFD Version 2 Can Do
117
@end menu
118
 
119
@node History, How It Works, Overview, Overview
120
@section History
121
 
122
One spur behind BFD was the desire, on the part of the GNU 960 team at
123
Intel Oregon, for interoperability of applications on their COFF and
124
b.out file formats.  Cygnus was providing GNU support for the team, and
125
was contracted to provide the required functionality.
126
 
127
The name came from a conversation David Wallace was having with Richard
128
Stallman about the library: RMS said that it would be quite hard---David
129
said ``BFD''.  Stallman was right, but the name stuck.
130
 
131
At the same time, Ready Systems wanted much the same thing, but for
132
different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
133
coff.
134
 
135
BFD was first implemented by members of Cygnus Support; Steve
136
Chamberlain (@code{sac@@cygnus.com}), John Gilmore
137
(@code{gnu@@cygnus.com}), K.  Richard Pixley (@code{rich@@cygnus.com})
138
and David Henkel-Wallace (@code{gumby@@cygnus.com}).
139
 
140
 
141
 
142
@node How It Works, What BFD Version 2 Can Do, History, Overview
143
@section How To Use BFD
144
 
145
To use the library, include @file{bfd.h} and link with @file{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 successfully 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
@file{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
with @samp{bfd_} to reduce namespace pollution.
158
 
159
For example, this sequence does what you would probably expect:
160
return the number of sections in an object file attached to a BFD
161
@code{abfd}.
162
 
163
@example
164
@c @cartouche
165
#include "bfd.h"
166
 
167
unsigned int number_of_sections (abfd)
168
bfd *abfd;
169
@{
170
  return bfd_count_sections (abfd);
171
@}
172
@c @end cartouche
173
@end example
174
 
175
The abstraction used within BFD is that an object file has:
176
 
177
@itemize @bullet
178
@item
179
a header,
180
@item
181
a number of sections containing raw data (@pxref{Sections}),
182
@item
183
a set of relocations (@pxref{Relocations}), and
184
@item
185
some symbol information (@pxref{Symbols}).
186
@end itemize
187
@noindent
188
Also, BFDs opened for archives have the additional attribute of an index
189
and contain subordinate BFDs. This approach is fine for a.out and coff,
190
but loses efficiency when applied to formats such as S-records and
191
IEEE-695.
192
 
193
@node What BFD Version 2 Can Do,  , How It Works, Overview
194
@section What BFD Version 2 Can Do
195
@include bfdsumm.texi
196
 
197
@node BFD front end, BFD back ends, Overview, Top
198
@chapter BFD Front End
199
@include bfdt.texi
200
@include bfdio.texi
201
 
202
@menu
203
* Memory Usage::
204
* Initialization::
205
* Sections::
206
* Symbols::
207
* Archives::
208
* Formats::
209
* Relocations::
210
* Core Files::
211
* Targets::
212
* Architectures::
213
* Opening and Closing::
214
* Internal::
215
* File Caching::
216
* Linker Functions::
217
* Hash Tables::
218
@end menu
219
 
220
@node Memory Usage, Initialization, BFD front end, BFD front end
221
@section Memory Usage
222
BFD keeps all of its internal structures in obstacks. There is one obstack
223
per open BFD file, into which the current state is stored. When a BFD is
224
closed, the obstack is deleted, and so everything which has been
225
allocated by BFD for the closing file is thrown away.
226
 
227
BFD does not free anything created by an application, but pointers into
228
@code{bfd} structures become invalid on a @code{bfd_close}; for example,
229
after a @code{bfd_close} the vector passed to
230
@code{bfd_canonicalize_symtab} is still around, since it has been
231
allocated by the application, but the data that it pointed to are
232
lost.
233
 
234
The general rule is to not close a BFD until all operations dependent
235
upon data from the BFD have been completed, or all the data from within
236
the file has been copied. To help with the management of memory, there
237
is a function (@code{bfd_alloc_size}) which returns the number of bytes
238
in obstacks associated with the supplied BFD. This could be used to
239
select the greediest open BFD, close it to reclaim the memory, perform
240
some operation and reopen the BFD again, to get a fresh copy of the data
241
structures.
242
 
243
@node Initialization, Sections, Memory Usage, BFD front end
244
@include  init.texi
245
 
246
@node Sections, Symbols, Initialization, BFD front end
247
@include  section.texi
248
 
249
@node Symbols, Archives, Sections, BFD front end
250
@include  syms.texi
251
 
252
@node Archives, Formats, Symbols, BFD front end
253
@include  archive.texi
254
 
255
@node Formats, Relocations, Archives, BFD front end
256
@include  format.texi
257
 
258
@node Relocations, Core Files, Formats, BFD front end
259
@include  reloc.texi
260
 
261
@node Core Files, Targets, Relocations, BFD front end
262
@include  core.texi
263
 
264
@node Targets, Architectures, Core Files, BFD front end
265
@include  targets.texi
266
 
267
@node Architectures, Opening and Closing, Targets, BFD front end
268
@include  archures.texi
269
 
270
@node Opening and Closing, Internal, Architectures, BFD front end
271
@include  opncls.texi
272
 
273
@node Internal, File Caching, Opening and Closing, BFD front end
274
@include  libbfd.texi
275
 
276
@node File Caching, Linker Functions, Internal, BFD front end
277
@include  cache.texi
278
 
279
@node Linker Functions, Hash Tables, File Caching, BFD front end
280
@include  linker.texi
281
 
282
@node Hash Tables, , Linker Functions, BFD front end
283
@include  hash.texi
284
 
285
@node BFD back ends, GNU Free Documentation License, BFD front end, Top
286
@chapter BFD back ends
287
@menu
288
* What to Put Where::
289
* aout ::       a.out backends
290
* coff ::       coff backends
291
* elf  ::       elf backends
292
* mmo  ::       mmo backend
293
@ignore
294
* oasys ::      oasys backends
295
* ieee ::       ieee backend
296
* srecord ::    s-record backend
297
@end ignore
298
@end menu
299
@node What to Put Where, aout, BFD back ends, BFD back ends
300
@section What to Put Where
301
All of BFD lives in one directory.
302
 
303
@node aout, coff, What to Put Where, BFD back ends
304
@include  aoutx.texi
305
 
306
@node coff, elf, aout, BFD back ends
307
@include  coffcode.texi
308
 
309
@node elf, mmo, coff, BFD back ends
310
@include  elf.texi
311
@c Leave this out until the file has some actual contents...
312
@c @include  elfcode.texi
313
 
314
@node mmo,  , elf, BFD back ends
315
@include  mmo.texi
316
 
317
@node GNU Free Documentation License, BFD Index, BFD back ends, Top
318
@include fdl.texi
319
 
320
@node BFD Index,  , GNU Free Documentation License, Top
321
@unnumbered BFD Index
322
@printindex cp
323
 
324
@tex
325
% I think something like @colophon should be in texinfo.  In the
326
% meantime:
327
\long\def\colophon{\hbox to0pt{}\vfill
328
\centerline{The body of this manual is set in}
329
\centerline{\fontname\tenrm,}
330
\centerline{with headings in {\bf\fontname\tenbf}}
331
\centerline{and examples in {\tt\fontname\tentt}.}
332
\centerline{{\it\fontname\tenit\/} and}
333
\centerline{{\sl\fontname\tensl\/}}
334
\centerline{are used for emphasis.}\vfill}
335
\page\colophon
336
% Blame: doc@cygnus.com, 28mar91.
337
@end tex
338
 
339
@bye

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.