contrib/binutils/bfd/doc/bfd.texinfo

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