diff options
Diffstat (limited to 'bfd/doc')
| -rwxr-xr-x | bfd/doc/Makefile | 56 | ||||
| -rwxr-xr-x | bfd/doc/awkscan | 12 | ||||
| -rwxr-xr-x | bfd/doc/awkscan-ip | 8 | ||||
| -rwxr-xr-x | bfd/doc/awkscan-p | 8 | ||||
| -rw-r--r-- | bfd/doc/bfd.texinfo | 430 | ||||
| -rwxr-xr-x | bfd/doc/bfdinfo | 1281 | ||||
| -rwxr-xr-x | bfd/doc/blins-p | 8 | ||||
| -rwxr-xr-x | bfd/doc/exfil1-p | 5 | ||||
| -rwxr-xr-x | bfd/doc/exfil3-p | 16 | ||||
| -rwxr-xr-x | bfd/doc/exfilter | 14 | ||||
| -rwxr-xr-x | bfd/doc/exfilter-p | 12 | ||||
| -rwxr-xr-x | bfd/doc/exfiltst | 8 | ||||
| -rwxr-xr-x | bfd/doc/exmerge | 4 | ||||
| -rwxr-xr-x | bfd/doc/intobfd | 11 | ||||
| -rwxr-xr-x | bfd/doc/mergecom-p | 5 | ||||
| -rwxr-xr-x | bfd/doc/movecom-p | 8 | ||||
| -rwxr-xr-x | bfd/doc/scanit | 25 | ||||
| -rwxr-xr-x | bfd/doc/scanph | 26 | ||||
| -rwxr-xr-x | bfd/doc/sedscript | 85 | ||||
| -rwxr-xr-x | bfd/doc/sedscript-p | 63 | ||||
| -rwxr-xr-x | bfd/doc/startcom-p | 12 | ||||
| -rwxr-xr-x | bfd/doc/tolibbfd | 4 | ||||
| -rwxr-xr-x | bfd/doc/tolibcoff | 1 | ||||
| -rwxr-xr-x | bfd/doc/unPROTO | 18 |
24 files changed, 2120 insertions, 0 deletions
diff --git a/bfd/doc/Makefile b/bfd/doc/Makefile new file mode 100755 index 0000000..3cb3f47 --- /dev/null +++ b/bfd/doc/Makefile @@ -0,0 +1,56 @@ +.SUFFIXES: .texi .o .c .h .p .ip +VPATH=.. +.c.texi: + scanit $< $@ + +.h.texi: + scanit $< $@ + +.c.p: + scanph $< $@ + +.h.p: + scanph $< $@ + +.c.ip: + scanph -i $< $@ + + +DOCFILES = syms.texi bfd.texi cache.texi \ + format.texi section.texi archive.texi \ + core.texi libbfd.texi archures.texi \ + reloc.texi opncls.texi targets.texi \ + aoutx.texi coffcode.texi cache.texi + +PROTOS = opncls.p archures.p libbfd.p \ + section.p syms.p bfd.p \ + archive.p reloc.p targets.p \ + format.p coffcode.p core.p + +IPROTOS = cache.ip libbfd.ip reloc.ip + +docs: $(DOCFILES) + +protos: $(PROTOS) $(IPROTOS) + sed -f intobfd bfd-in.h > bfd.h + sed -f tolibbfd libbfd-in.h > libbfd.h + sed -f tolibcoff libcoff-in.h > libcoff.h + + + +clean: + rm -f $(PROTOS) *.p *.ip *.h bfd.?? $(DOCFILES) bfd.dvi bfd.ps *~* *# bfd.??? + +bfd.info: $(DOCFILES) bfd.texinfo + makeinfo +no-validate bfd.texinfo + +bfd.dvi: $(DOCFILES) bfd.texinfo + tex bfd.texinfo + texindex bfd.?? + tex bfd.texinfo + +bfd.ps: bfd.dvi + dvips bfd -o + +quickdoc: $(DSRC) docs + tex bfd.texinfo diff --git a/bfd/doc/awkscan b/bfd/doc/awkscan new file mode 100755 index 0000000..69b0cea --- /dev/null +++ b/bfd/doc/awkscan @@ -0,0 +1,12 @@ +# NOTE: BEGIN pattern gives errors if other than 1st line; +# END ditto if other than last. +BEGIN { print "@c ------------------------------START TEXT FROM " FILENAME } +# +# Keep /*doc* blocks (terminated by either */ or *-*/) +/^\/\*doc\*/,/^\*\/|^\*-\*\// +# +# Also keep two kinds of /*proto blocks +/^\/\*proto\*/,/^\*\/|^\*-\*\// +/^\/\*proto-internal\*/,/^\*\/|^\*-\*\// +# +END { print "@c ------------------------------END TEXT FROM " FILENAME } diff --git a/bfd/doc/awkscan-ip b/bfd/doc/awkscan-ip new file mode 100755 index 0000000..73bd61f --- /dev/null +++ b/bfd/doc/awkscan-ip @@ -0,0 +1,8 @@ +# Awk filter, 1st filter for BFD internal prototype file extraction +# +# keep /*proto-internal blocks +/^\/\*proto-internal\*/,/^\*\/|^\*-\*\// +# +# Apparent bug in sed can discard last line in some situations; therefore +# make last line harmless. +END { print "\n" } diff --git a/bfd/doc/awkscan-p b/bfd/doc/awkscan-p new file mode 100755 index 0000000..c7fe79f --- /dev/null +++ b/bfd/doc/awkscan-p @@ -0,0 +1,8 @@ +# Awk filter, 1st filter for BFD prototype file extraction +# +# keep /*proto blocks +/^\/\*proto\*/,/^\*\/|^\*-\*\// +# +# Apparent bug in sed can discard last line in some situations; therefore +# make last line harmless. +END { print "\n" } diff --git a/bfd/doc/bfd.texinfo b/bfd/doc/bfd.texinfo new file mode 100644 index 0000000..d8ce6f5 --- /dev/null +++ b/bfd/doc/bfd.texinfo @@ -0,0 +1,430 @@ +\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 + + diff --git a/bfd/doc/bfdinfo b/bfd/doc/bfdinfo new file mode 100755 index 0000000..5bb06ff --- /dev/null +++ b/bfd/doc/bfdinfo @@ -0,0 +1,1281 @@ +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. + + +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:: + + +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. + + +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. + + +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. + + +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. + + +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). + + +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 + + +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. + + +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:: + + +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. + + +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 + + +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 ; + + +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); + + +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:: + + +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. + + +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. + + +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; + + +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 + + +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); + + +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 diff --git a/bfd/doc/blins-p b/bfd/doc/blins-p new file mode 100755 index 0000000..858dcd7 --- /dev/null +++ b/bfd/doc/blins-p @@ -0,0 +1,8 @@ +# sed script for BFD header files +# Merge adjacent blank lines. Loop til no change. +:blin +/^$/,/^ *[^ ]*.*$/{ +/^$/N +s/^ *\n *$// +} +t blin diff --git a/bfd/doc/exfil1-p b/bfd/doc/exfil1-p new file mode 100755 index 0000000..a57fc95 --- /dev/null +++ b/bfd/doc/exfil1-p @@ -0,0 +1,5 @@ +# +# Locate and coalesce adjacent comments +/\*\/$/N +s/\*\/\n\/\*/\ +/ diff --git a/bfd/doc/exfil3-p b/bfd/doc/exfil3-p new file mode 100755 index 0000000..c557a16 --- /dev/null +++ b/bfd/doc/exfil3-p @@ -0,0 +1,16 @@ +# blank-line activity: +# Merge adjacent blank lines. Loop til no change. +:blin +/^$/,/^ *[^ ]*.*$/{ +/^$/N +s/^ *\n *$// +} +t blin +# +/^$/,/^ *[^ ]*.*$/{ +/^$/N +# Transpose <blank line> <end comment> +/^ *\n\*\/$/c\ +*\/\ + +} diff --git a/bfd/doc/exfilter b/bfd/doc/exfilter new file mode 100755 index 0000000..7551607 --- /dev/null +++ b/bfd/doc/exfilter @@ -0,0 +1,14 @@ +# SED script for preprocessing embedded doc from source (S. Chamberlain markup) +# Final pass; cleanup work is done here. +# +# Within examples, make '{' and '}' printable: +/^@lisp$/,/^@end lisp$/s/{/@{/ +/^@lisp$/,/^@end lisp$/s/}/@}/ +/^@example$/,/^@end example$/s/{/@{/ +/^@example$/,/^@end example$/s/}/@}/ +# +# Delete empty @findex and @subsubsection entries (resulting from *proto* +# with no further text on same line, in middle pass) +/^@findex $/d +/^@subsubsection @code{}/d +# diff --git a/bfd/doc/exfilter-p b/bfd/doc/exfilter-p new file mode 100755 index 0000000..27a1d05 --- /dev/null +++ b/bfd/doc/exfilter-p @@ -0,0 +1,12 @@ +# SED script for preprocessing embedded headers from C source comments +# (S. Chamberlain markup) +# beginning of many passes of cleanup work +# +# Delete empty comment blocks +/^\/\*$/N +/^\/\*\n\*\/ *$/d +# +# Locate and coalesce adjacent comments +/\*\/$/N +s/\*\/\n\/\*/\ +/ diff --git a/bfd/doc/exfiltst b/bfd/doc/exfiltst new file mode 100755 index 0000000..18bab5a --- /dev/null +++ b/bfd/doc/exfiltst @@ -0,0 +1,8 @@ +# Merge adjacent blank lines. Loop til no change. +:blin +/^$/,/^ *[^ ]*.*$/{ +/^$/N +s/^ *\n *$// +} +t blin + diff --git a/bfd/doc/exmerge b/bfd/doc/exmerge new file mode 100755 index 0000000..dafa424 --- /dev/null +++ b/bfd/doc/exmerge @@ -0,0 +1,4 @@ +# SED script for preprocessing embedded doc from source (S. Chamberlain markup) +# Locate and coalesce adjacent @example blocks +/^@end example/N +/^@end example\n@example$/d diff --git a/bfd/doc/intobfd b/bfd/doc/intobfd new file mode 100755 index 0000000..b256f4b --- /dev/null +++ b/bfd/doc/intobfd @@ -0,0 +1,11 @@ +/\/\*:archive.c\*\//r archive.p +/\/\*:archures.c\*\//r archures.p +/\/\*:bfd.c\*\//r bfd.p +/\/\*:core.c\*\//r core.p +/\/\*:format.c\*\//r format.p +/\/\*:libbfd.c\*\//r libbfd.p +/\/\*:opncls.c\*\//r opncls.p +/\/\*:reloc.c\*\//r reloc.p +/\/\*:section.c\*\//r section.p +/\/\*:syms.c\*\//r syms.p +/\/\*:targets.c\*\//r targets.p diff --git a/bfd/doc/mergecom-p b/bfd/doc/mergecom-p new file mode 100755 index 0000000..456478b --- /dev/null +++ b/bfd/doc/mergecom-p @@ -0,0 +1,5 @@ +# SED script for preprocessing embedded headers from C source comments +# Locate and coalesce adjacent comments +/\*\/$/N +s/\*\/\n\/\*/\ +/ diff --git a/bfd/doc/movecom-p b/bfd/doc/movecom-p new file mode 100755 index 0000000..7ed04c7 --- /dev/null +++ b/bfd/doc/movecom-p @@ -0,0 +1,8 @@ +# sed script for BFD header files: +# Transpose <blank line> <end comment> +/^$/,/^ *[^ ]*.*$/{ +/^$/N +/^ *\n\*\/$/c\ +*\/\ + +} diff --git a/bfd/doc/scanit b/bfd/doc/scanit new file mode 100755 index 0000000..4271baf --- /dev/null +++ b/bfd/doc/scanit @@ -0,0 +1,25 @@ +#!/bin/sh +# Script to coordinate parsing of S. Chamberlain source-embedded +# documentation markup language. + +# Four passes: +# 1) awk discards lines not intended for docn, and marks blocks of +# text with comments identifying source file; +# 2) first sed pass interprets Chamberlain markup; +# 3) second sed pass does cleanup that involves merging lines +# 4) third sed pass does remaining cleans up---making {} +# printable within examples, and eliminating empty index entries and +# headings. +#Third and second sed passes are separate because order of execution is hard +#to control otherwise, making one or another of the things involving @example +#inoperative. + +base=`echo $1 | cut -d '.' -f 1` +out=`echo $2 | cut -d '.' -f 1` + +awk -f awkscan $1 | \ +sed -f sedscript | \ +sed -f unPROTO | \ +sed -f exmerge | \ +sed -f exfilter >$out.texi + diff --git a/bfd/doc/scanph b/bfd/doc/scanph new file mode 100755 index 0000000..4f36d68 --- /dev/null +++ b/bfd/doc/scanph @@ -0,0 +1,26 @@ +#!/bin/sh +# Script to coordinate parsing of S. Chamberlain source-embedded +# header-file markup language. + +# '-i' option means use *proto-internal* segments, else just *proto* +SFX=p +if [ $1 = "-i" ]; then + SFX=ip + shift +fi + +base=`echo $1 | cut -d '.' -f 1` +out=`echo $2 | cut -d '.' -f 1` + +# passes: +# 1) awk discards lines not intended for header, and marks blocks of +# text with comments identifying source file; +# 2) first sed pass interprets Chamberlain markup; +# 3) further sed passes clean up---merging adjacent comments etc. + +awk -f awkscan-$SFX $1 |\ +sed -f sedscript-p |\ +sed -f mergecom-p |\ +sed -f startcom-p |\ +sed -f blins-p |\ +sed -f movecom-p >$out.$SFX diff --git a/bfd/doc/sedscript b/bfd/doc/sedscript new file mode 100755 index 0000000..e8e225d --- /dev/null +++ b/bfd/doc/sedscript @@ -0,0 +1,85 @@ +# SED script for preprocessing embedded doc from source (S. Chamberlain markup) +# middle pass; most of the work is done here. +# +# First, get rid of /*doc* markers; they've done their job in the first pass. +/^\/\*doc\*/d +# +# /*proto* markers may be optionally followed by a *i-style subsubsec, findex +# entry. This will generate empty @findex and @subsubsection entries if +# the *proto* is on a line by itself; third pass removes them. +/^\/\*proto\*/s/^\/\*proto\* *\(.*\)$/@findex \1\ +@subsubsection @code{\1}/ +# +# /*proto-internal* is just like /*proto* from doc point of view. +/^\/\*proto-internal\*/s/^\/\*proto-internal\* *\(.*\)$/@findex \1\ +@subsubsection @code{\1}/ +# +# *i at beginning of line: rest of line is both a subsubsection heading +# and an entry in function index. +/^\*i/s/^\*i *\(.*\)$/@findex \1\ +@subsubsection @code{\1}/ +# +# Two alternative docn block ends, '*/' and '*-*/' on lines by themselves; +# replace by blank lines (for texinfo source readability). +/^\*\/$/c\ + +/^\*-\*\/$/c\ + +# {* and *} are standins for comment markers (originally embedded in .c +# comments)---turn into real comment markers: +s/{\*/\/\*/ +s/\*}/\*\// +# +# '*+++' and '*---' span a block of text that includes both example lines +# (marked by leading '$') and explanatory text (to be italicized). +# Italicize lines lacking '$': +/\*\+\+\+/,/\*---/s/^\([^$].*\)$/@i{\1}/ +# +# We don't need *+++ and *--- markers any more; kill them (trailing marker +# becomes blank line for readability) +/\*\+\+\+/d +/\*---/c\ + +# Any line beginning with '$' is made an example line; third pass later +# coalesces adjacent example blocks. *DO NOT* introduce extra space after +# @end example, so we can spot adjacent ones in third pass. +/^\$/i\ +@example +/^\$/a\ +@end example +# +# In any example line, turn '{' and '}' into '@{' and '@}' +###/^\$/s/{/@{/g +###/^\$/s/}/@}/g +# +# Now delete the '$' markers themselves: +/^\$/s/\$// +# +# *+ and *- delimit large examples to be enclosed in cartouches. +/^\*\+$/c\ +@lisp\ +@cartouche +/^\*-$/c\ +@end cartouche\ +@end lisp\ + +# '*;' introduces an example which may have a single line or multiple lines; +# it extends until the next semicolon (which is also printed). +# One-line case: (do this first; else second line address for multi-line case +# will include random text til we happen to end a line in a doc comment with +# a semicolon) +/^\*;.*;$/{ +s/^\*;/@example\ +/ +s/;$/;\ +@end example\ +/ +} +# Multi-line case: +/^\*;/,/.*;$/{ +s/^\*;/@example\ +/ +s/;$/;\ +@end example\ +/ +} diff --git a/bfd/doc/sedscript-p b/bfd/doc/sedscript-p new file mode 100755 index 0000000..1f24900 --- /dev/null +++ b/bfd/doc/sedscript-p @@ -0,0 +1,63 @@ +# SED script for preprocessing embedded headers from source +# (S. Chamberlain markup) +# middle pass; most of the work is done here. +# +# First, get rid of /*proto* markers; they've done their job in the first pass. +# (They remain comment-introducers) +/^\/\*proto\*/s/^\/\*proto\*/\/*/ +/^\/\*proto-internal\*/s/^\/\*proto-internal\*/\/*/ +# +# *-*/ is an alternative (older) comment-block end. Remap for uniformity: +s/^\*-\*\//\*\// +# +# {* and *} are standins for comment markers (originally embedded in .c +# comments)---turn into real comment markers: +s/{\*/\/\*/ +s/\*}/\*\// +# +# '*+++' and '*---' span a block of text that includes both header lines +# (marked by leading '$') and explanatory text (to be comments). +# No need to start comment at "*+++", or end it at "*---", since we're +# already in a *proto* comment block. Just delete. +/\*\+\+\+/d +/\*---/d +# +# Any line beginning with '$' is made a line of code in the header; +# stuff in between is comments, so *precede* each '$' line with +# END-comment, *follow* each '$' line with START-comment; third pass later +# eliminates empty comment blocks. +/^\$/i\ +*/ +/^\$/a\ +/* +# +# Now delete the '$' markers themselves: +/^\$/s/\$// +# +# *+ and *- delimit larger blocks of code, treated the same as '$' lines +/^\*\+$/c\ +*/ +/^\*-$/c\ +/* +# +# '*;' introduces code which may have a single line or multiple lines; +# it extends until the next semicolon (which is also printed). +# +# One-line case: (do this first; else second line address for multi-line case +# will include random text til we happen to end a line in a proto comment with +# a semicolon) +/^\*;.*;$/{ +s/^\*;/*\/\ +/ +s/;$/;\ +\/*\ +/ +} +# Multi-line case: +/^\*;/,/.*;$/{ +s/^\*;/*\/\ +/ +s/;$/;\ +\/*\ +/ +} diff --git a/bfd/doc/startcom-p b/bfd/doc/startcom-p new file mode 100755 index 0000000..0748fad --- /dev/null +++ b/bfd/doc/startcom-p @@ -0,0 +1,12 @@ +# sed script for preprocessing BFD header files +# <start comment> activity: +/^\/\*$/{ +N +# Delete empty comment blocks +/^\/\*\n\*\/ *$/d +# Transpose <start comment><blank line> +s/^\/\*\n *$/\ +\/*/ +# merge <start comment> on line by itself with following line +s/^\/\*\n\(.*\)/\/* \1/ +} diff --git a/bfd/doc/tolibbfd b/bfd/doc/tolibbfd new file mode 100755 index 0000000..ef9531e --- /dev/null +++ b/bfd/doc/tolibbfd @@ -0,0 +1,4 @@ +/---------------START FROM/,/---------------END FROM/d +/\/\*:libbfd.c\*\//r libbfd.ip +/\/\*:cache.c\*\//r cache.ip +/\/\*:reloc.c\*\//r reloc.ip diff --git a/bfd/doc/tolibcoff b/bfd/doc/tolibcoff new file mode 100755 index 0000000..548c8ba --- /dev/null +++ b/bfd/doc/tolibcoff @@ -0,0 +1 @@ +/\/\*:coffcode.h\*\//r coffcode.p diff --git a/bfd/doc/unPROTO b/bfd/doc/unPROTO new file mode 100755 index 0000000..a6f9520 --- /dev/null +++ b/bfd/doc/unPROTO @@ -0,0 +1,18 @@ +# +# The PROTO macro is a subterfuge to be compatible with both ANSI and K&R +# declaration syntax. It's not widely known, so for the docn just map the +# thing to ANSI declaration syntax. +# +# First, join up defns broken across multiple lines in source---but leave +# any linebreaks, to prettify our examples +:pbegn +/PROTO(.*, *$/N +s/\n/?/ +t pbegn +s/?/\ +/g +# Now actually do the PROTO interpretation. +# A PROTO invocation looks like +# PROTO( resulttype, function, (arglist)); +s/[ ]*PROTO(\(.*\),[\n ]*\(.*\),[\n ]*\((.*)\));/\1 \2\3;/ + |