--- /dev/null
+\input texinfo
+@setfilename bfdinfo
+@c $Id$
+@synindex ky cp
+@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 < 2.0
+@subtitle April 1991
+@author {Steve Chamberlain}
+@author {Cygnus Support}
+@page
+
+@tex
+\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$} % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Support\par
+\hfill steve\@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
+* History:: History of BFD
+* Backends:: Backends
+* Porting:: Porting
+* Future:: Future
+* Index:: Index
+
+BFD body:
+* Memory usage::
+* Sections::
+* Symbols::
+* Archives::
+* Formats::
+* Relocations::
+* Core Files::
+* Targets::
+* Architecturs::
+* Opening and Closing::
+* Internal::
+* File Caching::
+
+BFD backends:
+* a.out backends::
+* coff backends::
+@end menu
+
+@node Overview, History, Top, Top
+@chapter Introduction
+@cindex BFD
+@cindex what is it?
+Simply put, BFD is a package which allows applications to use the
+same routines to operate on object files whatever the object file
+format. A different 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 many back ends.
+@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
+@node History, How It Works, Overview,Top
+@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
+Cygnus 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 Steve Chamberlain (steve@@cygnus.com),
+John Gilmore (gnu@@cygnus.com), K. Richard Pixley (rich@@cygnus.com) and
+David Wallace (gumby@@cygnus.com) at Cygnus Support in Palo Alto,
+California.
+
+@node How It Works, History, Porting, Top
+@section How It Works
+
+To use the library, include @code{bfd.h} and link with @code{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
+@code{include/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
+@samp{bfd}_.
+
+For example, this sequence would do what you would probably expect:
+return the number of sections in an object file attached to a BFD
+@code{abfd}.
+
+@lisp
+@cartouche
+#include "bfd.h"
+
+unsigned int number_of_sections(abfd)
+bfd *abfd;
+@{
+ return bfd_count_sections(abfd);
+@}
+@end cartouche
+@end lisp
+
+The abstraction used within BFD is that an object file has a header,
+a number of sections containing raw data, a set of relocations, and some
+symbol information. 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.
+
+@section What BFD Version 1 Can Do
+As different information from the the object files is required,
+BFD reads from different sections of the file and processes them.
+For example a very common operation for the linker is processing symbol
+tables. Each BFD back end provides a routine for converting
+between the object file's representation of symbols and an internal
+canonical format. When the linker asks for the symbol table of an object
+file, it calls through the memory pointer to the relevant BFD
+back end routine which reads and converts the table into a canonical
+form. The linker then operates upon the canonical form. When the link is
+finished and the linker writes the output file's symbol table,
+another BFD back end routine is called which takes the newly
+created symbol table and converts it into the chosen output format.
+
+@node BFD information loss, Mechanism, BFD outline, BFD
+@subsection Information Loss
+@emph{Some information is lost due to the nature of the file format.} The output targets
+supported by BFD do not provide identical facilities, and
+information which may be described in one form has nowhere to go in
+another format. One example of this is alignment information in
+@code{b.out}. There is nowhere in an @code{a.out} format file to store
+alignment information on the contained data, so when a file is linked
+from @code{b.out} and an @code{a.out} image is produced, alignment
+information will not propagate to the output file. (The linker will
+still use the alignment information internally, so the link is performed
+correctly).
+
+Another example is COFF section names. COFF files may contain an
+unlimited number of sections, each one with a textual section name. If
+the target of the link is a format which does not have many sections (eg
+@code{a.out}) or has sections without names (eg the Oasys format) the
+link cannot be done simply. You can circumvent this problem by
+describing the desired input-to-output section mapping with the linker command
+language.
+
+@emph{Information can be lost during canonicalization.} The BFD
+internal canonical form of the external formats is not exhaustive; there
+are structures in input formats for which there is no direct
+representation internally. This means that the BFD back ends
+cannot maintain all possible data richness through the transformation
+between external to internal and back to external formats.
+
+This limitation is only a problem when an application reads one
+format and writes another. Each BFD back end is responsible for
+maintaining as much data as possible, and the internal BFD
+canonical form has structures which are opaque to the BFD core,
+and exported only to the back ends. When a file is read in one format,
+the canonical form is generated for BFD and the application. At the
+same time, the back end saves away any information which may otherwise
+be lost. If the data is then written back in the same format, the back
+end routine will be able to use the canonical form provided by the
+BFD core as well as the information it prepared earlier. Since
+there is a great deal of commonality between back ends, this mechanism
+is very useful. There is no information lost for this reason when
+linking or copying big endian COFF to little endian COFF, or @code{a.out} to
+@code{b.out}. When a mixture of formats is linked, the information is
+only lost from the files whose format differs from the destination.
+
+@node Mechanism, , BFD information loss, BFD
+@subsection Mechanism
+The greatest potential for loss of information is when there is least
+overlap between the information provided by the source format, that
+stored by the canonical format, and the information needed by the
+destination format. A brief description of the canonical form may help
+you appreciate what kinds of data you can count on preserving across
+conversions.
+@cindex BFD canonical format
+@cindex internal object-file format
+
+@table @emph
+@item files
+Information on target machine architecture, particular implementation
+and format type are stored on a per-file basis. Other information
+includes a demand pageable bit and a write protected bit. Note that
+information like Unix magic numbers is not stored here---only the magic
+numbers' meaning, so a @code{ZMAGIC} file would have both the demand
+pageable bit and the write protected text bit set. The byte order of
+the target is stored on a per-file basis, so that big- and little-endian
+object files may be linked with one another.
+@c FIXME: generalize above from "link"?
+
+@item sections
+Each section in the input file contains the name of the section, the
+original address in the object file, various flags, size and alignment
+information and pointers into other BFD data structures.
+
+@item symbols
+Each symbol contains a pointer to the object file which originally
+defined it, its name, its value, and various flag bits. When a
+BFD back end reads in a symbol table, the back end relocates all
+symbols to make them relative to the base of the section where they were
+defined. This ensures that each symbol points to its containing
+section. Each symbol also has a varying amount of hidden data to contain
+private data for the BFD back end. Since the symbol points to the
+original file, the private data format for that symbol is accessible.
+@code{gld} can operate on a collection of symbols of wildly different
+formats without problems.
+
+Normal global and simple local symbols are maintained on output, so an
+output file (no matter its format) will retain symbols pointing to
+functions and to global, static, and common variables. Some symbol
+information is not worth retaining; in @code{a.out} type information is
+stored in the symbol table as long symbol names. This information would
+be useless to most COFF debuggers; the linker has command line switches
+to allow users to throw it away.
+
+There is one word of type information within the symbol, so if the
+format supports symbol type information within symbols (for example COFF,
+IEEE, Oasys) and the type is simple enough to fit within one word
+(nearly everything but aggregates) the information will be preserved.
+
+@item relocation level
+Each canonical BFD relocation record contains a pointer to the symbol to
+relocate to, the offset of the data to relocate, the section the data
+is in and a pointer to a relocation type descriptor. Relocation is
+performed effectively by message passing through the relocation type
+descriptor and symbol pointer. It allows relocations to be performed
+on output data using a relocation method only available in one of the
+input formats. For instance, Oasys provides a byte relocation format.
+A relocation record requesting this relocation type would point
+indirectly to a routine to perform this, so the relocation may be
+performed on a byte being written to a COFF file, even though 68k COFF
+has no such relocation type.
+
+@item line numbers
+Object formats can contain, for debugging purposes, some form of mapping
+between symbols, source line numbers, and addresses in the output file.
+These addresses have to be relocated along with the symbol information.
+Each symbol with an associated list of line number records points to the
+first record of the list. The head of a line number list consists of a
+pointer to the symbol, which allows divination of the address of the
+function whose line number is being described. The rest of the list is
+made up of pairs: offsets into the section and line numbers. Any format
+which can simply derive this information can pass it successfully
+between formats (COFF, IEEE and Oasys).
+@end table
+
+@c FIXME: what is this line about? Do we want introductory remarks
+@c FIXME... on back ends? commented out for now.
+@c What is a backend
+@node BFD front end, BFD back end, Mechanism, Top
+@chapter BFD front end
+@include bfd.texi
+
+@node Memory Usage, Sections, bfd, Top
+@section Memory Usage
+BFD keeps all 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 libbfd for the closing file will be thrown away.
+
+BFD will not free anything created by an application, but pointers into
+@code{bfd} structures will be invalidated on a @code{bfd_close}; for example,
+after a @code{bfd_close} the vector passed to
+@code{bfd_canonicalize_symtab} will still be around, since it has been
+allocated by the application, but the data that it pointed to will be
+lost.
+
+The general rule is not to 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,Symbols ,Memory Usage, Top
+@include section.texi
+
+@node Symbols, Archives ,Sections, To
+@include syms.texi
+
+@node Archives, Formats, Symbols, Top
+@include archive.texi
+
+@node Formats, Relocations, Archives, Top
+@include format.texi
+
+@node Relocations, Core Files,Formats, Top
+@include reloc.texi
+
+@node Core Files, Targets, Relocations, Top
+@include core.texi
+
+@node Targets, Architectures, Core Files, Top
+@include targets.texi
+
+@node Architectures, Opening and Closing, Targets, Top
+@include archures.texi
+
+@node Opening and Closing, Internal, Architectures, Top
+@include opncls.texi
+
+@node Internal, File Caching, Opening and Closing, Top
+@include libbfd.texi
+
+@node File Caching, Top, Internal, Top
+@include cache.texi
+
+@chapter BFD back end
+@node BFD back end, ,BFD front end, Top
+@menu
+* What to put where
+* a.out backends::
+* coff backends::
+* oasys backend::
+* ieee backend::
+* srecord backend::
+@end menu
+@node What to Put Where, aout backends, BFD back end, BFD back end
+All of BFD lives in one directory.
+
+@node aout backends, coff backends, What to Put Where, BFD back end
+@include aoutx.texi
+
+@node coff backends, oasys backends, aout backends, BFD back end
+@include coffcode.texi
+
+@node Index, , BFD, Top
+@unnumbered Function Index
+@printindex fn
+@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: pesch@cygnus.com, 28mar91.
+@end tex
+
+
+@contents
+@bye
+
+
--- /dev/null
+Info file bfdinfo, produced by Makeinfo, -*- Text -*- from input file
+bfd.texinfo.
+
+ 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.
+
+ 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.
+
+\1f
+File: bfdinfo, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
+
+ This file documents the binary file descriptor library libbfd.
+
+* Menu:
+
+* Overview:: Overview of BFD
+* History:: History of BFD
+* Backends:: Backends
+* Porting:: Porting
+* Future:: Future
+* Index:: Index
+
+BFD body:
+* Memory usage::
+* Sections::
+* Symbols::
+* Archives::
+* Formats::
+* Relocations::
+* Core Files::
+* Targets::
+* Architecturs::
+* Opening and Closing::
+* Internal::
+* File Caching::
+
+BFD backends:
+* a.out backends::
+* coff backends::
+
+\1f
+File: bfdinfo, Node: Overview, Next: History, Prev: Top, Up: Top
+
+Introduction
+************
+
+ Simply put, BFD is a package which allows applications to use the
+same routines to operate on object files whatever the object file
+format. A different 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 many back ends.
+
+ * memory, and various canonical data structures. The front end also
+ decides which back end to use, and when to call back end routines.
+
+ * 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.
+
+\1f
+File: bfdinfo, Node: History, Next: How It Works, Prev: Overview, Up: Top
+
+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
+Cygnus 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 Steve Chamberlain (steve@cygnus.com),
+John Gilmore (gnu@cygnus.com), K. Richard Pixley (rich@cygnus.com) and
+David Wallace (gumby@cygnus.com) at Cygnus Support in Palo Alto,
+California.
+
+\1f
+File: bfdinfo, Node: How It Works, Next: History, Prev: Porting, Up: Top
+
+How It Works
+============
+
+ To use the library, include `bfd.h' and link with `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 `bfd', described in
+`include/bfd.h'. Our convention is to call this pointer a BFD, and
+instances of it within code `abfd'. All operations on the target
+object file are applied as methods to the BFD. The mapping is defined
+within `bfd.h' in a set of macros, all beginning `bfd'_.
+
+ For example, this sequence would do what you would probably expect:
+return the number of sections in an object file attached to a BFD
+`abfd'.
+
+
+ #include "bfd.h"
+
+ unsigned int number_of_sections(abfd)
+ bfd *abfd;
+ {
+ return bfd_count_sections(abfd);
+ }
+
+ lisp
+
+ The abstraction used within BFD is that an object file has a header,
+a number of sections containing raw data, a set of relocations, and
+some symbol information. 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.
+
+What BFD Version 1 Can Do
+=========================
+
+ As different information from the the object files is required, BFD
+reads from different sections of the file and processes them. For
+example a very common operation for the linker is processing symbol
+tables. Each BFD back end provides a routine for converting between
+the object file's representation of symbols and an internal canonical
+format. When the linker asks for the symbol table of an object file,
+it calls through the memory pointer to the relevant BFD back end
+routine which reads and converts the table into a canonical form. The
+linker then operates upon the canonical form. When the link is
+finished and the linker writes the output file's symbol table, another
+BFD back end routine is called which takes the newly created symbol
+table and converts it into the chosen output format.
+
+\1f
+File: bfdinfo, Node: BFD information loss, Next: Mechanism, Prev: BFD outline, Up: BFD
+
+Information Loss
+----------------
+
+ *Some information is lost due to the nature of the file format.*
+The output targets supported by BFD do not provide identical
+facilities, and information which may be described in one form has
+nowhere to go in another format. One example of this is alignment
+information in `b.out'. There is nowhere in an `a.out' format file to
+store alignment information on the contained data, so when a file is
+linked from `b.out' and an `a.out' image is produced, alignment
+information will not propagate to the output file. (The linker will
+still use the alignment information internally, so the link is
+performed correctly).
+
+ Another example is COFF section names. COFF files may contain an
+unlimited number of sections, each one with a textual section name. If
+the target of the link is a format which does not have many sections
+(eg `a.out') or has sections without names (eg the Oasys format) the
+link cannot be done simply. You can circumvent this problem by
+describing the desired input-to-output section mapping with the linker
+command language.
+
+ *Information can be lost during canonicalization.* The BFD internal
+canonical form of the external formats is not exhaustive; there are
+structures in input formats for which there is no direct
+representation internally. This means that the BFD back ends cannot
+maintain all possible data richness through the transformation between
+external to internal and back to external formats.
+
+ This limitation is only a problem when an application reads one
+format and writes another. Each BFD back end is responsible for
+maintaining as much data as possible, and the internal BFD canonical
+form has structures which are opaque to the BFD core, and exported
+only to the back ends. When a file is read in one format, the
+canonical form is generated for BFD and the application. At the same
+time, the back end saves away any information which may otherwise be
+lost. If the data is then written back in the same format, the back
+end routine will be able to use the canonical form provided by the BFD
+core as well as the information it prepared earlier. Since there is a
+great deal of commonality between back ends, this mechanism is very
+useful. There is no information lost for this reason when linking or
+copying big endian COFF to little endian COFF, or `a.out' to `b.out'.
+When a mixture of formats is linked, the information is only lost from
+the files whose format differs from the destination.
+
+\1f
+File: bfdinfo, Node: Mechanism, Prev: BFD information loss, Up: BFD
+
+Mechanism
+---------
+
+ The greatest potential for loss of information is when there is
+least overlap between the information provided by the source format,
+that stored by the canonical format, and the information needed by the
+destination format. A brief description of the canonical form may help
+you appreciate what kinds of data you can count on preserving across
+conversions.
+
+*files*
+ Information on target machine architecture, particular
+ implementation and format type are stored on a per-file basis.
+ Other information includes a demand pageable bit and a write
+ protected bit. Note that information like Unix magic numbers is
+ not stored here--only the magic numbers' meaning, so a `ZMAGIC'
+ file would have both the demand pageable bit and the write
+ protected text bit set. The byte order of the target is stored
+ on a per-file basis, so that big- and little-endian object files
+ may be linked with one another.
+
+*sections*
+ Each section in the input file contains the name of the section,
+ the original address in the object file, various flags, size and
+ alignment information and pointers into other BFD data structures.
+
+*symbols*
+ Each symbol contains a pointer to the object file which originally
+ defined it, its name, its value, and various flag bits. When a
+ BFD back end reads in a symbol table, the back end relocates all
+ symbols to make them relative to the base of the section where
+ they were defined. This ensures that each symbol points to its
+ containing section. Each symbol also has a varying amount of
+ hidden data to contain private data for the BFD back end. Since
+ the symbol points to the original file, the private data format
+ for that symbol is accessible. `gld' can operate on a collection
+ of symbols of wildly different formats without problems.
+
+ Normal global and simple local symbols are maintained on output,
+ so an output file (no matter its format) will retain symbols
+ pointing to functions and to global, static, and common
+ variables. Some symbol information is not worth retaining; in
+ `a.out' type information is stored in the symbol table as long
+ symbol names. This information would be useless to most COFF
+ debuggers; the linker has command line switches to allow users to
+ throw it away.
+
+ There is one word of type information within the symbol, so if the
+ format supports symbol type information within symbols (for
+ example COFF, IEEE, Oasys) and the type is simple enough to fit
+ within one word (nearly everything but aggregates) the
+ information will be preserved.
+
+*relocation level*
+ Each canonical BFD relocation record contains a pointer to the
+ symbol to relocate to, the offset of the data to relocate, the
+ section the data is in and a pointer to a relocation type
+ descriptor. Relocation is performed effectively by message
+ passing through the relocation type descriptor and symbol
+ pointer. It allows relocations to be performed on output data
+ using a relocation method only available in one of the input
+ formats. For instance, Oasys provides a byte relocation format.
+ A relocation record requesting this relocation type would point
+ indirectly to a routine to perform this, so the relocation may be
+ performed on a byte being written to a COFF file, even though 68k
+ COFF has no such relocation type.
+
+*line numbers*
+ Object formats can contain, for debugging purposes, some form of
+ mapping between symbols, source line numbers, and addresses in
+ the output file. These addresses have to be relocated along with
+ the symbol information. Each symbol with an associated list of
+ line number records points to the first record of the list. The
+ head of a line number list consists of a pointer to the symbol,
+ which allows divination of the address of the function whose line
+ number is being described. The rest of the list is made up of
+ pairs: offsets into the section and line numbers. Any format
+ which can simply derive this information can pass it successfully
+ between formats (COFF, IEEE and Oasys).
+
+\1f
+File: bfdinfo, Node: BFD front end, Next: BFD back end, Prev: Mechanism, Up: Top
+
+BFD front end
+*************
+
+typedef bfd
+===========
+
+ Pointers to bfd structs are the cornerstone of any application using
+`libbfd'. References though the BFD and to data in the BFD give the
+entire BFD functionality.
+
+ Here is the BFD struct itself. This contains the major data about
+the file, and contains pointers to the rest of the data.
+
+ struct _bfd
+ {
+
+ The filename the application opened the BFD with.
+
+ CONST char *filename;
+
+ A pointer to the target jump table.
+
+ struct bfd_target *xvec;
+
+ To avoid dragging too many header files into every file that
+includes `bfd.h', IOSTREAM has been declared as a "char *", and MTIME
+as a "long". Their correct types, to which they are cast when used,
+are "FILE *" and "time_t".
+
+ The iostream is the result of an fopen on the filename.
+
+ char *iostream;
+
+ Is the file being cached *Note File Caching::.
+
+ boolean cacheable;
+
+ Marks whether there was a default target specified when the BFD was
+opened. This is used to select what matching algorithm to use to chose
+the back end.
+
+ boolean target_defaulted;
+
+ The caching routines use these to maintain a least-recently-used
+list of BFDs (*note File Caching::.).
+
+ struct _bfd *lru_prev, *lru_next;
+
+ When a file is closed by the caching routines, BFD retains state
+information on the file here:
+
+ file_ptr where;
+
+ and here:
+
+ boolean opened_once;
+
+ boolean mtime_set;
+
+ File modified time
+
+ long mtime;
+
+ Reserved for an unimplemented file locking extension.
+
+ int ifd;
+
+ The format which belongs to the BFD.
+
+ bfd_format format;
+
+ The direction the BFD was opened with
+
+ enum bfd_direction {no_direction = 0,
+ read_direction = 1,
+ write_direction = 2,
+ both_direction = 3} direction;
+
+ Format_specific flags
+
+ flagword flags;
+
+ Currently my_archive is tested before adding origin to anything. I
+believe that this can become always an add of origin, with origin set
+to 0 for non archive files.
+
+ file_ptr origin;
+
+ Remember when output has begun, to stop strange things happening.
+
+ boolean output_has_begun;
+
+ Pointer to linked list of sections
+
+ struct sec *sections;
+
+ The number of sections
+
+ unsigned int section_count;
+
+ Stuff only useful for object files: The start address.
+
+ bfd_vma start_address;
+
+ Used for input and output
+
+ unsigned int symcount;
+
+ Symbol table for output BFD
+
+ struct symbol_cache_entry **outsymbols;
+
+ Architecture of object machine, eg m68k
+
+ enum bfd_architecture obj_arch;
+
+ Particular machine within arch, e.g. 68010
+
+ unsigned long obj_machine;
+
+ Stuff only useful for archives:
+
+ PTR arelt_data;
+ struct _bfd *my_archive;
+ struct _bfd *next;
+ struct _bfd *archive_head;
+ boolean has_armap;
+
+ Used by the back end to hold private data.
+
+ PTR tdata;
+
+ Used by the application to hold private data
+
+ PTR usrdata;
+
+ Where all the allocated stuff under this BFD goes (*note Memory
+Usage::.).
+
+ struct obstack memory;
+ };
+
+`bfd_set_start_address'
+.......................
+
+ Marks the entry point of an output BFD. Returns `true' on success,
+`false' otherwise.
+
+ boolean bfd_set_start_address(bfd *, bfd_vma);
+
+`bfd_get_mtime'
+...............
+
+ Return cached file modification time (e.g. as read from archive
+header for archive members, or from file system if we have been called
+before); else determine modify time, cache it, and return it.
+
+ long bfd_get_mtime(bfd *);
+
+`stuff'
+.......
+
+
+
+ #define bfd_sizeof_headers(abfd, reloc) \
+ BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
+
+ #define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \
+ BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr))
+
+ #define bfd_debug_info_start(abfd) \
+ BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
+
+ #define bfd_debug_info_end(abfd) \
+ BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
+
+ #define bfd_debug_info_accumulate(abfd, section) \
+ BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
+
+ #define bfd_stat_arch_elt(abfd, stat) \
+ BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
+
+ #define bfd_coff_swap_aux_in(a,e,t,c,i) \
+ BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
+
+ #define bfd_coff_swap_sym_in(a,e,i) \
+ BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
+
+ #define bfd_coff_swap_lineno_in(a,e,i) \
+ BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
+
+ lisp
+
+\1f
+File: bfdinfo, Node: Memory Usage, Next: Sections, Prev: bfd, Up: Top
+
+Memory Usage
+============
+
+ BFD keeps all 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 libbfd for the closing file will be thrown away.
+
+ BFD will not free anything created by an application, but pointers
+into `bfd' structures will be invalidated on a `bfd_close'; for
+example, after a `bfd_close' the vector passed to
+`bfd_canonicalize_symtab' will still be around, since it has been
+allocated by the application, but the data that it pointed to will be
+lost.
+
+ The general rule is not to 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 (`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.
+
+\1f
+File: bfdinfo, Node: Sections, Next: Symbols, Prev: Memory Usage, Up: Top
+
+Sections
+========
+
+ Sections are supported in BFD in `section.c'.
+
+ The raw data contained within a BFD is maintained through the
+section abstraction. A single BFD may have any number of sections,
+and keeps hold of them by pointing to the first, each one points to
+the next in the list.
+
+* Menu:
+
+* Section Input::
+* Section Output::
+* typedef asection::
+* section prototypes::
+
+\1f
+File: bfdinfo, Node: Section Input, Next: Section Output, Up: Sections
+
+Section Input
+-------------
+
+ When a BFD is opened for reading, the section structures are created
+and attached to the BFD.
+
+ Each section has a name which describes the section in the outside
+world - for example, `a.out' would contain at least three sections,
+called `.text', `.data' and `.bss'.
+
+ Sometimes a BFD will contain more than the 'natural' number of
+sections. A back end may attach other sections containing constructor
+data, or an application may add a section (using bfd_make_section) to
+the sections attached to an already open BFD. For example, the linker
+creates a supernumary section `COMMON' for each input file's BFD to
+hold information about common storage.
+
+ The raw data is not necessarily read in at the same time as the
+section descriptor is created. Some targets may leave the data in
+place until a `bfd_get_section_contents' call is made. Other back ends
+may read in all the data at once - For example; an S-record file has
+to be read once to determine the size of the data. An IEEE-695 file
+doesn't contain raw data in sections, but data and relocation
+expressions intermixed, so the data area has to be parsed to get out
+the data and relocations.
+
+\1f
+File: bfdinfo, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections
+
+Section Output
+--------------
+
+ To write a new object style BFD, the various sections to be written
+have to be created. They are attached to the BFD in the same way as
+input sections, data is written to the sections using
+`bfd_set_section_contents'.
+
+ The linker uses the fields `output_section' and `output_offset' to
+create an output file.
+
+ The data to be written comes from input sections attached to the
+output sections. The output section structure can be considered a
+filter for the input section, the output section determines the vma of
+the output data and the name, but the input section determines the
+offset into the output section of the data to be written.
+
+ Eg to create a section "O", starting at 0x100, 0x123 long,
+containing two subsections, "A" at offset 0x0 (ie at vma 0x100) and
+"B" at offset 0x20 (ie at vma 0x120) the structures would look like:
+
+
+
+ section name "A"
+ output_offset 0x00
+ size 0x20
+ output_section -----------> section name "O"
+ | vma 0x100
+ section name "B" | size 0x123
+ output_offset 0x20 |
+ size 0x103 |
+ output_section --------|
+
+ lisp
+
+\1f
+File: bfdinfo, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections
+
+typedef asection
+----------------
+
+ The shape of a section struct:
+
+ typedef struct sec {
+
+ The name of the section, the name isn't a copy, the pointer is the
+same as that passed to bfd_make_section.
+
+ CONST char *name;
+
+ The next section in the list belonging to the BFD, or NULL.
+
+ struct sec *next;
+
+ The field flags contains attributes of the section. Some of these
+flags are read in from the object file, and some are synthesized from
+other information.
+
+ flagword flags;
+
+ #define SEC_NO_FLAGS 0x000
+
+ Tells the OS to allocate space for this section when loaded. This
+would clear for a section containing debug information only.
+
+ #define SEC_ALLOC 0x001
+
+ Tells the OS to load the section from the file when loading. This
+would be clear for a .bss section
+
+ #define SEC_LOAD 0x002
+
+ The section contains data still to be relocated, so there will be
+some relocation information too.
+
+ #define SEC_RELOC 0x004
+
+ Obsolete
+
+ #define SEC_BALIGN 0x008
+
+ A signal to the OS that the section contains read only data.
+
+ #define SEC_READONLY 0x010
+
+ The section contains code only.
+
+ #define SEC_CODE 0x020
+
+ The section contains data only.
+
+ #define SEC_DATA 0x040
+
+ The section will reside in ROM.
+
+ #define SEC_ROM 0x080
+
+ The section contains constructor information. This section type is
+used by the linker to create lists of constructors and destructors
+used by `g++'. When a back end sees a symbol which should be used in a
+constructor list, it creates a new section for the type of name (eg
+`__CTOR_LIST__'), attaches the symbol to it and builds a relocation.
+To build the lists of constructors, all the linker has to to is
+catenate all the sections called `__CTOR_LIST__' and relocte the data
+contained within - exactly the operations it would peform on standard
+data.
+
+ #define SEC_CONSTRUCTOR 0x100
+
+ The section is a constuctor, and should be placed at the end of the
+..
+
+ #define SEC_CONSTRUCTOR_TEXT 0x1100
+
+ #define SEC_CONSTRUCTOR_DATA 0x2100
+
+ #define SEC_CONSTRUCTOR_BSS 0x3100
+
+ The section has contents - a bss section could be `SEC_ALLOC' |
+`SEC_HAS_CONTENTS', a debug section could be `SEC_HAS_CONTENTS'
+
+ #define SEC_HAS_CONTENTS 0x200
+
+ An instruction to the linker not to output sections containing this
+flag even if they have information which would normally be written.
+
+ #define SEC_NEVER_LOAD 0x400
+
+ The base address of the section in the address space of the target.
+
+ bfd_vma vma;
+
+ The size of the section in bytes of the loaded section. This
+contains a value even if the section has no contents (eg, the size of
+`.bss').
+
+ bfd_size_type size;
+
+ If this section is going to be output, then this value is the
+offset into the output section of the first byte in the input section.
+Eg, if this was going to start at the 100th byte in the output
+section, this value would be 100.
+
+ bfd_vma output_offset;
+
+ The output section through which to map on output.
+
+ struct sec *output_section;
+
+ The alignment requirement of the section, as an exponent - eg 3
+aligns to 2^3 (or 8)
+
+ unsigned int alignment_power;
+
+ If an input section, a pointer to a vector of relocation records for
+the data in this section.
+
+ struct reloc_cache_entry *relocation;
+
+ If an output section, a pointer to a vector of pointers to
+relocation records for the data in this section.
+
+ struct reloc_cache_entry **orelocation;
+
+ The number of relocation records in one of the above
+
+ unsigned reloc_count;
+
+ Which section is it 0..nth
+
+ int index;
+
+ Information below is back end specific - and not always used or
+updated
+
+ File position of section data
+
+ file_ptr filepos;
+
+ File position of relocation info
+
+ file_ptr rel_filepos;
+
+ File position of line data
+
+ file_ptr line_filepos;
+
+ Pointer to data for applications
+
+ PTR userdata;
+
+ struct lang_output_section *otheruserdata;
+
+ Attached line number information
+
+ alent *lineno;
+
+ Number of line number records
+
+ unsigned int lineno_count;
+
+ When a section is being output, this value changes as more
+linenumbers are written out
+
+ file_ptr moving_line_filepos;
+
+ what the section number is in the target world
+
+ unsigned int target_index;
+
+ PTR used_by_bfd;
+
+ If this is a constructor section then here is a list of the
+relocations created to relocate items within it.
+
+ struct relent_chain *constructor_chain;
+
+ The BFD which owns the section.
+
+ bfd *owner;
+
+ } asection ;
+
+\1f
+File: bfdinfo, Node: section prototypes, Next: Section, Prev: typedef section, Up: Sections
+
+section prototypes
+------------------
+
+`bfd_get_section_by_name'
+.........................
+
+ Runs through the provided ABFD and returns the `asection' who's
+name matches that provided, otherwise NULL. *Note Sections::, for more
+information.
+
+ asection * bfd_get_section_by_name(bfd *abfd, CONST char *name);
+
+`bfd_make_section'
+..................
+
+ This function creates a new empty section called NAME and attaches
+it to the end of the chain of sections for the BFD supplied. An
+attempt to create a section with a name which is already in use,
+returns the old section by that name instead.
+
+ Possible errors are:
+
+`invalid_operation'
+ If output has already started for this BFD.
+
+`no_memory'
+ If obstack alloc fails.
+
+ asection * bfd_make_section(bfd *, CONST char *name);
+
+`bfd_set_section_flags'
+.......................
+
+ Attempts to set the attributes of the section named in the BFD
+supplied to the value. Returns true on success, false on error.
+Possible error returns are:
+
+`invalid operation'
+ The section cannot have one or more of the attributes requested.
+ For example, a .bss section in `a.out' may not have the
+ `SEC_HAS_CONTENTS' field set.
+
+ boolean bfd_set_section_flags(bfd *, asection *, flagword);
+
+`bfd_map_over_sections'
+.......................
+
+ Calls the provided function FUNC for each section attached to the
+BFD ABFD, passing OBJ as an argument. The function will be called as
+if by
+
+ func(abfd, the_section, obj);
+
+ void bfd_map_over_sections(bfd *abfd, void (*func)(), PTR obj);
+
+ This is the prefered method for iterating over sections, an
+alternative would be to use a loop:
+
+ section *p;
+ for (p = abfd->sections; p != NULL; p = p->next)
+ func(abfd, p, ...)
+
+`bfd_set_section_size'
+......................
+
+ Sets SECTION to the size VAL. If the operation is ok, then `true'
+is returned, else `false'.
+
+ Possible error returns:
+
+`invalid_operation'
+ Writing has started to the BFD, so setting the size is invalid
+
+ boolean bfd_set_section_size(bfd *, asection *, bfd_size_type val);
+
+`bfd_set_section_contents'
+..........................
+
+ Sets the contents of the section SECTION in BFD ABFD to the data
+starting in memory at DATA. The data is written to the output section
+starting at offset OFFSET for COUNT bytes.
+
+ Normally `true' is returned, else `false'. Possible error returns
+are:
+
+`no_contents'
+ The output section does not have the `SEC_HAS_CONTENTS'
+ attribute, so nothing can be written to it.
+
+`and some more too'
+ This routine is front end to the back end function
+`_bfd_set_section_contents'.
+
+ boolean bfd_set_section_contents(bfd *abfd,
+ asection *section,
+ PTR data,
+ file_ptr offset,
+ bfd_size_type count);
+
+`bfd_get_section_contents'
+..........................
+
+ This function reads data from SECTION in BFD ABFD into memory
+starting at LOCATION. The data is read at an offset of OFFSET from the
+start of the input section, and is read for COUNT bytes.
+
+ If the contents of a constuctor with the `SEC_CONSTUCTOR' flag set
+are requested, then the LOCATION is filled with zeroes.
+
+ If no errors occur, `true' is returned, else `false'. Possible
+errors are:
+
+`unknown yet'
+ boolean bfd_get_section_contents(bfd *abfd, asection *section, PTR location,
+ file_ptr offset, bfd_size_type count);
+
+\1f
+File: bfdinfo, Node: Symbols, Next: Archives, Prev: Sections, Up: To
+
+Symbols
+=======
+
+ BFD trys to maintain as much symbol information as it can when it
+moves information from file to file. BFD passes information to
+applications though the `asymbol' structure. When the application
+requests the symbol table, BFD reads the table in the native form and
+translates parts of it into the internal format. To maintain more than
+the infomation passed to applications some targets keep some
+information 'behind the sceans', in a structure only the particular
+back end knows about. For example, the coff back end keeps the
+original symbol table structure as well as the canonical structure
+when a BFD is read in. On output, the coff back end can reconstruct
+the output symbol table so that no information is lost, even
+information unique to coff which BFD doesn't know or understand. If a
+coff symbol table was read, but was written through an a.out back end,
+all the coff specific information would be lost. (.. until BFD 2 :).
+
+ The symbol table of a BFD is not necessarily read in until a
+canonicalize request is made. Then the BFD back end fills in a table
+provided by the application with pointers to the canonical information.
+
+ To output symbols, the application provides BFD with a table of
+pointers to pointers to `asymbol's. This allows applications like the
+linker to output a symbol as read, since the 'behind the sceens'
+information will be still available.
+
+* Menu:
+
+* Reading Symbols::
+* Writing Symbols::
+* typedef asymbol::
+* symbol handling functions::
+
+\1f
+File: bfdinfo, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols
+
+Reading Symbols
+---------------
+
+ There are two stages to reading a symbol table from a BFD;
+allocating storage, and the actual reading process. This is an excerpt
+from an appliction which reads the symbol table:
+
+
+ unsigned int storage_needed;
+ asymbol **symbol_table;
+ unsigned int number_of_symbols;
+ unsigned int i;
+
+ storage_needed = get_symtab_upper_bound (abfd);
+
+ if (storage_needed == 0) {
+ return ;
+ }
+ symbol_table = (asymbol **) malloc (storage_needed);
+ ...
+ number_of_symbols =
+ bfd_canonicalize_symtab (abfd, symbol_table);
+
+ for (i = 0; i < number_of_symbols; i++) {
+ process_symbol (symbol_table[i]);
+ }
+
+ lisp
+
+ All storage for the symbols themselves is in an obstack connected to
+the BFD, and is freed when the BFD is closed.
+
+\1f
+File: bfdinfo, Node: Writing Symbols, Next: typedef asymbol, Prev: Reading Symbols, Up: Symbols
+
+Writing Symbols
+---------------
+
+ Writing of a symbol table is automatic when a BFD open for writing
+is closed. The application attaches a vector of pointers to pointers
+to symbols to the BFD being written, and fills in the symbol count.
+The close and cleanup code reads through the table provided and
+performs all the necessary operations. The outputing code must always
+be provided with an 'owned' symbol; one which has come from another
+BFD, or one which has been created using `bfd_make_empty_symbol'.
+
+ An example showing the creation of a symbol table with only one
+element:
+
+
+ #include "bfd.h"
+ main()
+ {
+ bfd *abfd;
+ asymbol *ptrs[2];
+ asymbol *new;
+
+ abfd = bfd_openw("foo","a.out-sunos-big");
+ bfd_set_format(abfd, bfd_object);
+ new = bfd_make_empty_symbol(abfd);
+ new->name = "dummy_symbol";
+ new->section = (asection *)0;
+ new->flags = BSF_ABSOLUTE | BSF_GLOBAL;
+ new->value = 0x12345;
+
+ ptrs[0] = new;
+ ptrs[1] = (asymbol *)0;
+
+ bfd_set_symtab(abfd, ptrs, 1);
+ bfd_close(abfd);
+ }
+
+ ./makesym
+ nm foo
+ 00012345 A dummy_symbol
+
+ lisp
+
+ Many formats cannot represent arbitary symbol information; for
+instance the `a.out' object format does not allow an arbitary number
+of sections. A symbol pointing to a section which is not one of
+`.text', `.data' or `.bss' cannot be described.
+
+\1f
+File: bfdinfo, Node: typedef asymbol, Next: symbol handling functions, Prev: Writing Symbols, Up: Symbols
+
+typedef asymbol
+---------------
+
+ An `asymbol' has the form:
+
+ typedef struct symbol_cache_entry
+ {
+
+ A pointer to the BFD which owns the symbol. This information is
+necessary so that a back end can work out what additional (invisible to
+the application writer) information is carried with the symbol.
+
+ struct _bfd *the_bfd;
+
+ The text of the symbol. The name is left alone, and not copied - the
+application may not alter it.
+
+ CONST char *name;
+
+ The value of the symbol.
+
+ symvalue value;
+
+ Attributes of a symbol:
+
+ #define BSF_NO_FLAGS 0x00
+
+ The symbol has local scope; `static' in `C'. The value is the
+offset into the section of the data.
+
+ #define BSF_LOCAL 0x01
+
+ The symbol has global scope; initialized data in `C'. The value is
+the offset into the section of the data.
+
+ #define BSF_GLOBAL 0x02
+
+ Obsolete
+
+ #define BSF_IMPORT 0x04
+
+ The symbol has global scope, and is exported. The value is the
+offset into the section of the data.
+
+ #define BSF_EXPORT 0x08
+
+ The symbol is undefined. `extern' in `C'. The value has no meaning.
+
+ #define BSF_UNDEFINED 0x10
+
+ The symbol is common, initialized to zero; default in `C'. The
+value is the size of the object in bytes.
+
+ #define BSF_FORT_COMM 0x20
+
+ A normal `C' symbol would be one of: `BSF_LOCAL', `BSF_FORT_COMM',
+`BSF_UNDEFINED' or `BSF_EXPORT|BSD_GLOBAL'
+
+ The symbol is a debugging record. The value has an arbitary meaning.
+
+ #define BSF_DEBUGGING 0x40
+
+ The symbol has no section attached, any value is the actual value
+and is not a relative offset to a section.
+
+ #define BSF_ABSOLUTE 0x80
+
+ Used by the linker
+
+ #define BSF_KEEP 0x10000
+ #define BSF_KEEP_G 0x80000
+
+ Unused
+
+ #define BSF_WEAK 0x100000
+ #define BSF_CTOR 0x200000
+ #define BSF_FAKE 0x400000
+
+ The symbol used to be a common symbol, but now it is allocated.
+
+ #define BSF_OLD_COMMON 0x800000
+
+ The default value for common data.
+
+ #define BFD_FORT_COMM_DEFAULT_VALUE 0
+
+ In some files the type of a symbol sometimes alters its location in
+an output file - ie in coff a `ISFCN' symbol which is also `C_EXT'
+symbol appears where it was declared and not at the end of a section.
+This bit is set by the target BFD part to convey this information.
+
+ #define BSF_NOT_AT_END 0x40000
+
+ Signal that the symbol is the label of constructor section.
+
+ #define BSF_CONSTRUCTOR 0x1000000
+
+ Signal that the symbol is a warning symbol. If the symbol is a
+warning symbol, then the value field (I know this is tacky) will point
+to the asymbol which when referenced will cause the warning.
+
+ #define BSF_WARNING 0x2000000
+
+ Signal that the symbol is indirect. The value of the symbol is a
+pointer to an undefined asymbol which contains the name to use instead.
+
+ #define BSF_INDIRECT 0x4000000
+
+ flagword flags;
+
+ A pointer to the section to which this symbol is relative, or 0 if
+the symbol is absolute or undefined. Note that it is not sufficient to
+set this location to 0 to mark a symbol as absolute - the flag
+`BSF_ABSOLUTE' must be set also.
+
+ struct sec *section;
+
+ Back end special data. This is being phased out in favour of making
+this a union.
+
+ PTR udata;
+ } asymbol;
+
+\1f
+File: bfdinfo, Node: symbol handling functions, Next: Symbols, Prev: typedef asymbol, Up: Symbols
+
+Symbol Handling Functions
+-------------------------
+
+`get_symtab_upper_bound'
+........................
+
+ Returns the number of bytes required in a vector of pointers to
+`asymbols' for all the symbols in the supplied BFD, including a
+terminal NULL pointer. If there are no symbols in the BFD, then 0 is
+returned.
+
+
+ #define get_symtab_upper_bound(abfd) \
+ BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
+
+ lisp
+
+`bfd_canonicalize_symtab'
+.........................
+
+ Supplied a BFD and a pointer to an uninitialized vector of pointers.
+This reads in the symbols from the BFD, and fills in the table with
+pointers to the symbols, and a trailing NULL. The routine returns the
+actual number of symbol pointers not including the NULL.
+
+
+ #define bfd_canonicalize_symtab(abfd, location) \
+ BFD_SEND (abfd, _bfd_canonicalize_symtab,\
+ (abfd, location))
+
+ lisp
+
+`bfd_set_symtab'
+................
+
+ Provided a table of pointers to to symbols and a count, writes to
+the output BFD the symbols when closed.
+
+ boolean bfd_set_symtab(bfd *, asymbol **, unsigned int );
+
+`bfd_print_symbol_vandf'
+........................
+
+ Prints the value and flags of the symbol supplied to the stream
+file.
+
+ void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
+
+`bfd_make_empty_symbol'
+.......................
+
+ This function creates a new `asymbol' structure for the BFD, and
+returns a pointer to it.
+
+ This routine is necessary, since each back end has private
+information surrounding the `asymbol'. Building your own `asymbol' and
+pointing to it will not create the private information, and will cause
+problems later on.
+
+
+ #define bfd_make_empty_symbol(abfd) \
+ BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
+
+ lisp
+
+\1f
+File: bfdinfo, Node: Archives, Next: Formats, Prev: Symbols, Up: Top
+
+Archives
+========
+
+ Gumby, you promised to write this bit...
+
+ Archives are supported in BFD in `archive.c'.
+
+ An archive is represented internally just like another BFD, with a
+pointer to a chain of contained BFDs. Archives can be created by
+opening BFDs, linking them together and attaching them as children to
+another BFD and then closing the parent BFD.
+
+`bfd_get_next_mapent'
+.....................
+
+ What this does
+
+ symindex bfd_get_next_mapent(bfd *, symindex, carsym **);
+
+`bfd_set_archive_head'
+......................
+
+ Used whilst processing archives. Sets the head of the chain of BFDs
+contained in an archive to NEW_HEAD. (see chapter on archives)
+
+ boolean bfd_set_archive_head(bfd *output, bfd *new_head);
+
+`bfd_get_elt_at_index'
+......................
+
+ Return the sub bfd contained within the archive at archive index n.
+
+ bfd * bfd_get_elt_at_index(bfd *, int);
+
+`bfd_openr_next_archived_file'
+..............................
+
+ Initially provided a BFD containing an archive and NULL, opens a BFD
+on the first contained element and returns that. Subsequent calls to
+bfd_openr_next_archived_file should pass the archive and the previous
+return value to return a created BFD to the next contained element.
+NULL is returned when there are no more.
+
+ bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
+
+\1f
+File: bfdinfo, Node: Formats, Next: Relocations, Prev: Archives, Up: Top
+
+File Formats
+============
+
+ A format is a BFD concept of high level file contents. The formats
+supported by BFD are:
+
+`bfd_object'
+ The BFD may contain data, symbols, relocations and debug info.
+
+`bfd_archive'
+ The
\ No newline at end of file
projects / binutils-gdb.git / commitdiff