diff options
Diffstat (limited to 'contrib/gdb/bfd/doc/bfd.texinfo')
| -rw-r--r-- | contrib/gdb/bfd/doc/bfd.texinfo | 348 |
1 files changed, 0 insertions, 348 deletions
diff --git a/contrib/gdb/bfd/doc/bfd.texinfo b/contrib/gdb/bfd/doc/bfd.texinfo deleted file mode 100644 index af7bc10..0000000 --- a/contrib/gdb/bfd/doc/bfd.texinfo +++ /dev/null @@ -1,348 +0,0 @@ -\input texinfo.tex -@setfilename bfd.info -@c $Id: bfd.texinfo,v 1.28 1995/11/10 20:04:12 victoria Exp $ -@tex -% NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE -\global\long\def\example{% -\begingroup -\let\aboveenvbreak=\par -\let\afterenvbreak=\par -\parskip=0pt -\lisp} -\global\long\def\Eexample{% -\Elisp -\endgroup -\vskip -\parskip% to cancel out effect of following \par -} -@end tex -@synindex fn cp - -@ifinfo -@format -START-INFO-DIR-ENTRY -* Bfd: (bfd). The Binary File Descriptor library. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@ifinfo -This file documents the BFD library. - -Copyright (C) 1991 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, subject to the terms -of the GNU General Public License, which includes the provision that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ifinfo -@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 -@subtitle April 1991 -@author {Steve Chamberlain} -@author {Cygnus Support} -@page - -@tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.28 $} % For use in headers, footers too -{\parskip=0pt -\hfill Cygnus Support\par -\hfill sac\@cygnus.com\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 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, subject to the terms -of the GNU General Public License, which includes the provision that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end titlepage -@end iftex - -@node Top, Overview, (dir), (dir) -@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 -* Index:: Index -@end menu - -@node Overview, BFD front end, Top, Top -@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, How It Works, Overview, Overview -@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, What BFD Version 2 Can Do, History, Overview -@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 sucessfully 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}. - -@lisp -@c @cartouche -#include "bfd.h" - -unsigned int number_of_sections(abfd) -bfd *abfd; -@{ - return bfd_count_sections(abfd); -@} -@c @end cartouche -@end lisp - -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, , How It Works, Overview -@section What BFD Version 2 Can Do -@include bfdsumm.texi - -@node BFD front end, BFD back ends, Overview, Top -@chapter BFD front end -@include bfd.texi - -@menu -* Memory Usage:: -* Initialization:: -* Sections:: -* Symbols:: -* Archives:: -* Formats:: -* Relocations:: -* Core Files:: -* Targets:: -* Architectures:: -* Opening and Closing:: -* Internal:: -* File Caching:: -* Linker Functions:: -* Hash Tables:: -@end menu - -@node Memory Usage, Initialization, BFD front end, BFD front end -@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 Initialization, Sections, Memory Usage, BFD front end -@include init.texi - -@node Sections, Symbols, Initialization, BFD front end -@include section.texi - -@node Symbols, Archives, Sections, BFD front end -@include syms.texi - -@node Archives, Formats, Symbols, BFD front end -@include archive.texi - -@node Formats, Relocations, Archives, BFD front end -@include format.texi - -@node Relocations, Core Files, Formats, BFD front end -@include reloc.texi - -@node Core Files, Targets, Relocations, BFD front end -@include core.texi - -@node Targets, Architectures, Core Files, BFD front end -@include targets.texi - -@node Architectures, Opening and Closing, Targets, BFD front end -@include archures.texi - -@node Opening and Closing, Internal, Architectures, BFD front end -@include opncls.texi - -@node Internal, File Caching, Opening and Closing, BFD front end -@include libbfd.texi - -@node File Caching, Linker Functions, Internal, BFD front end -@include cache.texi - -@node Linker Functions, Hash Tables, File Caching, BFD front end -@include linker.texi - -@node Hash Tables, , Linker Functions, BFD front end -@include hash.texi - -@node BFD back ends, Index, BFD front end, Top -@chapter BFD back ends -@menu -* What to Put Where:: -* aout :: a.out backends -* coff :: coff backends -* elf :: elf backends -@ignore -* oasys :: oasys backends -* ieee :: ieee backend -* srecord :: s-record backend -@end ignore -@end menu -@node What to Put Where, aout, BFD back ends, BFD back ends -All of BFD lives in one directory. - -@node aout, coff, What to Put Where, BFD back ends -@include aoutx.texi - -@node coff, elf, aout, BFD back ends -@include coffcode.texi - -@node elf, , coff, BFD back ends -@include elf.texi -@c Leave this out until the file has some actual contents... -@c @include elfcode.texi - -@node Index, , BFD back ends , Top -@unnumbered 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 - -@contents -@bye |
