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