[thirdparty/binutils-gdb.git] / bfd / doc / bfd.texi

\input texinfo.tex
@setfilename bfd.info
@c Copyright (C) 1988-2023 Free Software Foundation, Inc.
@c 
@synindex fn cp

@ifnottex
@dircategory Software development
@direntry
* Bfd: (bfd).                   The Binary File Descriptor library.
@end direntry
@end ifnottex

@copying
This file documents the BFD library.

Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end copying
@iftex
@c@finalout
@setchapternewpage on
@c@setchapternewpage odd
@settitle LIB BFD, the Binary File Descriptor Library
@titlepage
@title{libbfd}
@subtitle{The Binary File Descriptor Library}
@sp 1
@subtitle First Edition---BFD version < 3.0  % Since no product is stable before version 3.0 :-)
@subtitle Original Document Created: April 1991
@author {Steve Chamberlain}
@author {Cygnus Support}
@page

@tex
\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
\xdef\manvers{1.5}  % For use in headers, footers too
{\parskip=0pt
\hfill Free Software Foundation\par
\hfill sac\@www.gnu.org\par
\hfill {\it BFD}, \manvers\par
\hfill \TeX{}info \texinfoversion\par
}
\global\parindent=0pt % Steve likes it this way
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.

      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.3
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, with no Front-Cover Texts, and with no
      Back-Cover Texts.  A copy of the license is included in the
      section entitled ``GNU Free Documentation License''.

@end titlepage
@end iftex
@contents

@node Top
@ifinfo
This file documents the binary file descriptor library libbfd.
@end ifinfo

@menu
* Overview::                    Overview of BFD
* BFD front end::               BFD front end
* BFD back ends::               BFD back ends
* GNU Free Documentation License::  GNU Free Documentation License
* BFD Index::           BFD Index
@end menu

@node Overview
@chapter Introduction
@cindex BFD
@cindex what is it?
BFD is a package which allows applications to use the
same routines to operate on object files whatever the object file
format.  A new object file format can be supported simply by
creating a new BFD back end and adding it to the library.

BFD is split into two parts: the front end, and the back ends (one for
each object file format).
@itemize @bullet
@item The front end of BFD provides the interface to the user. It manages
memory and various canonical data structures. The front end also
decides which back end to use and when to call back end routines.
@item The back ends provide BFD its view of the real world. Each back
end provides a set of calls which the BFD front end can use to maintain
its canonical form. The back ends also may keep around information for
their own use, for greater efficiency.
@end itemize
@menu
* History::                     History
* How It Works::                How It Works
* What BFD Version 2 Can Do::   What BFD Version 2 Can Do
@end menu

@node History
@section History

One spur behind BFD was the desire, on the part of the GNU 960 team at
Intel Oregon, for interoperability of applications on their COFF and
b.out file formats.  Cygnus was providing GNU support for the team, and
was contracted to provide the required functionality.

The name came from a conversation David Wallace was having with Richard
Stallman about the library: RMS said that it would be quite hard---David
said ``BFD''.  Stallman was right, but the name stuck.

At the same time, Ready Systems wanted much the same thing, but for
different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
coff.

BFD was first implemented by members of Cygnus Support; Steve
Chamberlain (@code{sac@@cygnus.com}), John Gilmore
(@code{gnu@@cygnus.com}), K.  Richard Pixley (@code{rich@@cygnus.com})
and David Henkel-Wallace (@code{gumby@@cygnus.com}).



@node How It Works
@section How To Use BFD

To use the library, include @file{bfd.h} and link with @file{libbfd.a}. 

BFD provides a common interface to the parts of an object file
for a calling application. 

When an application successfully opens a target file (object, archive, or
whatever), a pointer to an internal structure is returned. This pointer
points to a structure called @code{bfd}, described in
@file{bfd.h}.  Our convention is to call this pointer a BFD, and
instances of it within code @code{abfd}.  All operations on
the target object file are applied as methods to the BFD.  The mapping is
defined within @code{bfd.h} in a set of macros, all beginning
with @samp{bfd_} to reduce namespace pollution.

For example, this sequence does what you would probably expect:
return the number of sections in an object file attached to a BFD
@code{abfd}. 

