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