bfd/doc/bfd.texinfo

   1 \input texinfo.tex
   2 @setfilename bfd.info
   3 @c $Id$
   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
  18 @synindex fn cp
  19
  20 @ifinfo
  21 @format
  22 START-INFO-DIR-ENTRY
  23 * Bfd::                         The Binary File Descriptor library.
  24 END-INFO-DIR-ENTRY
  25 @end format
  26 @end ifinfo
  27
  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
  62 @subtitle First Edition---BFD version < 3.0
  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
  73 \hfill sac\@cygnus.com\par
  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
 105 * BFD front end::               BFD front end
 106 * BFD back end::                BFD back end
 107 * Index::                       Index
 108 @end menu
 109
 110 @node Overview, BFD front end, Top, Top
 111 @chapter Introduction
 112 @cindex BFD
 113 @cindex what is it?
 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.
 118
 119 BFD is split into two parts: the front end, and the back ends (one for
 120 each object file format).
 121 @itemize @bullet
 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.
 129 @end itemize
 130 @menu
 131 * History::                     History
 132 * How It Works::                How It Works
 133 * What BFD Version 2 Can Do::   What BFD Version 2 Can Do
 134 @end menu
 135
 136 @node History, How It Works, Overview, Overview
 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
 142 was contracted to provide the required functionality.
 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
 152 BFD was first implemented by members of Cygnus Support; Steve
 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}).
 156
 157
 158
 159 @node How It Works, What BFD Version 2 Can Do, History, Overview
 160 @section How To Use BFD
 161
 162 To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
 163
 164 BFD provides a common interface to the parts of an object file
 165 for a calling application.
 166
 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{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.
 175
 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
 178 @code{abfd}.
 179
 180 @lisp
 181 @c @cartouche
 182 #include "bfd.h"
 183
 184 unsigned int number_of_sections(abfd)
 185 bfd *abfd;
 186 @{
 187   return bfd_count_sections(abfd);
 188 @}
 189 @c @end cartouche
 190 @end lisp
 191
 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.
 209
 210 @node What BFD Version 2 Can Do,  , How It Works, Overview
 211 @section What BFD Version 2 Can Do
 212 @include bfdsumm.texi
 213
 214 @node BFD front end, BFD back end, Overview, Top
 215 @chapter BFD front end
 216 @include bfd.texi
 217
 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
 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
 240 allocated by @code{libbfd} for the closing file will be thrown away.
 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
 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.
 257
 258 @node Initialization, Sections, Memory Usage, BFD front end
 259 @include  init.texi
 260
 261 @node Sections, Symbols, Initialization, BFD front end
 262 @include  section.texi
 263
 264 @node Symbols, Archives, Sections, BFD front end
 265 @include  syms.texi
 266
 267 @node Archives, Formats, Symbols, BFD front end
 268 @include  archive.texi
 269
 270 @node Formats, Relocations, Archives, BFD front end
 271 @include  format.texi
 272
 273 @node Relocations, Core Files, Formats, BFD front end
 274 @include  reloc.texi
 275
 276 @node Core Files, Targets, Relocations, BFD front end
 277 @include  core.texi
 278
 279 @node Targets, Architectures, Core Files, BFD front end
 280 @include  targets.texi
 281
 282 @node Architectures, Opening and Closing, Targets, BFD front end
 283 @include  archures.texi
 284
 285 @node Opening and Closing, Constructors, Architectures, BFD front end
 286 @include  opncls.texi
 287
 288 @node Constructors, Internal, Opening and Closing, BFD front end
 289 @include  ctor.texi
 290
 291 @node Internal, File Caching, Constructors, BFD front end
 292 @include  libbfd.texi
 293
 294 @node File Caching,  , Internal, BFD front end
 295 @include  cache.texi
 296
 297 @node BFD back end, Index, BFD front end, Top
 298 @chapter BFD back end
 299 @menu
 300 * What to Put Where::
 301 * aout ::       a.out backends
 302 * coff ::       coff backends
 303 * elf  ::       elf backends
 304 @ignore
 305 * oasys ::      oasys backends
 306 * ieee ::       ieee backend
 307 * srecord ::    s-record backend
 308 @end ignore
 309 @end menu
 310 @node What to Put Where, aout, BFD back end, BFD back end
 311 All of BFD lives in one directory.
 312
 313 @node aout, coff, What to Put Where, BFD back end
 314 @include  aoutx.texi
 315
 316 @node coff, elf, aout, BFD back end
 317 @include  coffcode.texi
 318
 319 @node elf,  , coff, BFD back end
 320 @include  elf.texi
 321 @include  elfcode.texi
 322
 323 @node Index,  , BFD back end, Top
 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
 342 @contents
 343 @bye