@example
@c @cartouche
#include "bfd.h"

unsigned int number_of_sections (abfd)
bfd *abfd;
@{
  return bfd_count_sections (abfd);
@}
@c @end cartouche
@end example

The abstraction used within BFD is that an object file has:

@itemize @bullet
@item
a header,
@item
a number of sections containing raw data (@pxref{Sections}),
@item
a set of relocations (@pxref{Relocations}), and
@item
some symbol information (@pxref{Symbols}).
@end itemize
@noindent
Also, BFDs opened for archives have the additional attribute of an index
and contain subordinate BFDs. This approach is fine for a.out and coff,
but loses efficiency when applied to formats such as S-records and
IEEE-695.

@node What BFD Version 2 Can Do
@section What BFD Version 2 Can Do
@include bfdsumm.texi

@node BFD front end
@chapter BFD Front End

@menu
* typedef bfd::
* Error reporting::
* Initialization::
* Miscellaneous::
* Memory Usage::
* Sections::
* Symbols::
* Archives::
* Formats::
* Relocations::
* Core Files::
* Targets::
* Architectures::
* Opening and Closing::
* Internal::
* File Caching::
* Linker Functions::
* Hash Tables::
@end menu

@include bfdt.texi
@include bfdio.texi

@node Memory Usage
@section Memory Usage
BFD keeps all of its internal structures in obstacks. There is one obstack
per open BFD file, into which the current state is stored. When a BFD is
closed, the obstack is deleted, and so everything which has been
allocated by BFD for the closing file is thrown away.

BFD does not free anything created by an application, but pointers into
@code{bfd} structures become invalid on a @code{bfd_close}; for example,
after a @code{bfd_close} the vector passed to
@code{bfd_canonicalize_symtab} is still around, since it has been
allocated by the application, but the data that it pointed to are
lost.

The general rule is to not close a BFD until all operations dependent
upon data from the BFD have been completed, or all the data from within
the file has been copied. To help with the management of memory, there
is a function (@code{bfd_alloc_size}) which returns the number of bytes
in obstacks associated with the supplied BFD. This could be used to
select the greediest open BFD, close it to reclaim the memory, perform
some operation and reopen the BFD again, to get a fresh copy of the data
structures.

@node Sections
@include  section.texi

@node Symbols
@include  syms.texi

@node Archives
@include  archive.texi

@node Formats
@include  format.texi

@node Relocations
@include  reloc.texi

@node Core Files
@include  corefile.texi

@node Targets
@include  targets.texi

@node Architectures
@include  archures.texi

@node Opening and Closing
@include  opncls.texi

@node Internal
@include  libbfd.texi

@node File Caching
@include  cache.texi

@node Linker Functions
@include  linker.texi

@node Hash Tables
@include  hash.texi

@node BFD back ends
@chapter BFD back ends
@menu
* What to Put Where::
* aout ::       a.out backends
* coff ::       coff backends
* elf  ::       elf backends
* mmo  ::       mmo backend
@ignore
* srecord ::    s-record backend
@end ignore
@end menu
@node What to Put Where
@section What to Put Where
All of BFD lives in one directory.

@node aout
@include  aoutx.texi

@node coff
@include  coffcode.texi

@node elf
@include  elf.texi
@c Leave this out until the file has some actual contents...
@c @include  elfcode.texi

@node mmo
@include  mmo.texi

@node GNU Free Documentation License
@include fdl.texi

@node BFD Index
@unnumbered BFD Index
@printindex cp

@tex
% I think something like @@colophon should be in texinfo.  In the
% meantime:
\long\def\colophon{\hbox to0pt{}\vfill
\centerline{The body of this manual is set in}
\centerline{\fontname\tenrm,}
\centerline{with headings in {\bf\fontname\tenbf}}
\centerline{and examples in {\tt\fontname\tentt}.}
\centerline{{\it\fontname\tenit\/} and}
\centerline{{\sl\fontname\tensl\/}}
\centerline{are used for emphasis.}\vfill}
\page\colophon
% Blame: doc@@cygnus.com, 28mar91.
@end tex

@bye