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, 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