bfd/doc/bfd.texinfo

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