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: (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 ends::               BFD back ends
 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 ends, Overview, Top
 215 @chapter BFD front end
 216 @include bfdt.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 * Internal::
 231 * File Caching::
 232 * Linker Functions::
 233 * Hash Tables::
 234 @end menu
 235
 236 @node Memory Usage, Initialization, BFD front end, BFD front end
 237 @section Memory usage
 238 BFD keeps all of its internal structures in obstacks. There is one obstack
 239 per open BFD file, into which the current state is stored. When a BFD is
 240 closed, the obstack is deleted, and so everything which has been
 241 allocated by BFD for the closing file is thrown away.
 242
 243 BFD does not free anything created by an application, but pointers into
 244 @code{bfd} structures become invalid on a @code{bfd_close}; for example,
 245 after a @code{bfd_close} the vector passed to
 246 @code{bfd_canonicalize_symtab} is still around, since it has been
 247 allocated by the application, but the data that it pointed to are
 248 lost.
 249
 250 The general rule is to not close a BFD until all operations dependent
 251 upon data from the BFD have been completed, or all the data from within
 252 the file has been copied. To help with the management of memory, there
 253 is a function (@code{bfd_alloc_size}) which returns the number of bytes
 254 in obstacks associated with the supplied BFD. This could be used to
 255 select the greediest open BFD, close it to reclaim the memory, perform
 256 some operation and reopen the BFD again, to get a fresh copy of the data
 257 structures.
 258
 259 @node Initialization, Sections, Memory Usage, BFD front end
 260 @include  init.texi
 261
 262 @node Sections, Symbols, Initialization, BFD front end
 263 @include  section.texi
 264
 265 @node Symbols, Archives, Sections, BFD front end
 266 @include  syms.texi
 267
 268 @node Archives, Formats, Symbols, BFD front end
 269 @include  archive.texi
 270
 271 @node Formats, Relocations, Archives, BFD front end
 272 @include  format.texi
 273
 274 @node Relocations, Core Files, Formats, BFD front end
 275 @include  reloc.texi
 276
 277 @node Core Files, Targets, Relocations, BFD front end
 278 @include  core.texi
 279
 280 @node Targets, Architectures, Core Files, BFD front end
 281 @include  targets.texi
 282
 283 @node Architectures, Opening and Closing, Targets, BFD front end
 284 @include  archures.texi
 285
 286 @node Opening and Closing, Internal, Architectures, BFD front end
 287 @include  opncls.texi
 288
 289 @node Internal, File Caching, Opening and Closing, BFD front end
 290 @include  libbfd.texi
 291
 292 @node File Caching, Linker Functions, Internal, BFD front end
 293 @include  cache.texi
 294
 295 @node Linker Functions, Hash Tables, File Caching, BFD front end
 296 @include  linker.texi
 297
 298 @node Hash Tables, , Linker Functions, BFD front end
 299 @include  hash.texi
 300
 301 @node BFD back ends, Index, BFD front end, Top
 302 @chapter BFD back ends
 303 @menu
 304 * What to Put Where::
 305 * aout ::       a.out backends
 306 * coff ::       coff backends
 307 * elf  ::       elf backends
 308 @ignore
 309 * oasys ::      oasys backends
 310 * ieee ::       ieee backend
 311 * srecord ::    s-record backend
 312 @end ignore
 313 @end menu
 314 @node What to Put Where, aout, BFD back ends, BFD back ends
 315 All of BFD lives in one directory.
 316
 317 @node aout, coff, What to Put Where, BFD back ends
 318 @include  aoutx.texi
 319
 320 @node coff, elf, aout, BFD back ends
 321 @include  coffcode.texi
 322
 323 @node elf,  , coff, BFD back ends
 324 @include  elf.texi
 325 @c Leave this out until the file has some actual contents...
 326 @c @include  elfcode.texi
 327
 328 @node Index,  , BFD back ends , Top
 329 @unnumbered Index
 330 @printindex cp
 331
 332 @tex
 333 % I think something like @colophon should be in texinfo.  In the
 334 % meantime:
 335 \long\def\colophon{\hbox to0pt{}\vfill
 336 \centerline{The body of this manual is set in}
 337 \centerline{\fontname\tenrm,}
 338 \centerline{with headings in {\bf\fontname\tenbf}}
 339 \centerline{and examples in {\tt\fontname\tentt}.}
 340 \centerline{{\it\fontname\tenit\/} and}
 341 \centerline{{\sl\fontname\tensl\/}}
 342 \centerline{are used for emphasis.}\vfill}
 343 \page\colophon
 344 % Blame: doc@cygnus.com, 28mar91.
 345 @end tex
 346
 347 @contents
 348 @bye