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