aboutsummaryrefslogtreecommitdiff
path: root/bfd/doc
diff options
context:
space:
mode:
authorRichard Henderson <rth@redhat.com>1999-05-03 07:29:11 +0000
committerRichard Henderson <rth@redhat.com>1999-05-03 07:29:11 +0000
commit252b5132c753830d5fd56823373aed85f2a0db63 (patch)
tree1af963bfd8d3e55167b81def4207f175eaff3a56 /bfd/doc
downloadgdb-252b5132c753830d5fd56823373aed85f2a0db63.zip
gdb-252b5132c753830d5fd56823373aed85f2a0db63.tar.gz
gdb-252b5132c753830d5fd56823373aed85f2a0db63.tar.bz2
19990502 sourceware importbinu_ss_19990502
Diffstat (limited to 'bfd/doc')
-rw-r--r--bfd/doc/ChangeLog390
-rw-r--r--bfd/doc/Makefile.am250
-rw-r--r--bfd/doc/Makefile.in600
-rw-r--r--bfd/doc/bfd.texinfo348
-rw-r--r--bfd/doc/bfdint.texi1885
-rw-r--r--bfd/doc/bfdsumm.texi148
-rw-r--r--bfd/doc/chew.c1579
-rw-r--r--bfd/doc/doc.str158
-rw-r--r--bfd/doc/makefile.vms5
-rw-r--r--bfd/doc/proto.str135
10 files changed, 5498 insertions, 0 deletions
diff --git a/bfd/doc/ChangeLog b/bfd/doc/ChangeLog
new file mode 100644
index 0000000..9e8207a
--- /dev/null
+++ b/bfd/doc/ChangeLog
@@ -0,0 +1,390 @@
+Thu Feb 4 23:21:36 1999 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in: Rebuild with current autoconf/automake.
+
+Thu Jul 23 09:36:44 1998 Nick Clifton <nickc@cygnus.com>
+
+ * bfdint.texi (BFD ELF processor required): Add paragraph
+ describing the necessity to create "include/elf/CPU.h".
+
+Thu May 7 14:45:43 1998 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.am (chew.o): Add -I options for intl srcdir and
+ objdir.
+ * Makefile.in: Rebuild.
+
+Mon Apr 27 20:19:24 1998 Ian Lance Taylor <ian@cygnus.com>
+
+ * bfdint.texi: New file.
+ * Makefile.am (noinst_TEXINFOS): New variable.
+ * Makefile.in: Rebuild.
+
+Mon Apr 13 16:48:56 1998 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in: Rebuild.
+
+Mon Apr 6 14:06:55 1998 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.am (STAGESTUFF): Remove variable.
+ (CLEANFILES): Don't remove $(STAGESTUFF).
+ (DISTCLEANFILES, MAINTAINERCLEANFILES): New variables.
+ * Makefile.in: Rebuild.
+
+Fri Mar 27 16:25:25 1998 Ian Lance Taylor <ian@cygnus.com>
+
+ * chew.c (skip_white_and_starts): Remove unused declaration.
+ (skip_white_and_stars): Add casts to avoid warnings.
+ (skip_trailing_newlines, paramstuff, courierize): Likewise.
+ (bulletize, do_fancy_stuff, iscommand): Likewise.
+ (kill_bogus_lines, nextword, main): Likewise.
+ (manglecomments): Comment out.
+ (outputdots, kill_bogus_lines): Remove unused local variables.
+ (perform, compile): Likewise.
+ (courierize): Fully parenthesize expression.
+ (copy_past_newline): Declare return value.
+ (print): Change printf format string.
+ (main): Call usage for an unrecognized option.
+
+Fri Feb 13 14:37:14 1998 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.am (AUTOMAKE_OPTIONS): Define.
+ * Makefile.in: Rebuild.
+
+Mon Jan 26 15:38:36 1998 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
+
+ * doc.str (bodytext): Don't output @* at the end.
+ * chew.c (kill_bogus_lines): Make sure that a period at the
+ beginning is recognized.
+ (indent): Don't put indentation at the end.
+ (copy_past_newline): Expand tabs.
+ * Makefile.am (s-reloc, s-syms): Depend on doc.str.
+ * Makefile.in: Rebuild.
+
+Wed Oct 1 14:41:28 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.am (libbfd.h): Don't use cpu-h8300.c, cpu-i960.c, or
+ elfcode.h as input files; they don't contribute anything.
+ * Makefile.in: Rebuild.
+
+Fri Aug 15 04:55:15 1997 Doug Evans <dje@canuck.cygnus.com>
+
+ * Makefile.am (libbfd.h, libcoff.h): Invoke $(MKDOC) as ./$(MKDOC).
+ * Makefile.in: Rebuild.
+
+Fri Aug 1 12:59:58 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.am (CC_FOR_BUILD): Don't set explicitly.
+ * Makefile.in: Rebuild.
+
+Thu Jul 31 20:00:12 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.am: New file, based on old Makefile.in.
+ * Makefile.in: Now built with automake.
+
+Tue Jul 22 14:44:00 1997 Robert Hoehne <robert.hoehne@Mathematik.TU-Chemnitz.DE>
+
+ * Makefile.in: Change stamp-* files to s-* files. Use bfdt.texi
+ rather than bfd.texi.
+ (DOCFILES): Change bfd.texi to bfdt.texi.
+ * bfd.texinfo: Include bfdt.texi, not bfd.texi.
+
+Mon Jun 16 15:33:15 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in (CC, CFLAGS): Substitute from configure script.
+ From Jeff Makey <jeff@cts.com>.
+
+Tue Apr 15 12:37:41 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in (install-info): Use mkinstalldirs to build
+ $(infodir).
+
+Tue Apr 8 12:49:46 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in (install-info): Permit info files to be in srcdir.
+ (stamp-*): Add a stamp-X target for each X.texi target.
+ (*.texi): Just depend upon stamp-X.
+ (clean): Remove stamp-*.
+ (distclean): Depend upon mostlyclean. Remove stamp-*. Don't
+ remove $(DOCFILES).
+
+Mon Apr 7 15:23:26 1997 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in (distclean): Don't remove *.info files.
+
+Thu Feb 13 20:50:02 1997 Klaus Kaempf (kkaempf@progis.de)
+
+ * makefile.vms: New file.
+
+Tue Jun 18 18:32:28 1996 Ian Lance Taylor <ian@cygnus.com>
+
+ * chew.c (kill_bogus_lines): Reset sl when not at the start of a
+ line. From Uwe Ohse <uwe@tirka.gun.de>.
+
+Tue Jan 30 14:10:46 1996 Ian Lance Taylor <ian@cygnus.com>
+
+ From Ronald F. Guilmette <rfg@monkeys.com>:
+ * Makefile.in (libbfd.h): Depend upon proto.str.
+ (libcoff.h, bfd.h): Likewise.
+
+Fri Nov 3 14:46:48 1995 Fred Fish <fnf@cygnus.com>
+
+ * Makefile.in (SRCDOC, SRCPROT, core.texi, bfd.h): Use corefile.c,
+ renamed from core.c.
+
+Wed Nov 1 14:28:23 1995 Manfred Hollstein KS/EF4A 60/1F/110 #40283 <manfred@lts.sel.alcatel.de>
+
+ * chew.c: Include <ctype.h>.
+
+Fri Oct 6 16:23:34 1995 Ken Raeburn <raeburn@cygnus.com>
+
+ Mon Sep 25 22:49:32 1995 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
+
+ * Makefile.in (Makefile): Only remake this Makefile.
+
+Wed Oct 4 15:51:05 1995 Ken Raeburn <raeburn@cygnus.com>
+
+ * chew.c: Include <stdio.h>.
+
+Tue Sep 12 18:14:50 1995 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in (maintainer-clean): New target.
+
+Thu Aug 31 12:18:43 1995 Ian Lance Taylor <ian@cygnus.com>
+
+ * Makefile.in (bfd.h): Add additional #endif at end of bfd.h if
+ __cplusplus is defined.
+
+Tue Nov 29 16:13:34 1994 Doug Evans <dje@canuck.cygnus.com>
+
+ * chew.c (write_buffer): New argument `f', all callers changed.
+ (stdout, stderr, print, drop, idrop): New forth words.
+ * proto.str (COMMENT): New command.
+ * doc.str (COMMENT): Likewise.
+
+Mon Sep 12 11:44:17 1994 Ian Lance Taylor (ian@sanguine.cygnus.com)
+
+ * Makefile.in (DOCFILES): Remove ctor.texi.
+ (IPROTOS): Remove ctor.ip.
+ (SRCIPROT): Remove $(srcdir)/../ctor.c.
+ (ctor.texi): Remove target.
+ (libbfd.h): Remove dependency on $(srcdir)/../ctor.c. Remove
+ $(MKDOC) run on $(srcdir)/../ctor.c.
+ * bfd.texinfo (Constructors): Remove section.
+
+Fri Sep 2 13:33:44 1994 Ken Raeburn (raeburn@cujo.cygnus.com)
+
+ * chew.c: Include assert.h. Added prototypes for most functions.
+ Changed most uses of int to long. Do bounds checking on the
+ stacks. Added comment at the beginning documenting most of the
+ intrinsics. Lots of whitespace changes. Re-ordered some
+ functions.
+ (die, check_range, icheck_range): New functions.
+ (strip_trailing_newlines, print_stack_level): New functions.
+ (translatecomments): Don't insert tab before "/*".
+ (iscommand): Minimum command length is now 4.
+ (nextword): Handle some \-sequences.
+ (push_addr): Deleted.
+ (main): Add new intrinsics strip_trailing_newlines and
+ print_stack_level. Complain at end if stack contains more than
+ one element, or less.
+ (remchar): Make sure the string is not empty before chopping off a
+ character.
+
+ * doc.str, proto.str: Handle new commands SENUM, ENUM, ENUMX,
+ ENUMEQ, ENUMEQX, ENUMDOC.
+
+Wed Jan 12 18:37:12 1994 Ian Lance Taylor (ian@tweedledumb.cygnus.com)
+
+ * bfd.texinfo: Added Linker Functions node.
+ * doc/Makefile.in (DOCFILES): Added linker.texi.
+ (SRCDOC): Added linker.c.
+ (linker.texi): New target.
+
+Tue Jan 4 10:52:56 1994 Ian Lance Taylor (ian@tweedledumb.cygnus.com)
+
+ * chew.c: Don't rely on a correct declaration of exit.
+ (chew_exit): New function which just calls exit.
+ (main): Use it.
+
+Mon Jan 3 11:40:40 1994 Ian Lance Taylor (ian@tweedledumb.cygnus.com)
+
+ * bfd.texinfo: Added Hash Tables node.
+ * Makefile.in (DOCFILES): Added hash.texi.
+ (SRCDOC): Added hash.c.
+ (hash.texi): New target.
+
+Thu Dec 30 16:57:04 1993 Ken Raeburn (raeburn@cujo.cygnus.com)
+
+ * Makefile.in: Delete all references to seclet.c, since it's just
+ been deleted. Don't mention hash.c, linker.c, or genlink.h yet,
+ since they don't contain documentation yet (hint, hint!).
+
+Fri Nov 5 10:58:53 1993 David J. Mackenzie (djm@thepub.cygnus.com)
+
+ * bfd.texinfo: Small cleanups.
+
+Fri Nov 19 03:46:11 1993 Ken Raeburn (raeburn@cambridge.cygnus.com)
+
+ * Makefile.in (archures.texi): Depends on $(MKDOC).
+
+Tue Aug 10 14:22:39 1993 Ken Raeburn (raeburn@cambridge.cygnus.com)
+
+ * bfd.texinfo (BFD back end): Don't include elfcode.texi, since
+ it's empty now and that triggers a makeinfo bug.
+
+Mon Aug 9 16:27:30 1993 Ken Raeburn (raeburn@cambridge.cygnus.com)
+
+ * bfd.texinfo (BFD back end): New section on ELF, includes
+ elf.texi and elfcode.texi.
+ * Makefile.in (DOCFILES): Include elf.texi, elfcode.texi.
+ (SRCDOC): Include elfcode.h, elf.c.
+ (elf.texi, elfcode.texi): New intermediate targets.
+
+Thu Jun 24 13:48:13 1993 David J. Mackenzie (djm@thepub.cygnus.com)
+
+ * Makefile.in (.c.o, chew.o): Put CFLAGS last.
+ * bfdsumm.texi: New file, broken out of bfd.texinfo, to share
+ with ld.texinfo.
+
+Mon Jun 14 12:07:07 1993 david d `zoo' zuhn (zoo at rtl.cygnus.com)
+
+ * Makefile.in (install-info): remove parentdir cruft,
+
+Wed Jun 9 16:00:32 1993 Jim Kingdon (kingdon@cygnus.com)
+
+ * Makefile.in (mostlyclean): Remove chew.o.
+
+Tue May 25 14:46:58 1993 Ken Raeburn (raeburn@cambridge.cygnus.com)
+
+ * Makefile.in (libbfd.h): Use elfcode.h, not elf32.c.
+
+Mon May 24 15:50:07 1993 Ken Raeburn (raeburn@cygnus.com)
+
+ * chew.c (compile): Add a couple of missing casts.
+
+Wed May 12 14:45:14 1993 Ian Lance Taylor (ian@cygnus.com)
+
+ * Makefile.in (CC_FOR_BUILD): New variable, define to be $(CC).
+ (chew.o, $(MKDOC)): Build using CC_FOR_BUILD rather than CC, since
+ it must run on the build machine.
+
+Tue Apr 6 22:38:10 1993 John Gilmore (gnu@cygnus.com)
+
+ * Makefile.in (chew): Don't compile from .c to executable in a
+ single step; it puts a temporary .o filename into the executable,
+ which makes multi-stage comparisons fail. Compile chew.c to
+ chew.o, and link that, which makes identical executables every time.
+
+Wed Mar 24 17:26:29 1993 david d `zoo' zuhn (zoo at poseidon.cygnus.com)
+
+ * Makefile.in: fix typo (bfd.texinfo not bfd.texino)
+
+Fri Mar 19 01:13:00 1993 Ken Raeburn (raeburn@kr-pc.cygnus.com)
+
+ * bfd.texinfo: Since BFD version number has been bumped, do same
+ to "version number" on title page, and elsewhere. Should be
+ fixed to extract real version number.
+
+Tue Mar 16 12:15:13 1993 Per Bothner (bothner@rtl.cygnus.com)
+
+ * Makefile.in: Add *clean rules.
+
+Mon Jan 11 18:43:56 1993 Ian Lance Taylor (ian@tweedledumb.cygnus.com)
+
+ * Makefile.in (libbfd.h): Removed duplicate init.c and libbfd.c.
+ Added seclet.c.
+ (bfd.h): Added dependency on bfd.c and seclet.c. Added seclet.c
+ to build.
+
+Thu Dec 17 19:35:43 1992 david d `zoo' zuhn (zoo at cirdan.cygnus.com)
+
+ * Makefile.in: added dvi target, define and use $(TEXI2DVI)
+
+Thu Dec 3 17:42:48 1992 Ken Raeburn (raeburn@cambridge.cygnus.com)
+
+ * Makefile.in (TEXIDIR): New variable.
+ (bfd.dvi): Look for bfd.texinfo in $(srcdir). Generate index.
+
+ * bfd.texinfo: Minor doc fixes.
+
+Thu Nov 5 03:13:55 1992 John Gilmore (gnu@cygnus.com)
+
+ Cleanup: Replace all uses of EXFUN in the BFD sources, with PARAMS.
+
+ * doc/chew.c (exfunstuff): Eliminate.
+ (paramstuff): Replace exfunstuff with function to generate PARAMS.
+ * doc/proto.str: Use paramstuff rather than exfunstuff.
+
+Mon Aug 17 12:40:32 1992 Steve Chamberlain (sac@thepub.cygnus.com)
+
+ * chew.c: various patches provided by Howard Chu.
+
+Fri Jun 19 18:59:54 1992 John Gilmore (gnu at cygnus.com)
+
+ * Makefile.in (libbfd.h): Add elf.c as a source of prototypes.
+
+Mon May 11 18:55:59 1992 John Gilmore (gnu at cygnus.com)
+
+ * chew.c: exit() should be declared by config files, not by
+ portable source code. Its type could be int or void function.
+
+Mon May 4 13:45:57 1992 K. Richard Pixley (rich@rtl.cygnus.com)
+
+ * Makefile.in: another CFLAGS correction.
+
+Tue Apr 28 10:21:32 1992 K. Richard Pixley (rich@rtl.cygnus.com)
+
+ * Makefile.in: Do the CFLAGS thing.
+
+Fri Apr 10 22:34:52 1992 Fred Fish (fnf@cygnus.com)
+
+ * Makefile.in (MINUS_G): Add macro and default to -g.
+
+Fri Mar 6 18:53:18 1992 Steve Chamberlain (sac@thepub.cygnus.com)
+
+ * chew.c: now has -w switch turn on warnings
+
+Wed Feb 26 18:04:40 1992 K. Richard Pixley (rich@cygnus.com)
+
+ * Makefile.in, configure.in: removed traces of namesubdir,
+ -subdirs, $(subdir), $(unsubdir), some rcs triggers. Forced
+ copyrights to '92, changed some from Cygnus to FSF.
+
+Tue Dec 10 22:11:05 1991 K. Richard Pixley (rich at rtl.cygnus.com)
+
+ * Makefile.in: build chew into the current directory. Complete
+ the MKDOC macro transition.
+
+Tue Dec 10 08:26:28 1991 Steve Chamberlain (sac at rtl.cygnus.com)
+
+ * chew.c: don't core dump when can't open file
+ * Makefile.in: get proto.str from the right place when built in
+ odd directories
+
+Tue Dec 10 04:07:25 1991 K. Richard Pixley (rich at rtl.cygnus.com)
+
+ * Makefile.in: infodir belongs in datadir.
+
+Sat Dec 7 17:01:23 1991 Steve Chamberlain (sac at rtl.cygnus.com)
+
+ * chew.c: Much modified
+ * proto.str, doc.str: New files for extracting to product
+ prototypes and documents respectively.
+
+
+Fri Dec 6 22:57:12 1991 K. Richard Pixley (rich at rtl.cygnus.com)
+
+ * Makefile.in: added standards.text support, host/site/target
+ inclusion hooks, install using INSTALL_DATA rather than cp,
+ don't echo on install.
+
+Thu Dec 5 22:46:17 1991 K. Richard Pixley (rich at rtl.cygnus.com)
+
+ * Makefile.in: idestdir and ddestdir go away. Added copyrights
+ and shift gpl to v2. Added ChangeLog if it didn't exist. docdir
+ and mandir now keyed off datadir by default.
+
+
+Local Variables:
+version-control: never
+End:
diff --git a/bfd/doc/Makefile.am b/bfd/doc/Makefile.am
new file mode 100644
index 0000000..0d5268e
--- /dev/null
+++ b/bfd/doc/Makefile.am
@@ -0,0 +1,250 @@
+## Process this file with automake to generate Makefile.in
+
+AUTOMAKE_OPTIONS = cygnus
+
+DOCFILES = aoutx.texi archive.texi archures.texi \
+ bfdt.texi cache.texi coffcode.texi \
+ core.texi elf.texi elfcode.texi format.texi libbfd.texi \
+ opncls.texi reloc.texi section.texi \
+ syms.texi targets.texi init.texi hash.texi linker.texi
+
+PROTOS = archive.p archures.p bfd.p \
+ core.p format.p \
+ libbfd.p opncls.p reloc.p \
+ section.p syms.p targets.p \
+ format.p core.p init.p
+
+IPROTOS = cache.ip libbfd.ip reloc.ip init.ip archures.ip coffcode.ip
+
+# SRCDOC, SRCPROT, SRCIPROT only used to sidestep Sun Make bug in interaction
+# between VPATH and suffix rules. If you use GNU Make, perhaps other Makes,
+# you don't need these three:
+SRCDOC = $(srcdir)/../aoutx.h $(srcdir)/../archive.c \
+ $(srcdir)/../archures.c $(srcdir)/../bfd.c \
+ $(srcdir)/../cache.c $(srcdir)/../coffcode.h \
+ $(srcdir)/../corefile.c $(srcdir)/../elf.c \
+ $(srcdir)/../elfcode.h $(srcdir)/../format.c \
+ $(srcdir)/../libbfd.c $(srcdir)/../opncls.c \
+ $(srcdir)/../reloc.c $(srcdir)/../section.c \
+ $(srcdir)/../syms.c $(srcdir)/../targets.c \
+ $(srcdir)/../hash.c $(srcdir)/../linker.c
+
+SRCPROT = $(srcdir)/../archive.c $(srcdir)/../archures.c \
+ $(srcdir)/../bfd.c $(srcdir)/../coffcode.h $(srcdir)/../corefile.c \
+ $(srcdir)/../format.c $(srcdir)/../libbfd.c \
+ $(srcdir)/../opncls.c $(srcdir)/../reloc.c \
+ $(srcdir)/../section.c $(srcdir)/../syms.c \
+ $(srcdir)/../targets.c $(srcdir)/../init.c
+
+SRCIPROT = $(srcdir)/../cache.c $(srcdir)/../libbfd.c \
+ $(srcdir)/../reloc.c $(srcdir)/../cpu-h8300.c \
+ $(srcdir)/../cpu-i960.c $(srcdir)/../archures.c \
+ $(srcdir)/../init.c
+
+TEXIDIR = $(srcdir)/../../texinfo/fsf
+
+info_TEXINFOS = bfd.texinfo
+
+MKDOC = chew$(EXEEXT_FOR_BUILD)
+
+$(MKDOC): chew.o
+ $(CC_FOR_BUILD) -o $(MKDOC) chew.o $(LOADLIBES) $(LDFLAGS)
+
+chew.o: chew.c
+ $(CC_FOR_BUILD) -c -I.. -I$(srcdir)/.. -I$(srcdir)/../../include -I$(srcdir)/../../intl -I../../intl $(H_CFLAGS) $(CFLAGS) $(srcdir)/chew.c
+
+protos: libbfd.h libcoff.h bfd.h
+
+bfd.info bfd.dvi: $(DOCFILES) bfdsumm.texi bfd.texinfo
+
+# We can't replace these rules with an implicit rule, because
+# makes without VPATH support couldn't find the .h files in `..'.
+
+# We use s-XXX targets so that we can distribute the info files,
+# and permit people to rebuild them, without requiring the makeinfo
+# program. If somebody tries to rebuild info, but none of the .texi
+# files have changed, then this Makefile will build chew, and will
+# build all of the stamp files, but will not actually have to rebuild
+# bfd.info.
+
+s-aoutx: $(MKDOC) $(srcdir)/../aoutx.h $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../aoutx.h >aoutx.tmp
+ $(srcdir)/../../move-if-change aoutx.tmp aoutx.texi
+ touch s-aoutx
+aoutx.texi: s-aoutx
+
+s-archive: $(MKDOC) $(srcdir)/../archive.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../archive.c >archive.tmp
+ $(srcdir)/../../move-if-change archive.tmp archive.texi
+ touch s-archive
+archive.texi: s-archive
+
+s-archures: $(MKDOC) $(srcdir)/../archures.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../archures.c >archures.tmp
+ $(srcdir)/../../move-if-change archures.tmp archures.texi
+ touch s-archures
+archures.texi: s-archures
+
+# We use bfdt.texi, rather than bfd.texi, to avoid conflicting with
+# bfd.texinfo on an 8.3 filesystem.
+s-bfd: $(MKDOC) $(srcdir)/../bfd.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../bfd.c >bfd.tmp
+ $(srcdir)/../../move-if-change bfd.tmp bfdt.texi
+ touch s-bfd
+bfdt.texi: s-bfd
+
+s-cache: $(MKDOC) $(srcdir)/../cache.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../cache.c >cache.tmp
+ $(srcdir)/../../move-if-change cache.tmp cache.texi
+ touch s-cache
+cache.texi: s-cache
+
+s-coffcode: $(MKDOC) $(srcdir)/../coffcode.h $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../coffcode.h >coffcode.tmp
+ $(srcdir)/../../move-if-change coffcode.tmp coffcode.texi
+ touch s-coffcode
+coffcode.texi: s-coffcode
+
+s-core: $(MKDOC) $(srcdir)/../corefile.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../corefile.c >core.tmp
+ $(srcdir)/../../move-if-change core.tmp core.texi
+ touch s-core
+core.texi: s-core
+
+s-elf: $(MKDOC) $(srcdir)/../elf.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../elf.c >elf.tmp
+ $(srcdir)/../../move-if-change elf.tmp elf.texi
+ touch s-elf
+elf.texi: s-elf
+
+s-elfcode: $(MKDOC) $(srcdir)/../elfcode.h $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../elfcode.h >elfcode.tmp
+ $(srcdir)/../../move-if-change elfcode.tmp elfcode.texi
+ touch s-elfcode
+elfcode.texi: s-elfcode
+
+s-format: $(MKDOC) $(srcdir)/../format.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../format.c >format.tmp
+ $(srcdir)/../../move-if-change format.tmp format.texi
+ touch s-format
+format.texi: s-format
+
+s-libbfd: $(MKDOC) $(srcdir)/../libbfd.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../libbfd.c >libbfd.tmp
+ $(srcdir)/../../move-if-change libbfd.tmp libbfd.texi
+ touch s-libbfd
+libbfd.texi: s-libbfd
+
+s-opncls: $(MKDOC) $(srcdir)/../opncls.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../opncls.c >opncls.tmp
+ $(srcdir)/../../move-if-change opncls.tmp opncls.texi
+ touch s-opncls
+opncls.texi: s-opncls
+
+s-reloc: $(MKDOC) $(srcdir)/../reloc.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../reloc.c >reloc.tmp
+ $(srcdir)/../../move-if-change reloc.tmp reloc.texi
+ touch s-reloc
+reloc.texi: s-reloc
+
+s-section: $(MKDOC) $(srcdir)/../section.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../section.c >section.tmp
+ $(srcdir)/../../move-if-change section.tmp section.texi
+ touch s-section
+section.texi: s-section
+
+s-syms: $(MKDOC) $(srcdir)/../syms.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../syms.c >syms.tmp
+ $(srcdir)/../../move-if-change syms.tmp syms.texi
+ touch s-syms
+syms.texi: s-syms
+
+s-targets: $(MKDOC) $(srcdir)/../targets.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../targets.c >targets.tmp
+ $(srcdir)/../../move-if-change targets.tmp targets.texi
+ touch s-targets
+targets.texi: s-targets
+
+s-init: $(MKDOC) $(srcdir)/../init.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../init.c >init.tmp
+ $(srcdir)/../../move-if-change init.tmp init.texi
+ touch s-init
+init.texi: s-init
+
+s-hash: $(MKDOC) $(srcdir)/../hash.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../hash.c >hash.tmp
+ $(srcdir)/../../move-if-change hash.tmp hash.texi
+ touch s-hash
+hash.texi: s-hash
+
+s-linker: $(MKDOC) $(srcdir)/../linker.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../linker.c >linker.tmp
+ $(srcdir)/../../move-if-change linker.tmp linker.texi
+ touch s-linker
+linker.texi: s-linker
+
+libbfd.h: $(srcdir)/../libbfd-in.h \
+ $(srcdir)/../init.c \
+ $(srcdir)/../libbfd.c \
+ $(srcdir)/../cache.c \
+ $(srcdir)/../reloc.c \
+ $(srcdir)/../archures.c \
+ $(srcdir)/proto.str \
+ $(MKDOC)
+ cat $(srcdir)/../libbfd-in.h >libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../init.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../libbfd.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../cache.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../reloc.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../archures.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../elf.c >>libbfd.h
+
+libcoff.h: $(srcdir)/../libcoff-in.h \
+ $(srcdir)/../coffcode.h \
+ $(srcdir)/proto.str \
+ $(MKDOC)
+ cat $(srcdir)/../libcoff-in.h >libcoff.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../coffcode.h >>libcoff.h
+
+bfd.h: $(srcdir)/../bfd-in.h \
+ $(srcdir)/../init.c \
+ $(srcdir)/../opncls.c \
+ $(srcdir)/../libbfd.c \
+ $(srcdir)/../section.c \
+ $(srcdir)/../archures.c \
+ $(srcdir)/../reloc.c \
+ $(srcdir)/../syms.c \
+ $(srcdir)/../bfd.c \
+ $(srcdir)/../archive.c \
+ $(srcdir)/../corefile.c \
+ $(srcdir)/../targets.c \
+ $(srcdir)/../format.c \
+ $(srcdir)/proto.str \
+ $(MKDOC)
+ cat $(srcdir)/../bfd-in.h >bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../init.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../opncls.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../libbfd.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../section.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../archures.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../reloc.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../syms.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../bfd.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../archive.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../corefile.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../targets.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../format.c >>bfd.h
+ echo "#ifdef __cplusplus" >>bfd.h
+ echo "}" >>bfd.h
+ echo "#endif" >>bfd.h
+ echo "#endif" >>bfd.h
+
+noinst_TEXINFOS = bfdint.texi
+
+MOSTLYCLEANFILES = $(MKDOC) *.o
+
+CLEANFILES = s-* *.p *.ip
+
+DISTCLEANFILES = bfd.?? bfd.??? bfd.h libbfd.h libcoff.h texput.log
+
+MAINTAINERCLEANFILES = $(DOCFILES)
diff --git a/bfd/doc/Makefile.in b/bfd/doc/Makefile.in
new file mode 100644
index 0000000..6295c10
--- /dev/null
+++ b/bfd/doc/Makefile.in
@@ -0,0 +1,600 @@
+# Makefile.in generated automatically by automake 1.4 from Makefile.am
+
+# Copyright (C) 1994, 1995-8, 1999 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+
+SHELL = @SHELL@
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+bindir = @bindir@
+sbindir = @sbindir@
+libexecdir = @libexecdir@
+datadir = @datadir@
+sysconfdir = @sysconfdir@
+sharedstatedir = @sharedstatedir@
+localstatedir = @localstatedir@
+libdir = @libdir@
+infodir = @infodir@
+mandir = @mandir@
+includedir = @includedir@
+oldincludedir = /usr/include
+
+DESTDIR =
+
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+
+top_builddir = ..
+
+ACLOCAL = @ACLOCAL@
+AUTOCONF = @AUTOCONF@
+AUTOMAKE = @AUTOMAKE@
+AUTOHEADER = @AUTOHEADER@
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS)
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+transform = @program_transform_name@
+
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_alias = @build_alias@
+build_triplet = @build@
+host_alias = @host_alias@
+host_triplet = @host@
+target_alias = @target_alias@
+target_triplet = @target@
+AR = @AR@
+AS = @AS@
+BFD_HOST_64BIT_LONG = @BFD_HOST_64BIT_LONG@
+BFD_HOST_64_BIT = @BFD_HOST_64_BIT@
+BFD_HOST_64_BIT_DEFINED = @BFD_HOST_64_BIT_DEFINED@
+BFD_HOST_U_64_BIT = @BFD_HOST_U_64_BIT@
+CATALOGS = @CATALOGS@
+CATOBJEXT = @CATOBJEXT@
+CC = @CC@
+CC_FOR_BUILD = @CC_FOR_BUILD@
+COREFILE = @COREFILE@
+COREFLAG = @COREFLAG@
+DATADIRNAME = @DATADIRNAME@
+DLLTOOL = @DLLTOOL@
+EXEEXT = @EXEEXT@
+EXEEXT_FOR_BUILD = @EXEEXT_FOR_BUILD@
+GMOFILES = @GMOFILES@
+GMSGFMT = @GMSGFMT@
+GT_NO = @GT_NO@
+GT_YES = @GT_YES@
+HDEFINES = @HDEFINES@
+INCLUDE_LOCALE_H = @INCLUDE_LOCALE_H@
+INSTOBJEXT = @INSTOBJEXT@
+INTLDEPS = @INTLDEPS@
+INTLLIBS = @INTLLIBS@
+INTLOBJS = @INTLOBJS@
+LD = @LD@
+LIBTOOL = @LIBTOOL@
+LN_S = @LN_S@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MKINSTALLDIRS = @MKINSTALLDIRS@
+MSGFMT = @MSGFMT@
+NM = @NM@
+PACKAGE = @PACKAGE@
+POFILES = @POFILES@
+POSUB = @POSUB@
+RANLIB = @RANLIB@
+TDEFINES = @TDEFINES@
+USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@
+USE_NLS = @USE_NLS@
+USE_SYMBOL_UNDERSCORE = @USE_SYMBOL_UNDERSCORE@
+VERSION = @VERSION@
+WIN32LDFLAGS = @WIN32LDFLAGS@
+WIN32LIBADD = @WIN32LIBADD@
+all_backends = @all_backends@
+bfd_backends = @bfd_backends@
+bfd_machines = @bfd_machines@
+l = @l@
+tdefaults = @tdefaults@
+wordsize = @wordsize@
+
+AUTOMAKE_OPTIONS = cygnus
+
+DOCFILES = aoutx.texi archive.texi archures.texi \
+ bfdt.texi cache.texi coffcode.texi \
+ core.texi elf.texi elfcode.texi format.texi libbfd.texi \
+ opncls.texi reloc.texi section.texi \
+ syms.texi targets.texi init.texi hash.texi linker.texi
+
+
+PROTOS = archive.p archures.p bfd.p \
+ core.p format.p \
+ libbfd.p opncls.p reloc.p \
+ section.p syms.p targets.p \
+ format.p core.p init.p
+
+
+IPROTOS = cache.ip libbfd.ip reloc.ip init.ip archures.ip coffcode.ip
+
+# SRCDOC, SRCPROT, SRCIPROT only used to sidestep Sun Make bug in interaction
+# between VPATH and suffix rules. If you use GNU Make, perhaps other Makes,
+# you don't need these three:
+SRCDOC = $(srcdir)/../aoutx.h $(srcdir)/../archive.c \
+ $(srcdir)/../archures.c $(srcdir)/../bfd.c \
+ $(srcdir)/../cache.c $(srcdir)/../coffcode.h \
+ $(srcdir)/../corefile.c $(srcdir)/../elf.c \
+ $(srcdir)/../elfcode.h $(srcdir)/../format.c \
+ $(srcdir)/../libbfd.c $(srcdir)/../opncls.c \
+ $(srcdir)/../reloc.c $(srcdir)/../section.c \
+ $(srcdir)/../syms.c $(srcdir)/../targets.c \
+ $(srcdir)/../hash.c $(srcdir)/../linker.c
+
+
+SRCPROT = $(srcdir)/../archive.c $(srcdir)/../archures.c \
+ $(srcdir)/../bfd.c $(srcdir)/../coffcode.h $(srcdir)/../corefile.c \
+ $(srcdir)/../format.c $(srcdir)/../libbfd.c \
+ $(srcdir)/../opncls.c $(srcdir)/../reloc.c \
+ $(srcdir)/../section.c $(srcdir)/../syms.c \
+ $(srcdir)/../targets.c $(srcdir)/../init.c
+
+
+SRCIPROT = $(srcdir)/../cache.c $(srcdir)/../libbfd.c \
+ $(srcdir)/../reloc.c $(srcdir)/../cpu-h8300.c \
+ $(srcdir)/../cpu-i960.c $(srcdir)/../archures.c \
+ $(srcdir)/../init.c
+
+
+TEXIDIR = $(srcdir)/../../texinfo/fsf
+
+info_TEXINFOS = bfd.texinfo
+
+MKDOC = chew$(EXEEXT_FOR_BUILD)
+
+noinst_TEXINFOS = bfdint.texi
+
+MOSTLYCLEANFILES = $(MKDOC) *.o
+
+CLEANFILES = s-* *.p *.ip
+
+DISTCLEANFILES = bfd.?? bfd.??? bfd.h libbfd.h libcoff.h texput.log
+
+MAINTAINERCLEANFILES = $(DOCFILES)
+mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs
+CONFIG_HEADER = ../config.h
+CONFIG_CLEAN_FILES =
+TEXI2DVI = `if test -f $(top_srcdir)/../texinfo/util/texi2dvi; then echo $(top_srcdir)/../texinfo/util/texi2dvi; else echo texi2dvi; fi`
+TEXINFO_TEX = $(top_srcdir)/../texinfo/texinfo.tex
+INFO_DEPS = bfd.info
+DVIS = bfd.dvi
+TEXINFOS = bfd.texinfo
+DIST_COMMON = ChangeLog Makefile.am Makefile.in
+
+
+DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
+
+TAR = tar
+GZIP_ENV = --best
+all: all-redirect
+.SUFFIXES:
+.SUFFIXES: .dvi .info .ps .texi .texinfo .txi
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4)
+ cd $(top_srcdir) && $(AUTOMAKE) --cygnus doc/Makefile
+
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ cd $(top_builddir) \
+ && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
+
+
+bfd.info: bfd.texinfo
+bfd.dvi: bfd.texinfo
+
+
+DVIPS = dvips
+
+.texi.info:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texi.dvi:
+ TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+ MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.texi:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texinfo.info:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texinfo:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.texinfo.dvi:
+ TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+ MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.txi.info:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+
+.txi.dvi:
+ TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+ MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.txi:
+ @rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ $(MAKEINFO) -I $(srcdir) $<
+.dvi.ps:
+ $(DVIPS) $< -o $@
+
+install-info-am: $(INFO_DEPS)
+ @$(NORMAL_INSTALL)
+ $(mkinstalldirs) $(DESTDIR)$(infodir)
+ @list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ if test -f $$file; then d=.; else d=$(srcdir); fi; \
+ for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
+ if test -f $$d/$$ifile; then \
+ echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \
+ $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \
+ else : ; fi; \
+ done; \
+ done
+ @$(POST_INSTALL)
+ @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
+ install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
+ done; \
+ else : ; fi
+
+uninstall-info:
+ $(PRE_UNINSTALL)
+ @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+ ii=yes; \
+ else ii=; fi; \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ test -z "$ii" \
+ || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \
+ done
+ @$(NORMAL_UNINSTALL)
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \
+ done
+
+dist-info: $(INFO_DEPS)
+ list='$(INFO_DEPS)'; \
+ for base in $$list; do \
+ if test -f $$base; then d=.; else d=$(srcdir); fi; \
+ for file in `cd $$d && eval echo $$base*`; do \
+ test -f $(distdir)/$$file \
+ || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
+ || cp -p $$d/$$file $(distdir)/$$file; \
+ done; \
+ done
+
+mostlyclean-aminfo:
+ -rm -f bfd.aux bfd.cp bfd.cps bfd.dvi bfd.fn bfd.fns bfd.ky bfd.kys \
+ bfd.ps bfd.log bfd.pg bfd.toc bfd.tp bfd.tps bfd.vr bfd.vrs \
+ bfd.op bfd.tr bfd.cv bfd.cn
+
+clean-aminfo:
+
+distclean-aminfo:
+
+maintainer-clean-aminfo:
+ for i in $(INFO_DEPS); do \
+ rm -f $$i; \
+ if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
+ rm -f $$i-[0-9]*; \
+ fi; \
+ done
+clean-info: mostlyclean-aminfo
+tags: TAGS
+TAGS:
+
+
+distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir)
+
+subdir = doc
+
+distdir: $(DISTFILES)
+ @for file in $(DISTFILES); do \
+ if test -f $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ cp -pr $$/$$file $(distdir)/$$file; \
+ else \
+ test -f $(distdir)/$$file \
+ || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
+ || cp -p $$d/$$file $(distdir)/$$file || :; \
+ fi; \
+ done
+ $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info
+info-am: $(INFO_DEPS)
+info: info-am
+dvi-am: $(DVIS)
+dvi: dvi-am
+check-am:
+check: check-am
+installcheck-am:
+installcheck: installcheck-am
+install-info-am:
+install-info: install-info-am
+install-exec-am:
+install-exec: install-exec-am
+
+install-data-am:
+install-data: install-data-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+install: install-am
+uninstall-am:
+uninstall: uninstall-am
+all-am: Makefile
+all-redirect: all-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install
+installdirs:
+
+
+mostlyclean-generic:
+ -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES)
+
+clean-generic:
+ -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+ -rm -f Makefile $(CONFIG_CLEAN_FILES)
+ -rm -f config.cache config.log stamp-h stamp-h[0-9]*
+ -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES)
+
+maintainer-clean-generic:
+ -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic
+
+mostlyclean: mostlyclean-am
+
+clean-am: clean-aminfo clean-generic mostlyclean-am
+
+clean: clean-am
+
+distclean-am: distclean-aminfo distclean-generic clean-am
+ -rm -f libtool
+
+distclean: distclean-am
+
+maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \
+ distclean-am
+ @echo "This command is intended for maintainers to use;"
+ @echo "it deletes files that may require special tools to rebuild."
+
+maintainer-clean: maintainer-clean-am
+
+.PHONY: install-info-am uninstall-info mostlyclean-aminfo \
+distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \
+info-am info dvi-am dvi check check-am installcheck-am installcheck \
+install-info-am install-info install-exec-am install-exec \
+install-data-am install-data install-am install uninstall-am uninstall \
+all-redirect all-am all installdirs mostlyclean-generic \
+distclean-generic clean-generic maintainer-clean-generic clean \
+mostlyclean distclean maintainer-clean
+
+
+$(MKDOC): chew.o
+ $(CC_FOR_BUILD) -o $(MKDOC) chew.o $(LOADLIBES) $(LDFLAGS)
+
+chew.o: chew.c
+ $(CC_FOR_BUILD) -c -I.. -I$(srcdir)/.. -I$(srcdir)/../../include -I$(srcdir)/../../intl -I../../intl $(H_CFLAGS) $(CFLAGS) $(srcdir)/chew.c
+
+protos: libbfd.h libcoff.h bfd.h
+
+bfd.info bfd.dvi: $(DOCFILES) bfdsumm.texi bfd.texinfo
+
+# We can't replace these rules with an implicit rule, because
+# makes without VPATH support couldn't find the .h files in `..'.
+
+# We use s-XXX targets so that we can distribute the info files,
+# and permit people to rebuild them, without requiring the makeinfo
+# program. If somebody tries to rebuild info, but none of the .texi
+# files have changed, then this Makefile will build chew, and will
+# build all of the stamp files, but will not actually have to rebuild
+# bfd.info.
+
+s-aoutx: $(MKDOC) $(srcdir)/../aoutx.h $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../aoutx.h >aoutx.tmp
+ $(srcdir)/../../move-if-change aoutx.tmp aoutx.texi
+ touch s-aoutx
+aoutx.texi: s-aoutx
+
+s-archive: $(MKDOC) $(srcdir)/../archive.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../archive.c >archive.tmp
+ $(srcdir)/../../move-if-change archive.tmp archive.texi
+ touch s-archive
+archive.texi: s-archive
+
+s-archures: $(MKDOC) $(srcdir)/../archures.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../archures.c >archures.tmp
+ $(srcdir)/../../move-if-change archures.tmp archures.texi
+ touch s-archures
+archures.texi: s-archures
+
+# We use bfdt.texi, rather than bfd.texi, to avoid conflicting with
+# bfd.texinfo on an 8.3 filesystem.
+s-bfd: $(MKDOC) $(srcdir)/../bfd.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../bfd.c >bfd.tmp
+ $(srcdir)/../../move-if-change bfd.tmp bfdt.texi
+ touch s-bfd
+bfdt.texi: s-bfd
+
+s-cache: $(MKDOC) $(srcdir)/../cache.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../cache.c >cache.tmp
+ $(srcdir)/../../move-if-change cache.tmp cache.texi
+ touch s-cache
+cache.texi: s-cache
+
+s-coffcode: $(MKDOC) $(srcdir)/../coffcode.h $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../coffcode.h >coffcode.tmp
+ $(srcdir)/../../move-if-change coffcode.tmp coffcode.texi
+ touch s-coffcode
+coffcode.texi: s-coffcode
+
+s-core: $(MKDOC) $(srcdir)/../corefile.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../corefile.c >core.tmp
+ $(srcdir)/../../move-if-change core.tmp core.texi
+ touch s-core
+core.texi: s-core
+
+s-elf: $(MKDOC) $(srcdir)/../elf.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../elf.c >elf.tmp
+ $(srcdir)/../../move-if-change elf.tmp elf.texi
+ touch s-elf
+elf.texi: s-elf
+
+s-elfcode: $(MKDOC) $(srcdir)/../elfcode.h $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../elfcode.h >elfcode.tmp
+ $(srcdir)/../../move-if-change elfcode.tmp elfcode.texi
+ touch s-elfcode
+elfcode.texi: s-elfcode
+
+s-format: $(MKDOC) $(srcdir)/../format.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../format.c >format.tmp
+ $(srcdir)/../../move-if-change format.tmp format.texi
+ touch s-format
+format.texi: s-format
+
+s-libbfd: $(MKDOC) $(srcdir)/../libbfd.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str < $(srcdir)/../libbfd.c >libbfd.tmp
+ $(srcdir)/../../move-if-change libbfd.tmp libbfd.texi
+ touch s-libbfd
+libbfd.texi: s-libbfd
+
+s-opncls: $(MKDOC) $(srcdir)/../opncls.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../opncls.c >opncls.tmp
+ $(srcdir)/../../move-if-change opncls.tmp opncls.texi
+ touch s-opncls
+opncls.texi: s-opncls
+
+s-reloc: $(MKDOC) $(srcdir)/../reloc.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../reloc.c >reloc.tmp
+ $(srcdir)/../../move-if-change reloc.tmp reloc.texi
+ touch s-reloc
+reloc.texi: s-reloc
+
+s-section: $(MKDOC) $(srcdir)/../section.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../section.c >section.tmp
+ $(srcdir)/../../move-if-change section.tmp section.texi
+ touch s-section
+section.texi: s-section
+
+s-syms: $(MKDOC) $(srcdir)/../syms.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../syms.c >syms.tmp
+ $(srcdir)/../../move-if-change syms.tmp syms.texi
+ touch s-syms
+syms.texi: s-syms
+
+s-targets: $(MKDOC) $(srcdir)/../targets.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../targets.c >targets.tmp
+ $(srcdir)/../../move-if-change targets.tmp targets.texi
+ touch s-targets
+targets.texi: s-targets
+
+s-init: $(MKDOC) $(srcdir)/../init.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../init.c >init.tmp
+ $(srcdir)/../../move-if-change init.tmp init.texi
+ touch s-init
+init.texi: s-init
+
+s-hash: $(MKDOC) $(srcdir)/../hash.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../hash.c >hash.tmp
+ $(srcdir)/../../move-if-change hash.tmp hash.texi
+ touch s-hash
+hash.texi: s-hash
+
+s-linker: $(MKDOC) $(srcdir)/../linker.c $(srcdir)/doc.str
+ ./$(MKDOC) -f $(srcdir)/doc.str <$(srcdir)/../linker.c >linker.tmp
+ $(srcdir)/../../move-if-change linker.tmp linker.texi
+ touch s-linker
+linker.texi: s-linker
+
+libbfd.h: $(srcdir)/../libbfd-in.h \
+ $(srcdir)/../init.c \
+ $(srcdir)/../libbfd.c \
+ $(srcdir)/../cache.c \
+ $(srcdir)/../reloc.c \
+ $(srcdir)/../archures.c \
+ $(srcdir)/proto.str \
+ $(MKDOC)
+ cat $(srcdir)/../libbfd-in.h >libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../init.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../libbfd.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../cache.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../reloc.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../archures.c >>libbfd.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../elf.c >>libbfd.h
+
+libcoff.h: $(srcdir)/../libcoff-in.h \
+ $(srcdir)/../coffcode.h \
+ $(srcdir)/proto.str \
+ $(MKDOC)
+ cat $(srcdir)/../libcoff-in.h >libcoff.h
+ ./$(MKDOC) -i -f $(srcdir)/proto.str < $(srcdir)/../coffcode.h >>libcoff.h
+
+bfd.h: $(srcdir)/../bfd-in.h \
+ $(srcdir)/../init.c \
+ $(srcdir)/../opncls.c \
+ $(srcdir)/../libbfd.c \
+ $(srcdir)/../section.c \
+ $(srcdir)/../archures.c \
+ $(srcdir)/../reloc.c \
+ $(srcdir)/../syms.c \
+ $(srcdir)/../bfd.c \
+ $(srcdir)/../archive.c \
+ $(srcdir)/../corefile.c \
+ $(srcdir)/../targets.c \
+ $(srcdir)/../format.c \
+ $(srcdir)/proto.str \
+ $(MKDOC)
+ cat $(srcdir)/../bfd-in.h >bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../init.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../opncls.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../libbfd.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../section.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../archures.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../reloc.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../syms.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../bfd.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../archive.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../corefile.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../targets.c >>bfd.h
+ ./$(MKDOC) -f $(srcdir)/proto.str<$(srcdir)/../format.c >>bfd.h
+ echo "#ifdef __cplusplus" >>bfd.h
+ echo "}" >>bfd.h
+ echo "#endif" >>bfd.h
+ echo "#endif" >>bfd.h
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/bfd/doc/bfd.texinfo b/bfd/doc/bfd.texinfo
new file mode 100644
index 0000000..eadf87c
--- /dev/null
+++ b/bfd/doc/bfd.texinfo
@@ -0,0 +1,348 @@
+\input texinfo.tex
+@setfilename bfd.info
+@c $Id$
+@tex
+% NOTE LOCAL KLUGE TO AVOID TOO MUCH WHITESPACE
+\global\long\def\example{%
+\begingroup
+\let\aboveenvbreak=\par
+\let\afterenvbreak=\par
+\parskip=0pt
+\lisp}
+\global\long\def\Eexample{%
+\Elisp
+\endgroup
+\vskip -\parskip% to cancel out effect of following \par
+}
+@end tex
+@synindex fn cp
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Bfd: (bfd). The Binary File Descriptor library.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This file documents the BFD library.
+
+Copyright (C) 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, subject to the terms
+of the GNU General Public License, which includes the provision that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+@iftex
+@c@finalout
+@setchapternewpage on
+@c@setchapternewpage odd
+@settitle LIB BFD, the Binary File Descriptor Library
+@titlepage
+@title{libbfd}
+@subtitle{The Binary File Descriptor Library}
+@sp 1
+@subtitle First Edition---BFD version < 3.0
+@subtitle April 1991
+@author {Steve Chamberlain}
+@author {Cygnus Support}
+@page
+
+@tex
+\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$} % For use in headers, footers too
+{\parskip=0pt
+\hfill Cygnus Support\par
+\hfill sac\@cygnus.com\par
+\hfill {\it BFD}, \manvers\par
+\hfill \TeX{}info \texinfoversion\par
+}
+\global\parindent=0pt % Steve likes it this way
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, subject to the terms
+of the GNU General Public License, which includes the provision that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+@end iftex
+
+@node Top, Overview, (dir), (dir)
+@ifinfo
+This file documents the binary file descriptor library libbfd.
+@end ifinfo
+
+@menu
+* Overview:: Overview of BFD
+* BFD front end:: BFD front end
+* BFD back ends:: BFD back ends
+* Index:: Index
+@end menu
+
+@node Overview, BFD front end, Top, Top
+@chapter Introduction
+@cindex BFD
+@cindex what is it?
+BFD is a package which allows applications to use the
+same routines to operate on object files whatever the object file
+format. A new object file format can be supported simply by
+creating a new BFD back end and adding it to the library.
+
+BFD is split into two parts: the front end, and the back ends (one for
+each object file format).
+@itemize @bullet
+@item The front end of BFD provides the interface to the user. It manages
+memory and various canonical data structures. The front end also
+decides which back end to use and when to call back end routines.
+@item The back ends provide BFD its view of the real world. Each back
+end provides a set of calls which the BFD front end can use to maintain
+its canonical form. The back ends also may keep around information for
+their own use, for greater efficiency.
+@end itemize
+@menu
+* History:: History
+* How It Works:: How It Works
+* What BFD Version 2 Can Do:: What BFD Version 2 Can Do
+@end menu
+
+@node History, How It Works, Overview, Overview
+@section History
+
+One spur behind BFD was the desire, on the part of the GNU 960 team at
+Intel Oregon, for interoperability of applications on their COFF and
+b.out file formats. Cygnus was providing GNU support for the team, and
+was contracted to provide the required functionality.
+
+The name came from a conversation David Wallace was having with Richard
+Stallman about the library: RMS said that it would be quite hard---David
+said ``BFD''. Stallman was right, but the name stuck.
+
+At the same time, Ready Systems wanted much the same thing, but for
+different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
+coff.
+
+BFD was first implemented by members of Cygnus Support; Steve
+Chamberlain (@code{sac@@cygnus.com}), John Gilmore
+(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com})
+and David Henkel-Wallace (@code{gumby@@cygnus.com}).
+
+
+
+@node How It Works, What BFD Version 2 Can Do, History, Overview
+@section How To Use BFD
+
+To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
+
+BFD provides a common interface to the parts of an object file
+for a calling application.
+
+When an application sucessfully opens a target file (object, archive, or
+whatever), a pointer to an internal structure is returned. This pointer
+points to a structure called @code{bfd}, described in
+@file{bfd.h}. Our convention is to call this pointer a BFD, and
+instances of it within code @code{abfd}. All operations on
+the target object file are applied as methods to the BFD. The mapping is
+defined within @code{bfd.h} in a set of macros, all beginning
+with @samp{bfd_} to reduce namespace pollution.
+
+For example, this sequence does what you would probably expect:
+return the number of sections in an object file attached to a BFD
+@code{abfd}.
+
+@lisp
+@c @cartouche
+#include "bfd.h"
+
+unsigned int number_of_sections(abfd)
+bfd *abfd;
+@{
+ return bfd_count_sections(abfd);
+@}
+@c @end cartouche
+@end lisp
+
+The abstraction used within BFD is that an object file has:
+
+@itemize @bullet
+@item
+a header,
+@item
+a number of sections containing raw data (@pxref{Sections}),
+@item
+a set of relocations (@pxref{Relocations}), and
+@item
+some symbol information (@pxref{Symbols}).
+@end itemize
+@noindent
+Also, BFDs opened for archives have the additional attribute of an index
+and contain subordinate BFDs. This approach is fine for a.out and coff,
+but loses efficiency when applied to formats such as S-records and
+IEEE-695.
+
+@node What BFD Version 2 Can Do, , How It Works, Overview
+@section What BFD Version 2 Can Do
+@include bfdsumm.texi
+
+@node BFD front end, BFD back ends, Overview, Top
+@chapter BFD front end
+@include bfdt.texi
+
+@menu
+* Memory Usage::
+* Initialization::
+* Sections::
+* Symbols::
+* Archives::
+* Formats::
+* Relocations::
+* Core Files::
+* Targets::
+* Architectures::
+* Opening and Closing::
+* Internal::
+* File Caching::
+* Linker Functions::
+* Hash Tables::
+@end menu
+
+@node Memory Usage, Initialization, BFD front end, BFD front end
+@section Memory usage
+BFD keeps all of its internal structures in obstacks. There is one obstack
+per open BFD file, into which the current state is stored. When a BFD is
+closed, the obstack is deleted, and so everything which has been
+allocated by BFD for the closing file is thrown away.
+
+BFD does not free anything created by an application, but pointers into
+@code{bfd} structures become invalid on a @code{bfd_close}; for example,
+after a @code{bfd_close} the vector passed to
+@code{bfd_canonicalize_symtab} is still around, since it has been
+allocated by the application, but the data that it pointed to are
+lost.
+
+The general rule is to not close a BFD until all operations dependent
+upon data from the BFD have been completed, or all the data from within
+the file has been copied. To help with the management of memory, there
+is a function (@code{bfd_alloc_size}) which returns the number of bytes
+in obstacks associated with the supplied BFD. This could be used to
+select the greediest open BFD, close it to reclaim the memory, perform
+some operation and reopen the BFD again, to get a fresh copy of the data
+structures.
+
+@node Initialization, Sections, Memory Usage, BFD front end
+@include init.texi
+
+@node Sections, Symbols, Initialization, BFD front end
+@include section.texi
+
+@node Symbols, Archives, Sections, BFD front end
+@include syms.texi
+
+@node Archives, Formats, Symbols, BFD front end
+@include archive.texi
+
+@node Formats, Relocations, Archives, BFD front end
+@include format.texi
+
+@node Relocations, Core Files, Formats, BFD front end
+@include reloc.texi
+
+@node Core Files, Targets, Relocations, BFD front end
+@include core.texi
+
+@node Targets, Architectures, Core Files, BFD front end
+@include targets.texi
+
+@node Architectures, Opening and Closing, Targets, BFD front end
+@include archures.texi
+
+@node Opening and Closing, Internal, Architectures, BFD front end
+@include opncls.texi
+
+@node Internal, File Caching, Opening and Closing, BFD front end
+@include libbfd.texi
+
+@node File Caching, Linker Functions, Internal, BFD front end
+@include cache.texi
+
+@node Linker Functions, Hash Tables, File Caching, BFD front end
+@include linker.texi
+
+@node Hash Tables, , Linker Functions, BFD front end
+@include hash.texi
+
+@node BFD back ends, Index, BFD front end, Top
+@chapter BFD back ends
+@menu
+* What to Put Where::
+* aout :: a.out backends
+* coff :: coff backends
+* elf :: elf backends
+@ignore
+* oasys :: oasys backends
+* ieee :: ieee backend
+* srecord :: s-record backend
+@end ignore
+@end menu
+@node What to Put Where, aout, BFD back ends, BFD back ends
+All of BFD lives in one directory.
+
+@node aout, coff, What to Put Where, BFD back ends
+@include aoutx.texi
+
+@node coff, elf, aout, BFD back ends
+@include coffcode.texi
+
+@node elf, , coff, BFD back ends
+@include elf.texi
+@c Leave this out until the file has some actual contents...
+@c @include elfcode.texi
+
+@node Index, , BFD back ends , Top
+@unnumbered Index
+@printindex cp
+
+@tex
+% I think something like @colophon should be in texinfo. In the
+% meantime:
+\long\def\colophon{\hbox to0pt{}\vfill
+\centerline{The body of this manual is set in}
+\centerline{\fontname\tenrm,}
+\centerline{with headings in {\bf\fontname\tenbf}}
+\centerline{and examples in {\tt\fontname\tentt}.}
+\centerline{{\it\fontname\tenit\/} and}
+\centerline{{\sl\fontname\tensl\/}}
+\centerline{are used for emphasis.}\vfill}
+\page\colophon
+% Blame: doc@cygnus.com, 28mar91.
+@end tex
+
+@contents
+@bye
diff --git a/bfd/doc/bfdint.texi b/bfd/doc/bfdint.texi
new file mode 100644
index 0000000..eb09b34
--- /dev/null
+++ b/bfd/doc/bfdint.texi
@@ -0,0 +1,1885 @@
+\input texinfo
+@setfilename bfdint.info
+
+@settitle BFD Internals
+@iftex
+@titlepage
+@title{BFD Internals}
+@author{Ian Lance Taylor}
+@author{Cygnus Solutions}
+@page
+@end iftex
+
+@node Top
+@top BFD Internals
+@raisesections
+@cindex bfd internals
+
+This document describes some BFD internal information which may be
+helpful when working on BFD. It is very incomplete.
+
+This document is not updated regularly, and may be out of date. It was
+last modified on $Date$.
+
+The initial version of this document was written by Ian Lance Taylor
+@email{ian@@cygnus.com}.
+
+@menu
+* BFD overview:: BFD overview
+* BFD guidelines:: BFD programming guidelines
+* BFD target vector:: BFD target vector
+* BFD generated files:: BFD generated files
+* BFD multiple compilations:: Files compiled multiple times in BFD
+* BFD relocation handling:: BFD relocation handling
+* BFD ELF support:: BFD ELF support
+* BFD glossary:: Glossary
+* Index:: Index
+@end menu
+
+@node BFD overview
+@section BFD overview
+
+BFD is a library which provides a single interface to read and write
+object files, executables, archive files, and core files in any format.
+
+@menu
+* BFD library interfaces:: BFD library interfaces
+* BFD library users:: BFD library users
+* BFD view:: The BFD view of a file
+* BFD blindness:: BFD loses information
+@end menu
+
+@node BFD library interfaces
+@subsection BFD library interfaces
+
+One way to look at the BFD library is to divide it into four parts by
+type of interface.
+
+The first interface is the set of generic functions which programs using
+the BFD library will call. These generic function normally translate
+directly or indirectly into calls to routines which are specific to a
+particular object file format. Many of these generic functions are
+actually defined as macros in @file{bfd.h}. These functions comprise
+the official BFD interface.
+
+The second interface is the set of functions which appear in the target
+vectors. This is the bulk of the code in BFD. A target vector is a set
+of function pointers specific to a particular object file format. The
+target vector is used to implement the generic BFD functions. These
+functions are always called through the target vector, and are never
+called directly. The target vector is described in detail in @ref{BFD
+target vector}. The set of functions which appear in a particular
+target vector is often referred to as a BFD backend.
+
+The third interface is a set of oddball functions which are typically
+specific to a particular object file format, are not generic functions,
+and are called from outside of the BFD library. These are used as hooks
+by the linker and the assembler when a particular object file format
+requires some action which the BFD generic interface does not provide.
+These functions are typically declared in @file{bfd.h}, but in many
+cases they are only provided when BFD is configured with support for a
+particular object file format. These functions live in a grey area, and
+are not really part of the official BFD interface.
+
+The fourth interface is the set of BFD support functions which are
+called by the other BFD functions. These manage issues like memory
+allocation, error handling, file access, hash tables, swapping, and the
+like. These functions are never called from outside of the BFD library.
+
+@node BFD library users
+@subsection BFD library users
+
+Another way to look at the BFD library is to divide it into three parts
+by the manner in which it is used.
+
+The first use is to read an object file. The object file readers are
+programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}.
+These programs use BFD to view an object file in a generic form. The
+official BFD interface is normally fully adequate for these programs.
+
+The second use is to write an object file. The object file writers are
+programs like @samp{gas} and @samp{objcopy}. These programs use BFD to
+create an object file. The official BFD interface is normally adequate
+for these programs, but for some object file formats the assembler needs
+some additional hooks in order to set particular flags or other
+information. The official BFD interface includes functions to copy
+private information from one object file to another, and these functions
+are used by @samp{objcopy} to avoid information loss.
+
+The third use is to link object files. There is only one object file
+linker, @samp{ld}. Originally, @samp{ld} was an object file reader and
+an object file writer, and it did the link operation using the generic
+BFD structures. However, this turned out to be too slow and too memory
+intensive.
+
+The official BFD linker functions were written to permit specific BFD
+backends to perform the link without translating through the generic
+structures, in the normal case where all the input files and output file
+have the same object file format. Not all of the backends currently
+implement the new interface, and there are default linking functions
+within BFD which use the generic structures and which work with all
+backends.
+
+For several object file formats the linker needs additional hooks which
+are not provided by the official BFD interface, particularly for dynamic
+linking support. These functions are typically called from the linker
+emulation template.
+
+@node BFD view
+@subsection The BFD view of a file
+
+BFD uses generic structures to manage information. It translates data
+into the generic form when reading files, and out of the generic form
+when writing files.
+
+BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd}
+is composed of the following elements. The BFD information can be
+displayed using the @samp{objdump} program with various options.
+
+@table @asis
+@item general information
+The object file format, a few general flags, the start address.
+@item architecture
+The architecture, including both a general processor type (m68k, MIPS
+etc.) and a specific machine number (m68000, R4000, etc.).
+@item sections
+A list of sections.
+@item symbols
+A symbol table.
+@end table
+
+BFD represents a section as a pointer to the @samp{asection} type. Each
+section has a name and a size. Most sections also have an associated
+block of data, known as the section contents. Sections also have
+associated flags, a virtual memory address, a load memory address, a
+required alignment, a list of relocations, and other miscellaneous
+information.
+
+BFD represents a relocation as a pointer to the @samp{arelent} type. A
+relocation describes an action which the linker must take to modify the
+section contents. Relocations have a symbol, an address, an addend, and
+a pointer to a howto structure which describes how to perform the
+relocation. For more information, see @ref{BFD relocation handling}.
+
+BFD represents a symbol as a pointer to the @samp{asymbol} type. A
+symbol has a name, a pointer to a section, an offset within that
+section, and some flags.
+
+Archive files do not have any sections or symbols. Instead, BFD
+represents an archive file as a file which contains a list of
+@samp{bfd}s. BFD also provides access to the archive symbol map, as a
+list of symbol names. BFD provides a function to return the @samp{bfd}
+within the archive which corresponds to a particular entry in the
+archive symbol map.
+
+@node BFD blindness
+@subsection BFD loses information
+
+Most object file formats have information which BFD can not represent in
+its generic form, at least as currently defined.
+
+There is often explicit information which BFD can not represent. For
+example, the COFF version stamp, or the ELF program segments. BFD
+provides special hooks to handle this information when copying,
+printing, or linking an object file. The BFD support for a particular
+object file format will normally store this information in private data
+and handle it using the special hooks.
+
+In some cases there is also implicit information which BFD can not
+represent. For example, the MIPS processor distinguishes small and
+large symbols, and requires that all small symbls be within 32K of the
+GP register. This means that the MIPS assembler must be able to mark
+variables as either small or large, and the MIPS linker must know to put
+small symbols within range of the GP register. Since BFD can not
+represent this information, this means that the assembler and linker
+must have information that is specific to a particular object file
+format which is outside of the BFD library.
+
+This loss of information indicates areas where the BFD paradigm breaks
+down. It is not actually possible to represent the myriad differences
+among object file formats using a single generic interface, at least not
+in the manner which BFD does it today.
+
+Nevertheless, the BFD library does greatly simplify the task of dealing
+with object files, and particular problems caused by information loss
+can normally be solved using some sort of relatively constrained hook
+into the library.
+
+
+
+@node BFD guidelines
+@section BFD programming guidelines
+@cindex bfd programming guidelines
+@cindex programming guidelines for bfd
+@cindex guidelines, bfd programming
+
+There is a lot of poorly written and confusing code in BFD. New BFD
+code should be written to a higher standard. Merely because some BFD
+code is written in a particular manner does not mean that you should
+emulate it.
+
+Here are some general BFD programming guidelines:
+
+@itemize @bullet
+@item
+Follow the GNU coding standards.
+
+@item
+Avoid global variables. We ideally want BFD to be fully reentrant, so
+that it can be used in multiple threads. All uses of global or static
+variables interfere with that. Initialized constant variables are OK,
+and they should be explicitly marked with const. Instead of global
+variables, use data attached to a BFD or to a linker hash table.
+
+@item
+All externally visible functions should have names which start with
+@samp{bfd_}. All such functions should be declared in some header file,
+typically @file{bfd.h}. See, for example, the various declarations near
+the end of @file{bfd-in.h}, which mostly declare functions required by
+specific linker emulations.
+
+@item
+All functions which need to be visible from one file to another within
+BFD, but should not be visible outside of BFD, should start with
+@samp{_bfd_}. Although external names beginning with @samp{_} are
+prohibited by the ANSI standard, in practice this usage will always
+work, and it is required by the GNU coding standards.
+
+@item
+Always remember that people can compile using @samp{--enable-targets} to
+build several, or all, targets at once. It must be possible to link
+together the files for all targets.
+
+@item
+BFD code should compile with few or no warnings using @samp{gcc -Wall}.
+Some warnings are OK, like the absence of certain function declarations
+which may or may not be declared in system header files. Warnings about
+ambiguous expressions and the like should always be fixed.
+@end itemize
+
+@node BFD target vector
+@section BFD target vector
+@cindex bfd target vector
+@cindex target vector in bfd
+
+BFD supports multiple object file formats by using the @dfn{target
+vector}. This is simply a set of function pointers which implement
+behaviour that is specific to a particular object file format.
+
+In this section I list all of the entries in the target vector and
+describe what they do.
+
+@menu
+* BFD target vector miscellaneous:: Miscellaneous constants
+* BFD target vector swap:: Swapping functions
+* BFD target vector format:: Format type dependent functions
+* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros
+* BFD target vector generic:: Generic functions
+* BFD target vector copy:: Copy functions
+* BFD target vector core:: Core file support functions
+* BFD target vector archive:: Archive functions
+* BFD target vector symbols:: Symbol table functions
+* BFD target vector relocs:: Relocation support
+* BFD target vector write:: Output functions
+* BFD target vector link:: Linker functions
+* BFD target vector dynamic:: Dynamic linking information functions
+@end menu
+
+@node BFD target vector miscellaneous
+@subsection Miscellaneous constants
+
+The target vector starts with a set of constants.
+
+@table @samp
+@item name
+The name of the target vector. This is an arbitrary string. This is
+how the target vector is named in command line options for tools which
+use BFD, such as the @samp{-oformat} linker option.
+
+@item flavour
+A general description of the type of target. The following flavours are
+currently defined:
+
+@table @samp
+@item bfd_target_unknown_flavour
+Undefined or unknown.
+@item bfd_target_aout_flavour
+a.out.
+@item bfd_target_coff_flavour
+COFF.
+@item bfd_target_ecoff_flavour
+ECOFF.
+@item bfd_target_elf_flavour
+ELF.
+@item bfd_target_ieee_flavour
+IEEE-695.
+@item bfd_target_nlm_flavour
+NLM.
+@item bfd_target_oasys_flavour
+OASYS.
+@item bfd_target_tekhex_flavour
+Tektronix hex format.
+@item bfd_target_srec_flavour
+Motorola S-record format.
+@item bfd_target_ihex_flavour
+Intel hex format.
+@item bfd_target_som_flavour
+SOM (used on HP/UX).
+@item bfd_target_os9k_flavour
+os9000.
+@item bfd_target_versados_flavour
+VERSAdos.
+@item bfd_target_msdos_flavour
+MS-DOS.
+@item bfd_target_evax_flavour
+openVMS.
+@end table
+
+@item byteorder
+The byte order of data in the object file. One of
+@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or
+@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such
+as S-records which do not record the architecture of the data.
+
+@item header_byteorder
+The byte order of header information in the object file. Normally the
+same as the @samp{byteorder} field, but there are certain cases where it
+may be different.
+
+@item object_flags
+Flags which may appear in the @samp{flags} field of a BFD with this
+format.
+
+@item section_flags
+Flags which may appear in the @samp{flags} field of a section within a
+BFD with this format.
+
+@item symbol_leading_char
+A character which the C compiler normally puts before a symbol. For
+example, an a.out compiler will typically generate the symbol
+@samp{_foo} for a function named @samp{foo} in the C source, in which
+case this field would be @samp{_}. If there is no such character, this
+field will be @samp{0}.
+
+@item ar_pad_char
+The padding character to use at the end of an archive name. Normally
+@samp{/}.
+
+@item ar_max_namelen
+The maximum length of a short name in an archive. Normally @samp{14}.
+
+@item backend_data
+A pointer to constant backend data. This is used by backends to store
+whatever additional information they need to distinguish similar target
+vectors which use the same sets of functions.
+@end table
+
+@node BFD target vector swap
+@subsection Swapping functions
+
+Every target vector has fuction pointers used for swapping information
+in and out of the target representation. There are two sets of
+functions: one for data information, and one for header information.
+Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has
+three actual functions: put, get unsigned, and get signed.
+
+These 18 functions are used to convert data between the host and target
+representations.
+
+@node BFD target vector format
+@subsection Format type dependent functions
+
+Every target vector has three arrays of function pointers which are
+indexed by the BFD format type. The BFD format types are as follows:
+
+@table @samp
+@item bfd_unknown
+Unknown format. Not used for anything useful.
+@item bfd_object
+Object file.
+@item bfd_archive
+Archive file.
+@item bfd_core
+Core file.
+@end table
+
+The three arrays of function pointers are as follows:
+
+@table @samp
+@item bfd_check_format
+Check whether the BFD is of a particular format (object file, archive
+file, or core file) corresponding to this target vector. This is called
+by the @samp{bfd_check_format} function when examining an existing BFD.
+If the BFD matches the desired format, this function will initialize any
+format specific information such as the @samp{tdata} field of the BFD.
+This function must be called before any other BFD target vector function
+on a file opened for reading.
+
+@item bfd_set_format
+Set the format of a BFD which was created for output. This is called by
+the @samp{bfd_set_format} function after creating the BFD with a
+function such as @samp{bfd_openw}. This function will initialize format
+specific information required to write out an object file or whatever of
+the given format. This function must be called before any other BFD
+target vector function on a file opened for writing.
+
+@item bfd_write_contents
+Write out the contents of the BFD in the given format. This is called
+by @samp{bfd_close} function for a BFD opened for writing. This really
+should not be an array selected by format type, as the
+@samp{bfd_set_format} function provides all the required information.
+In fact, BFD will fail if a different format is used when calling
+through the @samp{bfd_set_format} and the @samp{bfd_write_contents}
+arrays; fortunately, since @samp{bfd_close} gets it right, this is a
+difficult error to make.
+@end table
+
+@node BFD_JUMP_TABLE macros
+@subsection @samp{BFD_JUMP_TABLE} macros
+@cindex @samp{BFD_JUMP_TABLE}
+
+Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros.
+These macros take a single argument, which is a prefix applied to a set
+of functions. The macros are then used to initialize the fields in the
+target vector.
+
+For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three
+functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc},
+and @samp{_bfd_reloc_type_lookup}. A reference like
+@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions
+prefixed with @samp{foo}: @samp{foo_get_reloc_upper_found}, etc. The
+@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three
+functions initialize the appropriate fields in the BFD target vector.
+
+This is done because it turns out that many different target vectors can
+share certain classes of functions. For example, archives are similar
+on most platforms, so most target vectors can use the same archive
+functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE}
+with the same argument, calling a set of functions which is defined in
+@file{archive.c}.
+
+Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with
+the description of the function pointers which it defines. The function
+pointers will be described using the name without the prefix which the
+@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as
+the name of the field in the target vector structure. Any differences
+will be noted.
+
+@node BFD target vector generic
+@subsection Generic functions
+@cindex @samp{BFD_JUMP_TABLE_GENERIC}
+
+The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all
+functions which don't easily fit into other categories.
+
+@table @samp
+@item _close_and_cleanup
+Free any target specific information associated with the BFD. This is
+called when any BFD is closed (the @samp{bfd_write_contents} function
+mentioned earlier is only called for a BFD opened for writing). Most
+targets use @samp{bfd_alloc} to allocate all target specific
+information, and therefore don't have to do anything in this function.
+This function pointer is typically set to
+@samp{_bfd_generic_close_and_cleanup}, which simply returns true.
+
+@item _bfd_free_cached_info
+Free any cached information associated with the BFD which can be
+recreated later if necessary. This is used to reduce the memory
+consumption required by programs using BFD. This is normally called via
+the @samp{bfd_free_cached_info} macro. It is used by the default
+archive routines when computing the archive map. Most targets do not
+do anything special for this entry point, and just set it to
+@samp{_bfd_generic_free_cached_info}, which simply returns true.
+
+@item _new_section_hook
+This is called from @samp{bfd_make_section_anyway} whenever a new
+section is created. Most targets use it to initialize section specific
+information. This function is called whether or not the section
+corresponds to an actual section in an actual BFD.
+
+@item _get_section_contents
+Get the contents of a section. This is called from
+@samp{bfd_get_section_contents}. Most targets set this to
+@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek}
+based on the section's @samp{filepos} field and a @samp{bfd_read}. The
+corresponding field in the target vector is named
+@samp{_bfd_get_section_contents}.
+
+@item _get_section_contents_in_window
+Set a @samp{bfd_window} to hold the contents of a section. This is
+called from @samp{bfd_get_section_contents_in_window}. The
+@samp{bfd_window} idea never really caught on, and I don't think this is
+ever called. Pretty much all targets implement this as
+@samp{bfd_generic_get_section_contents_in_window}, which uses
+@samp{bfd_get_section_contents} to do the right thing. The
+corresponding field in the target vector is named
+@samp{_bfd_get_section_contents_in_window}.
+@end table
+
+@node BFD target vector copy
+@subsection Copy functions
+@cindex @samp{BFD_JUMP_TABLE_COPY}
+
+The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are
+called when copying BFDs, and for a couple of functions which deal with
+internal BFD information.
+
+@table @samp
+@item _bfd_copy_private_bfd_data
+This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}.
+If the input and output BFDs have the same format, this will copy any
+private information over. This is called after all the section contents
+have been written to the output file. Only a few targets do anything in
+this function.
+
+@item _bfd_merge_private_bfd_data
+This is called when linking, via @samp{bfd_merge_private_bfd_data}. It
+gives the backend linker code a chance to set any special flags in the
+output file based on the contents of the input file. Only a few targets
+do anything in this function.
+
+@item _bfd_copy_private_section_data
+This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called
+for each section, via @samp{bfd_copy_private_section_data}. This
+function is called before any section contents have been written. Only
+a few targets do anything in this function.
+
+@item _bfd_copy_private_symbol_data
+This is called via @samp{bfd_copy_private_symbol_data}, but I don't
+think anything actually calls it. If it were defined, it could be used
+to copy private symbol data from one BFD to another. However, most BFDs
+store extra symbol information by allocating space which is larger than
+the @samp{asymbol} structure and storing private information in the
+extra space. Since @samp{objcopy} and other programs copy symbol
+information by copying pointers to @samp{asymbol} structures, the
+private symbol information is automatically copied as well. Most
+targets do not do anything in this function.
+
+@item _bfd_set_private_flags
+This is called via @samp{bfd_set_private_flags}. It is basically a hook
+for the assembler to set magic information. For example, the PowerPC
+ELF assembler uses it to set flags which appear in the e_flags field of
+the ELF header. Most targets do not do anything in this function.
+
+@item _bfd_print_private_bfd_data
+This is called by @samp{objdump} when the @samp{-p} option is used. It
+is called via @samp{bfd_print_private_data}. It prints any interesting
+information about the BFD which can not be otherwise represented by BFD
+and thus can not be printed by @samp{objdump}. Most targets do not do
+anything in this function.
+@end table
+
+@node BFD target vector core
+@subsection Core file support functions
+@cindex @samp{BFD_JUMP_TABLE_CORE}
+
+The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal
+with core files. Obviously, these functions only do something
+interesting for targets which have core file support.
+
+@table @samp
+@item _core_file_failing_command
+Given a core file, this returns the command which was run to produce the
+core file.
+
+@item _core_file_failing_signal
+Given a core file, this returns the signal number which produced the
+core file.
+
+@item _core_file_matches_executable_p
+Given a core file and a BFD for an executable, this returns whether the
+core file was generated by the executable.
+@end table
+
+@node BFD target vector archive
+@subsection Archive functions
+@cindex @samp{BFD_JUMP_TABLE_ARCHIVE}
+
+The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal
+with archive files. Most targets use COFF style archive files
+(including ELF targets), and these use @samp{_bfd_archive_coff} as the
+argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out
+style archives, and these use @samp{_bfd_archive_bsd}. (The main
+difference between BSD and COFF archives is the format of the archive
+symbol table). Targets with no archive support use
+@samp{_bfd_noarchive}. Finally, a few targets have unusual archive
+handling.
+
+@table @samp
+@item _slurp_armap
+Read in the archive symbol table, storing it in private BFD data. This
+is normally called from the archive @samp{check_format} routine. The
+corresponding field in the target vector is named
+@samp{_bfd_slurp_armap}.
+
+@item _slurp_extended_name_table
+Read in the extended name table from the archive, if there is one,
+storing it in private BFD data. This is normally called from the
+archive @samp{check_format} routine. The corresponding field in the
+target vector is named @samp{_bfd_slurp_extended_name_table}.
+
+@item construct_extended_name_table
+Build and return an extended name table if one is needed to write out
+the archive. This also adjusts the archive headers to refer to the
+extended name table appropriately. This is normally called from the
+archive @samp{write_contents} routine. The corresponding field in the
+target vector is named @samp{_bfd_construct_extended_name_table}.
+
+@item _truncate_arname
+This copies a file name into an archive header, truncating it as
+required. It is normally called from the archive @samp{write_contents}
+routine. This function is more interesting in targets which do not
+support extended name tables, but I think the GNU @samp{ar} program
+always uses extended name tables anyhow. The corresponding field in the
+target vector is named @samp{_bfd_truncate_arname}.
+
+@item _write_armap
+Write out the archive symbol table using calls to @samp{bfd_write}.
+This is normally called from the archive @samp{write_contents} routine.
+The corresponding field in the target vector is named @samp{write_armap}
+(no leading underscore).
+
+@item _read_ar_hdr
+Read and parse an archive header. This handles expanding the archive
+header name into the real file name using the extended name table. This
+is called by routines which read the archive symbol table or the archive
+itself. The corresponding field in the target vector is named
+@samp{_bfd_read_ar_hdr_fn}.
+
+@item _openr_next_archived_file
+Given an archive and a BFD representing a file stored within the
+archive, return a BFD for the next file in the archive. This is called
+via @samp{bfd_openr_next_archived_file}. The corresponding field in the
+target vector is named @samp{openr_next_archived_file} (no leading
+underscore).
+
+@item _get_elt_at_index
+Given an archive and an index, return a BFD for the file in the archive
+corresponding to that entry in the archive symbol table. This is called
+via @samp{bfd_get_elt_at_index}. The corresponding field in the target
+vector is named @samp{_bfd_get_elt_at_index}.
+
+@item _generic_stat_arch_elt
+Do a stat on an element of an archive, returning information read from
+the archive header (modification time, uid, gid, file mode, size). This
+is called via @samp{bfd_stat_arch_elt}. The corresponding field in the
+target vector is named @samp{_bfd_stat_arch_elt}.
+
+@item _update_armap_timestamp
+After the entire contents of an archive have been written out, update
+the timestamp of the archive symbol table to be newer than that of the
+file. This is required for a.out style archives. This is normally
+called by the archive @samp{write_contents} routine. The corresponding
+field in the target vector is named @samp{_bfd_update_armap_timestamp}.
+@end table
+
+@node BFD target vector symbols
+@subsection Symbol table functions
+@cindex @samp{BFD_JUMP_TABLE_SYMBOLS}
+
+The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal
+with symbols.
+
+@table @samp
+@item _get_symtab_upper_bound
+Return a sensible upper bound on the amount of memory which will be
+required to read the symbol table. In practice most targets return the
+amount of memory required to hold @samp{asymbol} pointers for all the
+symbols plus a trailing @samp{NULL} entry, and store the actual symbol
+information in BFD private data. This is called via
+@samp{bfd_get_symtab_upper_bound}. The corresponding field in the
+target vector is named @samp{_bfd_get_symtab_upper_bound}.
+
+@item _get_symtab
+Read in the symbol table. This is called via
+@samp{bfd_canonicalize_symtab}. The corresponding field in the target
+vector is named @samp{_bfd_canonicalize_symtab}.
+
+@item _make_empty_symbol
+Create an empty symbol for the BFD. This is needed because most targets
+store extra information with each symbol by allocating a structure
+larger than an @samp{asymbol} and storing the extra information at the
+end. This function will allocate the right amount of memory, and return
+what looks like a pointer to an empty @samp{asymbol}. This is called
+via @samp{bfd_make_empty_symbol}. The corresponding field in the target
+vector is named @samp{_bfd_make_empty_symbol}.
+
+@item _print_symbol
+Print information about the symbol. This is called via
+@samp{bfd_print_symbol}. One of the arguments indicates what sort of
+information should be printed:
+
+@table @samp
+@item bfd_print_symbol_name
+Just print the symbol name.
+@item bfd_print_symbol_more
+Print the symbol name and some interesting flags. I don't think
+anything actually uses this.
+@item bfd_print_symbol_all
+Print all information about the symbol. This is used by @samp{objdump}
+when run with the @samp{-t} option.
+@end table
+The corresponding field in the target vector is named
+@samp{_bfd_print_symbol}.
+
+@item _get_symbol_info
+Return a standard set of information about the symbol. This is called
+via @samp{bfd_symbol_info}. The corresponding field in the target
+vector is named @samp{_bfd_get_symbol_info}.
+
+@item _bfd_is_local_label_name
+Return whether the given string would normally represent the name of a
+local label. This is called via @samp{bfd_is_local_label} and
+@samp{bfd_is_local_label_name}. Local labels are normally discarded by
+the assembler. In the linker, this defines the difference between the
+@samp{-x} and @samp{-X} options.
+
+@item _get_lineno
+Return line number information for a symbol. This is only meaningful
+for a COFF target. This is called when writing out COFF line numbers.
+
+@item _find_nearest_line
+Given an address within a section, use the debugging information to find
+the matching file name, function name, and line number, if any. This is
+called via @samp{bfd_find_nearest_line}. The corresponding field in the
+target vector is named @samp{_bfd_find_nearest_line}.
+
+@item _bfd_make_debug_symbol
+Make a debugging symbol. This is only meaningful for a COFF target,
+where it simply returns a symbol which will be placed in the
+@samp{N_DEBUG} section when it is written out. This is called via
+@samp{bfd_make_debug_symbol}.
+
+@item _read_minisymbols
+Minisymbols are used to reduce the memory requirements of programs like
+@samp{nm}. A minisymbol is a cookie pointing to internal symbol
+information which the caller can use to extract complete symbol
+information. This permits BFD to not convert all the symbols into
+generic form, but to instead convert them one at a time. This is called
+via @samp{bfd_read_minisymbols}. Most targets do not implement this,
+and just use generic support which is based on using standard
+@samp{asymbol} structures.
+
+@item _minisymbol_to_symbol
+Convert a minisymbol to a standard @samp{asymbol}. This is called via
+@samp{bfd_minisymbol_to_symbol}.
+@end table
+
+@node BFD target vector relocs
+@subsection Relocation support
+@cindex @samp{BFD_JUMP_TABLE_RELOCS}
+
+The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal
+with relocations.
+
+@table @samp
+@item _get_reloc_upper_bound
+Return a sensible upper bound on the amount of memory which will be
+required to read the relocations for a section. In practice most
+targets return the amount of memory required to hold @samp{arelent}
+pointers for all the relocations plus a trailing @samp{NULL} entry, and
+store the actual relocation information in BFD private data. This is
+called via @samp{bfd_get_reloc_upper_bound}.
+
+@item _canonicalize_reloc
+Return the relocation information for a section. This is called via
+@samp{bfd_canonicalize_reloc}. The corresponding field in the target
+vector is named @samp{_bfd_canonicalize_reloc}.
+
+@item _bfd_reloc_type_lookup
+Given a relocation code, return the corresponding howto structure
+(@pxref{BFD relocation codes}). This is called via
+@samp{bfd_reloc_type_lookup}. The corresponding field in the target
+vector is named @samp{reloc_type_lookup}.
+@end table
+
+@node BFD target vector write
+@subsection Output functions
+@cindex @samp{BFD_JUMP_TABLE_WRITE}
+
+The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal
+with writing out a BFD.
+
+@table @samp
+@item _set_arch_mach
+Set the architecture and machine number for a BFD. This is called via
+@samp{bfd_set_arch_mach}. Most targets implement this by calling
+@samp{bfd_default_set_arch_mach}. The corresponding field in the target
+vector is named @samp{_bfd_set_arch_mach}.
+
+@item _set_section_contents
+Write out the contents of a section. This is called via
+@samp{bfd_set_section_contents}. The corresponding field in the target
+vector is named @samp{_bfd_set_section_contents}.
+@end table
+
+@node BFD target vector link
+@subsection Linker functions
+@cindex @samp{BFD_JUMP_TABLE_LINK}
+
+The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the
+linker.
+
+@table @samp
+@item _sizeof_headers
+Return the size of the header information required for a BFD. This is
+used to implement the @samp{SIZEOF_HEADERS} linker script function. It
+is normally used to align the first section at an efficient position on
+the page. This is called via @samp{bfd_sizeof_headers}. The
+corresponding field in the target vector is named
+@samp{_bfd_sizeof_headers}.
+
+@item _bfd_get_relocated_section_contents
+Read the contents of a section and apply the relocation information.
+This handles both a final link and a relocateable link; in the latter
+case, it adjust the relocation information as well. This is called via
+@samp{bfd_get_relocated_section_contents}. Most targets implement it by
+calling @samp{bfd_generic_get_relocated_section_contents}.
+
+@item _bfd_relax_section
+Try to use relaxation to shrink the size of a section. This is called
+by the linker when the @samp{-relax} option is used. This is called via
+@samp{bfd_relax_section}. Most targets do not support any sort of
+relaxation.
+
+@item _bfd_link_hash_table_create
+Create the symbol hash table to use for the linker. This linker hook
+permits the backend to control the size and information of the elements
+in the linker symbol hash table. This is called via
+@samp{bfd_link_hash_table_create}.
+
+@item _bfd_link_add_symbols
+Given an object file or an archive, add all symbols into the linker
+symbol hash table. Use callbacks to the linker to include archive
+elements in the link. This is called via @samp{bfd_link_add_symbols}.
+
+@item _bfd_final_link
+Finish the linking process. The linker calls this hook after all of the
+input files have been read, when it is ready to finish the link and
+generate the output file. This is called via @samp{bfd_final_link}.
+
+@item _bfd_link_split_section
+I don't know what this is for. Nothing seems to call it. The only
+non-trivial definition is in @file{som.c}.
+@end table
+
+@node BFD target vector dynamic
+@subsection Dynamic linking information functions
+@cindex @samp{BFD_JUMP_TABLE_DYNAMIC}
+
+The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read
+dynamic linking information.
+
+@table @samp
+@item _get_dynamic_symtab_upper_bound
+Return a sensible upper bound on the amount of memory which will be
+required to read the dynamic symbol table. In practice most targets
+return the amount of memory required to hold @samp{asymbol} pointers for
+all the symbols plus a trailing @samp{NULL} entry, and store the actual
+symbol information in BFD private data. This is called via
+@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in
+the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}.
+
+@item _canonicalize_dynamic_symtab
+Read the dynamic symbol table. This is called via
+@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the
+target vector is named @samp{_bfd_canonicalize_dynamic_symtab}.
+
+@item _get_dynamic_reloc_upper_bound
+Return a sensible upper bound on the amount of memory which will be
+required to read the dynamic relocations. In practice most targets
+return the amount of memory required to hold @samp{arelent} pointers for
+all the relocations plus a trailing @samp{NULL} entry, and store the
+actual relocation information in BFD private data. This is called via
+@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in
+the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}.
+
+@item _canonicalize_dynamic_reloc
+Read the dynamic relocations. This is called via
+@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the
+target vector is named @samp{_bfd_canonicalize_dynamic_reloc}.
+@end table
+
+@node BFD generated files
+@section BFD generated files
+@cindex generated files in bfd
+@cindex bfd generated files
+
+BFD contains several automatically generated files. This section
+describes them. Some files are created at configure time, when you
+configure BFD. Some files are created at make time, when you build
+time. Some files are automatically rebuilt at make time, but only if
+you configure with the @samp{--enable-maintainer-mode} option. Some
+files live in the object directory---the directory from which you run
+configure---and some live in the source directory. All files that live
+in the source directory are checked into the CVS repository.
+
+@table @file
+@item bfd.h
+@cindex @file{bfd.h}
+@cindex @file{bfd-in3.h}
+Lives in the object directory. Created at make time from
+@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at
+configure time from @file{bfd-in2.h}. There are automatic dependencies
+to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h}
+changes, so you can normally ignore @file{bfd-in3.h}, and just think
+about @file{bfd-in2.h} and @file{bfd.h}.
+
+@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}.
+To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly
+control whether BFD is built for a 32 bit target or a 64 bit target.
+
+@item bfd-in2.h
+@cindex @file{bfd-in2.h}
+Lives in the source directory. Created from @file{bfd-in.h} and several
+other BFD source files. If you configure with the
+@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt
+automatically when a source file changes.
+
+@item elf32-target.h
+@itemx elf64-target.h
+@cindex @file{elf32-target.h}
+@cindex @file{elf64-target.h}
+Live in the object directory. Created from @file{elfxx-target.h}.
+These files are versions of @file{elfxx-target.h} customized for either
+a 32 bit ELF target or a 64 bit ELF target.
+
+@item libbfd.h
+@cindex @file{libbfd.h}
+Lives in the source directory. Created from @file{libbfd-in.h} and
+several other BFD source files. If you configure with the
+@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt
+automatically when a source file changes.
+
+@item libcoff.h
+@cindex @file{libcoff.h}
+Lives in the source directory. Created from @file{libcoff-in.h} and
+@file{coffcode.h}. If you configure with the
+@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt
+automatically when a source file changes.
+
+@item targmatch.h
+@cindex @file{targmatch.h}
+Lives in the object directory. Created at make time from
+@file{config.bfd}. This file is used to map configuration triplets into
+BFD target vector variable names at run time.
+@end table
+
+@node BFD multiple compilations
+@section Files compiled multiple times in BFD
+Several files in BFD are compiled multiple times. By this I mean that
+there are header files which contain function definitions. These header
+files are included by other files, and thus the functions are compiled
+once per file which includes them.
+
+Preprocessor macros are used to control the compilation, so that each
+time the files are compiled the resulting functions are slightly
+different. Naturally, if they weren't different, there would be no
+reason to compile them multiple times.
+
+This is a not a particularly good programming technique, and future BFD
+work should avoid it.
+
+@itemize @bullet
+@item
+Since this technique is rarely used, even experienced C programmers find
+it confusing.
+
+@item
+It is difficult to debug programs which use BFD, since there is no way
+to describe which version of a particular function you are looking at.
+
+@item
+Programs which use BFD wind up incorporating two or more slightly
+different versions of the same function, which wastes space in the
+executable.
+
+@item
+This technique is never required nor is it especially efficient. It is
+always possible to use statically initialized structures holding
+function pointers and magic constants instead.
+@end itemize
+
+The following is a list of the files which are compiled multiple times.
+
+@table @file
+@item aout-target.h
+@cindex @file{aout-target.h}
+Describes a few functions and the target vector for a.out targets. This
+is used by individual a.out targets with different definitions of
+@samp{N_TXTADDR} and similar a.out macros.
+
+@item aoutf1.h
+@cindex @file{aoutf1.h}
+Implements standard SunOS a.out files. In principle it supports 64 bit
+a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but
+since all known a.out targets are 32 bits, this code may or may not
+work. This file is only included by a few other files, and it is
+difficult to justify its existence.
+
+@item aoutx.h
+@cindex @file{aoutx.h}
+Implements basic a.out support routines. This file can be compiled for
+either 32 or 64 bit support. Since all known a.out targets are 32 bits,
+the 64 bit support may or may not work. I believe the original
+intention was that this file would only be included by @samp{aout32.c}
+and @samp{aout64.c}, and that other a.out targets would simply refer to
+the functions it defined. Unfortunately, some other a.out targets
+started including it directly, leading to a somewhat confused state of
+affairs.
+
+@item coffcode.h
+@cindex @file{coffcode.h}
+Implements basic COFF support routines. This file is included by every
+COFF target. It implements code which handles COFF magic numbers as
+well as various hook functions called by the generic COFF functions in
+@file{coffgen.c}. This file is controlled by a number of different
+macros, and more are added regularly.
+
+@item coffswap.h
+@cindex @file{coffswap.h}
+Implements COFF swapping routines. This file is included by
+@file{coffcode.h}, and thus by every COFF target. It implements the
+routines which swap COFF structures between internal and external
+format. The main control for this file is the external structure
+definitions in the files in the @file{include/coff} directory. A COFF
+target file will include one of those files before including
+@file{coffcode.h} and thus @file{coffswap.h}. There are a few other
+macros which affect @file{coffswap.h} as well, mostly describing whether
+certain fields are present in the external structures.
+
+@item ecoffswap.h
+@cindex @file{ecoffswap.h}
+Implements ECOFF swapping routines. This is like @file{coffswap.h}, but
+for ECOFF. It is included by the ECOFF target files (of which there are
+only two). The control is the preprocessor macro @samp{ECOFF_32} or
+@samp{ECOFF_64}.
+
+@item elfcode.h
+@cindex @file{elfcode.h}
+Implements ELF functions that use external structure definitions. This
+file is included by two other files: @file{elf32.c} and @file{elf64.c}.
+It is controlled by the @samp{ARCH_SIZE} macro which is defined to be
+@samp{32} or @samp{64} before including it. The @samp{NAME} macro is
+used internally to give the functions different names for the two target
+sizes.
+
+@item elfcore.h
+@cindex @file{elfcore.h}
+Like @file{elfcode.h}, but for functions that are specific to ELF core
+files. This is included only by @file{elfcode.h}.
+
+@item elflink.h
+@cindex @file{elflink.h}
+Like @file{elfcode.h}, but for functions used by the ELF linker. This
+is included only by @file{elfcode.h}.
+
+@item elfxx-target.h
+@cindex @file{elfxx-target.h}
+This file is the source for the generated files @file{elf32-target.h}
+and @file{elf64-target.h}, one of which is included by every ELF target.
+It defines the ELF target vector.
+
+@item freebsd.h
+@cindex @file{freebsd.h}
+Presumably intended to be included by all FreeBSD targets, but in fact
+there is only one such target, @samp{i386-freebsd}. This defines a
+function used to set the right magic number for FreeBSD, as well as
+various macros, and includes @file{aout-target.h}.
+
+@item netbsd.h
+@cindex @file{netbsd.h}
+Like @file{freebsd.h}, except that there are several files which include
+it.
+
+@item nlm-target.h
+@cindex @file{nlm-target.h}
+Defines the target vector for a standard NLM target.
+
+@item nlmcode.h
+@cindex @file{nlmcode.h}
+Like @file{elfcode.h}, but for NLM targets. This is only included by
+@file{nlm32.c} and @file{nlm64.c}, both of which define the macro
+@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM
+targets anyhow, so this is sort of useless.
+
+@item nlmswap.h
+@cindex @file{nlmswap.h}
+Like @file{coffswap.h}, but for NLM targets. This is included by each
+NLM target, but I think it winds up compiling to the exact same code for
+every target, and as such is fairly useless.
+
+@item peicode.h
+@cindex @file{peicode.h}
+Provides swapping routines and other hooks for PE targets.
+@file{coffcode.h} will include this rather than @file{coffswap.h} for a
+PE target. This defines PE specific versions of the COFF swapping
+routines, and also defines some macros which control @file{coffcode.h}
+itself.
+@end table
+
+@node BFD relocation handling
+@section BFD relocation handling
+@cindex bfd relocation handling
+@cindex relocations in bfd
+
+The handling of relocations is one of the more confusing aspects of BFD.
+Relocation handling has been implemented in various different ways, all
+somewhat incompatible, none perfect.
+
+@menu
+* BFD relocation concepts:: BFD relocation concepts
+* BFD relocation functions:: BFD relocation functions
+* BFD relocation codes:: BFD relocation codes
+* BFD relocation future:: BFD relocation future
+@end menu
+
+@node BFD relocation concepts
+@subsection BFD relocation concepts
+
+A relocation is an action which the linker must take when linking. It
+describes a change to the contents of a section. The change is normally
+based on the final value of one or more symbols. Relocations are
+created by the assembler when it creates an object file.
+
+Most relocations are simple. A typical simple relocation is to set 32
+bits at a given offset in a section to the value of a symbol. This type
+of relocation would be generated for code like @code{int *p = &i;} where
+@samp{p} and @samp{i} are global variables. A relocation for the symbol
+@samp{i} would be generated such that the linker would initialize the
+area of memory which holds the value of @samp{p} to the value of the
+symbol @samp{i}.
+
+Slightly more complex relocations may include an addend, which is a
+constant to add to the symbol value before using it. In some cases a
+relocation will require adding the symbol value to the existing contents
+of the section in the object file. In others the relocation will simply
+replace the contents of the section with the symbol value. Some
+relocations are PC relative, so that the value to be stored in the
+section is the difference between the value of a symbol and the final
+address of the section contents.
+
+In general, relocations can be arbitrarily complex. For example,
+relocations used in dynamic linking systems often require the linker to
+allocate space in a different section and use the offset within that
+section as the value to store. In the IEEE object file format,
+relocations may involve arbitrary expressions.
+
+When doing a relocateable link, the linker may or may not have to do
+anything with a relocation, depending upon the definition of the
+relocation. Simple relocations generally do not require any special
+action.
+
+@node BFD relocation functions
+@subsection BFD relocation functions
+
+In BFD, each section has an array of @samp{arelent} structures. Each
+structure has a pointer to a symbol, an address within the section, an
+addend, and a pointer to a @samp{reloc_howto_struct} structure. The
+howto structure has a bunch of fields describing the reloc, including a
+type field. The type field is specific to the object file format
+backend; none of the generic code in BFD examines it.
+
+Originally, the function @samp{bfd_perform_relocation} was supposed to
+handle all relocations. In theory, many relocations would be simple
+enough to be described by the fields in the howto structure. For those
+that weren't, the howto structure included a @samp{special_function}
+field to use as an escape.
+
+While this seems plausible, a look at @samp{bfd_perform_relocation}
+shows that it failed. The function has odd special cases. Some of the
+fields in the howto structure, such as @samp{pcrel_offset}, were not
+adequately documented.
+
+The linker uses @samp{bfd_perform_relocation} to do all relocations when
+the input and output file have different formats (e.g., when generating
+S-records). The generic linker code, which is used by all targets which
+do not define their own special purpose linker, uses
+@samp{bfd_get_relocated_section_contents}, which for most targets turns
+into a call to @samp{bfd_generic_get_relocated_section_contents}, which
+calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation}
+is still widely used, which makes it difficult to change, since it is
+difficult to test all possible cases.
+
+The assembler used @samp{bfd_perform_relocation} for a while. This
+turned out to be the wrong thing to do, since
+@samp{bfd_perform_relocation} was written to handle relocations on an
+existing object file, while the assembler needed to create relocations
+in a new object file. The assembler was changed to use the new function
+@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation}
+was created as a copy of @samp{bfd_perform_relocation}.
+
+Unfortunately, the work did not progress any farther, so
+@samp{bfd_install_relocation} remains a simple copy of
+@samp{bfd_perform_relocation}, with all the odd special cases and
+confusing code. This again is difficult to change, because again any
+change can affect any assembler target, and so is difficult to test.
+
+The new linker, when using the same object file format for all input
+files and the output file, does not convert relocations into
+@samp{arelent} structures, so it can not use
+@samp{bfd_perform_relocation} at all. Instead, users of the new linker
+are expected to write a @samp{relocate_section} function which will
+handle relocations in a target specific fashion.
+
+There are two helper functions for target specific relocation:
+@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}.
+These functions use a howto structure, but they @emph{do not} use the
+@samp{special_function} field. Since the functions are normally called
+from target specific code, the @samp{special_function} field adds
+little; any relocations which require special handling can be handled
+without calling those functions.
+
+So, if you want to add a new target, or add a new relocation to an
+existing target, you need to do the following:
+
+@itemize @bullet
+@item
+Make sure you clearly understand what the contents of the section should
+look like after assembly, after a relocateable link, and after a final
+link. Make sure you clearly understand the operations the linker must
+perform during a relocateable link and during a final link.
+
+@item
+Write a howto structure for the relocation. The howto structure is
+flexible enough to represent any relocation which should be handled by
+setting a contiguous bitfield in the destination to the value of a
+symbol, possibly with an addend, possibly adding the symbol value to the
+value already present in the destination.
+
+@item
+Change the assembler to generate your relocation. The assembler will
+call @samp{bfd_install_relocation}, so your howto structure has to be
+able to handle that. You may need to set the @samp{special_function}
+field to handle assembly correctly. Be careful to ensure that any code
+you write to handle the assembler will also work correctly when doing a
+relocateable link. For example, see @samp{bfd_elf_generic_reloc}.
+
+@item
+Test the assembler. Consider the cases of relocation against an
+undefined symbol, a common symbol, a symbol defined in the object file
+in the same section, and a symbol defined in the object file in a
+different section. These cases may not all be applicable for your
+reloc.
+
+@item
+If your target uses the new linker, which is recommended, add any
+required handling to the target specific relocation function. In simple
+cases this will just involve a call to @samp{_bfd_final_link_relocate}
+or @samp{_bfd_relocate_contents}, depending upon the definition of the
+relocation and whether the link is relocateable or not.
+
+@item
+Test the linker. Test the case of a final link. If the relocation can
+overflow, use a linker script to force an overflow and make sure the
+error is reported correctly. Test a relocateable link, whether the
+symbol is defined or undefined in the relocateable output. For both the
+final and relocateable link, test the case when the symbol is a common
+symbol, when the symbol looked like a common symbol but became a defined
+symbol, when the symbol is defined in a different object file, and when
+the symbol is defined in the same object file.
+
+@item
+In order for linking to another object file format, such as S-records,
+to work correctly, @samp{bfd_perform_relocation} has to do the right
+thing for the relocation. You may need to set the
+@samp{special_function} field to handle this correctly. Test this by
+doing a link in which the output object file format is S-records.
+
+@item
+Using the linker to generate relocateable output in a different object
+file format is impossible in the general case, so you generally don't
+have to worry about that. Linking input files of different object file
+formats together is quite unusual, but if you're really dedicated you
+may want to consider testing this case, both when the output object file
+format is the same as your format, and when it is different.
+@end itemize
+
+@node BFD relocation codes
+@subsection BFD relocation codes
+
+BFD has another way of describing relocations besides the howto
+structures described above: the enum @samp{bfd_reloc_code_real_type}.
+
+Every known relocation type can be described as a value in this
+enumeration. The enumeration contains many target specific relocations,
+but where two or more targets have the same relocation, a single code is
+used. For example, the single value @samp{BFD_RELOC_32} is used for all
+simple 32 bit relocation types.
+
+The main purpose of this relocation code is to give the assembler some
+mechanism to create @samp{arelent} structures. In order for the
+assembler to create an @samp{arelent} structure, it has to be able to
+obtain a howto structure. The function @samp{bfd_reloc_type_lookup},
+which simply calls the target vector entry point
+@samp{reloc_type_lookup}, takes a relocation code and returns a howto
+structure.
+
+The function @samp{bfd_get_reloc_code_name} returns the name of a
+relocation code. This is mainly used in error messages.
+
+Using both howto structures and relocation codes can be somewhat
+confusing. There are many processor specific relocation codes.
+However, the relocation is only fully defined by the howto structure.
+The same relocation code will map to different howto structures in
+different object file formats. For example, the addend handling may be
+different.
+
+Most of the relocation codes are not really general. The assembler can
+not use them without already understanding what sorts of relocations can
+be used for a particular target. It might be possible to replace the
+relocation codes with something simpler.
+
+@node BFD relocation future
+@subsection BFD relocation future
+
+Clearly the current BFD relocation support is in bad shape. A
+wholescale rewrite would be very difficult, because it would require
+thorough testing of every BFD target. So some sort of incremental
+change is required.
+
+My vague thoughts on this would involve defining a new, clearly defined,
+howto structure. Some mechanism would be used to determine which type
+of howto structure was being used by a particular format.
+
+The new howto structure would clearly define the relocation behaviour in
+the case of an assembly, a relocateable link, and a final link. At
+least one special function would be defined as an escape, and it might
+make sense to define more.
+
+One or more generic functions similar to @samp{bfd_perform_relocation}
+would be written to handle the new howto structure.
+
+This should make it possible to write a generic version of the relocate
+section functions used by the new linker. The target specific code
+would provide some mechanism (a function pointer or an initial
+conversion) to convert target specific relocations into howto
+structures.
+
+Ideally it would be possible to use this generic relocate section
+function for the generic linker as well. That is, it would replace the
+@samp{bfd_generic_get_relocated_section_contents} function which is
+currently normally used.
+
+For the special case of ELF dynamic linking, more consideration needs to
+be given to writing ELF specific but ELF target generic code to handle
+special relocation types such as GOT and PLT.
+
+@node BFD ELF support
+@section BFD ELF support
+@cindex elf support in bfd
+@cindex bfd elf support
+
+The ELF object file format is defined in two parts: a generic ABI and a
+processor specific supplement. The ELF support in BFD is split in a
+similar fashion. The processor specific support is largely kept within
+a single file. The generic support is provided by several other files.
+The processor specific support provides a set of function pointers and
+constants used by the generic support.
+
+@menu
+* BFD ELF sections and segments:: ELF sections and segments
+* BFD ELF generic support:: BFD ELF generic support
+* BFD ELF processor specific support:: BFD ELF processor specific support
+* BFD ELF core files:: BFD ELF core files
+* BFD ELF future:: BFD ELF future
+@end menu
+
+@node BFD ELF sections and segments
+@subsection ELF sections and segments
+
+The ELF ABI permits a file to have either sections or segments or both.
+Relocateable object files conventionally have only sections.
+Executables conventionally have both. Core files conventionally have
+only program segments.
+
+ELF sections are similar to sections in other object file formats: they
+have a name, a VMA, file contents, flags, and other miscellaneous
+information. ELF relocations are stored in sections of a particular
+type; BFD automatically converts these sections into internal relocation
+information.
+
+ELF program segments are intended for fast interpretation by a system
+loader. They have a type, a VMA, an LMA, file contents, and a couple of
+other fields. When an ELF executable is run on a Unix system, the
+system loader will examine the program segments to decide how to load
+it. The loader will ignore the section information. Loadable program
+segments (type @samp{PT_LOAD}) are directly loaded into memory. Other
+program segments are interpreted by the loader, and generally provide
+dynamic linking information.
+
+When an ELF file has both program segments and sections, an ELF program
+segment may encompass one or more ELF sections, in the sense that the
+portion of the file which corresponds to the program segment may include
+the portions of the file corresponding to one or more sections. When
+there is more than one section in a loadable program segment, the
+relative positions of the section contents in the file must correspond
+to the relative positions they should hold when the program segment is
+loaded. This requirement should be obvious if you consider that the
+system loader will load an entire program segment at a time.
+
+On a system which supports dynamic paging, such as any native Unix
+system, the contents of a loadable program segment must be at the same
+offset in the file as in memory, modulo the memory page size used on the
+system. This is because the system loader will map the file into memory
+starting at the start of a page. The system loader can easily remap
+entire pages to the correct load address. However, if the contents of
+the file were not correctly aligned within the page, the system loader
+would have to shift the contents around within the page, which is too
+expensive. For example, if the LMA of a loadable program segment is
+@samp{0x40080} and the page size is @samp{0x1000}, then the position of
+the segment contents within the file must equal @samp{0x80} modulo
+@samp{0x1000}.
+
+BFD has only a single set of sections. It does not provide any generic
+way to examine both sections and segments. When BFD is used to open an
+object file or executable, the BFD sections will represent ELF sections.
+When BFD is used to open a core file, the BFD sections will represent
+ELF program segments.
+
+When BFD is used to examine an object file or executable, any program
+segments will be read to set the LMA of the sections. This is because
+ELF sections only have a VMA, while ELF program segments have both a VMA
+and an LMA. Any program segments will be copied by the
+@samp{copy_private} entry points. They will be printed by the
+@samp{print_private} entry point. Otherwise, the program segments are
+ignored. In particular, programs which use BFD currently have no direct
+access to the program segments.
+
+When BFD is used to create an executable, the program segments will be
+created automatically based on the section information. This is done in
+the function @samp{assign_file_positions_for_segments} in @file{elf.c}.
+This function has been tweaked many times, and probably still has
+problems that arise in particular cases.
+
+There is a hook which may be used to explicitly define the program
+segments when creating an executable: the @samp{bfd_record_phdr}
+function in @file{bfd.c}. If this function is called, BFD will not
+create program segments itself, but will only create the program
+segments specified by the caller. The linker uses this function to
+implement the @samp{PHDRS} linker script command.
+
+@node BFD ELF generic support
+@subsection BFD ELF generic support
+
+In general, functions which do not read external data from the ELF file
+are found in @file{elf.c}. They operate on the internal forms of the
+ELF structures, which are defined in @file{include/elf/internal.h}. The
+internal structures are defined in terms of @samp{bfd_vma}, and so may
+be used for both 32 bit and 64 bit ELF targets.
+
+The file @file{elfcode.h} contains functions which operate on the
+external data. @file{elfcode.h} is compiled twice, once via
+@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via
+@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}.
+@file{elfcode.h} includes functions to swap the ELF structures in and
+out of external form, as well as a few more complex functions.
+
+Linker support is found in @file{elflink.c} and @file{elflink.h}. The
+latter file is compiled twice, for both 32 and 64 bit support. The
+linker support is only used if the processor specific file defines
+@samp{elf_backend_relocate_section}, which is required to relocate the
+section contents. If that macro is not defined, the generic linker code
+is used, and relocations are handled via @samp{bfd_perform_relocation}.
+
+The core file support is in @file{elfcore.h}, which is compiled twice,
+for both 32 and 64 bit support. The more interesting cases of core file
+support only work on a native system which has the @file{sys/procfs.h}
+header file. Without that file, the core file support does little more
+than read the ELF program segments as BFD sections.
+
+The BFD internal header file @file{elf-bfd.h} is used for communication
+among these files and the processor specific files.
+
+The default entries for the BFD ELF target vector are found mainly in
+@file{elf.c}. Some functions are found in @file{elfcode.h}.
+
+The processor specific files may override particular entries in the
+target vector, but most do not, with one exception: the
+@samp{bfd_reloc_type_lookup} entry point is always processor specific.
+
+@node BFD ELF processor specific support
+@subsection BFD ELF processor specific support
+
+By convention, the processor specific support for a particular processor
+will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is
+either 32 or 64, and @var{cpu} is the name of the processor.
+
+@menu
+* BFD ELF processor required:: Required processor specific support
+* BFD ELF processor linker:: Processor specific linker support
+* BFD ELF processor other:: Other processor specific support options
+@end menu
+
+@node BFD ELF processor required
+@subsubsection Required processor specific support
+
+When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the
+following:
+
+@itemize @bullet
+@item
+Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or
+both, to a unique C name to use for the target vector. This name should
+appear in the list of target vectors in @file{targets.c}, and will also
+have to appear in @file{config.bfd} and @file{configure.in}. Define
+@samp{TARGET_BIG_SYM} for a big-endian processor,
+@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both
+for a bi-endian processor.
+@item
+Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or
+both, to a string used as the name of the target vector. This is the
+name which a user of the BFD tool would use to specify the object file
+format. It would normally appear in a linker emulation parameters
+file.
+@item
+Define @samp{ELF_ARCH} to the BFD architecture (an element of the
+@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}).
+@item
+Define @samp{ELF_MACHINE_CODE} to the magic number which should appear
+in the @samp{e_machine} field of the ELF header. As of this writing,
+these magic numbers are assigned by SCO; if you want to get a magic
+number for a particular processor, try sending a note to
+@email{registry@@sco.com}. In the BFD sources, the magic numbers are
+found in @file{include/elf/common.h}; they have names beginning with
+@samp{EM_}.
+@item
+Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in
+memory. This can normally be found at the start of chapter 5 in the
+processor specific supplement. For a processor which will only be used
+in an embedded system, or which has no memory management hardware, this
+can simply be @samp{1}.
+@item
+If the format should use @samp{Rel} rather than @samp{Rela} relocations,
+define @samp{USE_REL}. This is normally defined in chapter 4 of the
+processor specific supplement.
+
+In the absence of a supplement, it's easier to work with @samp{Rela}
+relocations. @samp{Rela} relocations will require more space in object
+files (but not in executables, except when using dynamic linking).
+However, this is outweighed by the simplicity of addend handling when
+using @samp{Rela} relocations. With @samp{Rel} relocations, the addend
+must be stored in the section contents, which makes relocateable links
+more complex.
+
+For example, consider C code like @code{i = a[1000];} where @samp{a} is
+a global array. The instructions which load the value of @samp{a[1000]}
+will most likely use a relocation which refers to the symbol
+representing @samp{a}, with an addend that gives the offset from the
+start of @samp{a} to element @samp{1000}. When using @samp{Rel}
+relocations, that addend must be stored in the instructions themselves.
+If you are adding support for a RISC chip which uses two or more
+instructions to load an address, then the addend may not fit in a single
+instruction, and will have to be somehow split among the instructions.
+This makes linking awkward, particularly when doing a relocateable link
+in which the addend may have to be updated. It can be done---the MIPS
+ELF support does it---but it should be avoided when possible.
+
+It is possible, though somewhat awkward, to support both @samp{Rel} and
+@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it
+by overriding the relocation reading and writing routines.
+@item
+Define howto structures for all the relocation types.
+@item
+Define a @samp{bfd_reloc_type_lookup} routine. This must be named
+@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a
+function or a macro. It must translate a BFD relocation code into a
+howto structure. This is normally a table lookup or a simple switch.
+@item
+If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}.
+If using @samp{Rela} relocations, define @samp{elf_info_to_howto}.
+Either way, this is a macro defined as the name of a function which
+takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and
+sets the @samp{howto} field of the @samp{arelent} based on the
+@samp{Rel} or @samp{Rela} structure. This is normally uses
+@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as
+an index into a table of howto structures.
+@end itemize
+
+You must also add the magic number for this processor to the
+@samp{prep_headers} function in @file{elf.c}.
+
+You must also create a header file in the @file{include/elf} directory
+called @file{@var{cpu}.h}. This file should define any target specific
+information which may be needed outside of the BFD code. In particular
+it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER},
+@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS}
+macros to create a table mapping the number used to indentify a
+relocation to a name describing that relocation.
+
+@node BFD ELF processor linker
+@subsubsection Processor specific linker support
+
+The linker will be much more efficient if you define a relocate section
+function. This will permit BFD to use the ELF specific linker support.
+
+If you do not define a relocate section function, BFD must use the
+generic linker support, which requires converting all symbols and
+relocations into BFD @samp{asymbol} and @samp{arelent} structures. In
+this case, relocations will be handled by calling
+@samp{bfd_perform_relocation}, which will use the howto structures you
+have defined. @xref{BFD relocation handling}.
+
+In order to support linking into a different object file format, such as
+S-records, @samp{bfd_perform_relocation} must work correctly with your
+howto structures, so you can't skip that step. However, if you define
+the relocate section function, then in the normal case of linking into
+an ELF file the linker will not need to convert symbols and relocations,
+and will be much more efficient.
+
+To use a relocation section function, define the macro
+@samp{elf_backend_relocate_section} as the name of a function which will
+take the contents of a section, as well as relocation, symbol, and other
+information, and modify the section contents according to the relocation
+information. In simple cases, this is little more than a loop over the
+relocations which computes the value of each relocation and calls
+@samp{_bfd_final_link_relocate}. The function must check for a
+relocateable link, and in that case normally needs to do nothing other
+than adjust the addend for relocations against a section symbol.
+
+The complex cases generally have to do with dynamic linker support. GOT
+and PLT relocations must be handled specially, and the linker normally
+arranges to set up the GOT and PLT sections while handling relocations.
+When generating a shared library, random relocations must normally be
+copied into the shared library, or converted to RELATIVE relocations
+when possible.
+
+@node BFD ELF processor other
+@subsubsection Other processor specific support options
+
+There are many other macros which may be defined in
+@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in
+@file{elfxx-target.h}.
+
+Macros may be used to override some of the generic ELF target vector
+functions.
+
+Several processor specific hook functions which may be defined as
+macros. These functions are found as function pointers in the
+@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In
+general, a hook function is set by defining a macro
+@samp{elf_backend_@var{name}}.
+
+There are a few processor specific constants which may also be defined.
+These are again found in the @samp{elf_backend_data} structure.
+
+I will not define the various functions and constants here; see the
+comments in @file{elf-bfd.h}.
+
+Normally any odd characteristic of a particular ELF processor is handled
+via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON}
+section number found in MIPS ELF is handled via the hooks
+@samp{section_from_bfd_section}, @samp{symbol_processing},
+@samp{add_symbol_hook}, and @samp{output_symbol_hook}.
+
+Dynamic linking support, which involves processor specific relocations
+requiring special handling, is also implemented via hook functions.
+
+@node BFD ELF core files
+@subsection BFD ELF core files
+@cindex elf core files
+
+On native ELF Unix systems, core files are generated without any
+sections. Instead, they only have program segments.
+
+When BFD is used to read an ELF core file, the BFD sections will
+actually represent program segments. Since ELF program segments do not
+have names, BFD will invent names like @samp{segment@var{n}} where
+@var{n} is a number.
+
+A single ELF program segment may include both an initialized part and an
+uninitialized part. The size of the initialized part is given by the
+@samp{p_filesz} field. The total size of the segment is given by the
+@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz},
+then the extra space is uninitialized, or, more precisely, initialized
+to zero.
+
+BFD will represent such a program segment as two different sections.
+The first, named @samp{segment@var{n}a}, will represent the initialized
+part of the program segment. The second, named @samp{segment@var{n}b},
+will represent the uninitialized part.
+
+ELF core files store special information such as register values in
+program segments with the type @samp{PT_NOTE}. BFD will attempt to
+interpret the information in these segments, and will create additional
+sections holding the information. Some of this interpretation requires
+information found in the host header file @file{sys/procfs.h}, and so
+will only work when BFD is built on a native system.
+
+BFD does not currently provide any way to create an ELF core file. In
+general, BFD does not provide a way to create core files. The way to
+implement this would be to write @samp{bfd_set_format} and
+@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see
+@ref{BFD target vector format}.
+
+@node BFD ELF future
+@subsection BFD ELF future
+
+The current dynamic linking support has too much code duplication.
+While each processor has particular differences, much of the dynamic
+linking support is quite similar for each processor. The GOT and PLT
+are handled in fairly similar ways, the details of -Bsymbolic linking
+are generally similar, etc. This code should be reworked to use more
+generic functions, eliminating the duplication.
+
+Similarly, the relocation handling has too much duplication. Many of
+the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are
+quite similar. The relocate section functions are also often quite
+similar, both in the standard linker handling and the dynamic linker
+handling. Many of the COFF processor specific backends share a single
+relocate section function (@samp{_bfd_coff_generic_relocate_section}),
+and it should be possible to do something like this for the ELF targets
+as well.
+
+The appearance of the processor specific magic number in
+@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be
+possible to add support for a new processor without changing the generic
+support.
+
+The processor function hooks and constants are ad hoc and need better
+documentation.
+
+When a linker script uses @samp{SIZEOF_HEADERS}, the ELF backend must
+guess at the number of program segments which will be required, in
+@samp{get_program_header_size}. This is because the linker calls
+@samp{bfd_sizeof_headers} before it knows all the section addresses and
+sizes. The ELF backend may later discover, when creating program
+segments, that more program segments are required. This is currently
+reported as an error in @samp{assign_file_positions_for_segments}.
+
+In practice this makes it difficult to use @samp{SIZEOF_HEADERS} except
+with a carefully defined linker script. Unfortunately,
+@samp{SIZEOF_HEADERS} is required for fast program loading on a native
+system, since it permits the initial code section to appear on the same
+page as the program segments, saving a page read when the program starts
+running. Fortunately, native systems permit careful definition of the
+linker script. Still, ideally it would be possible to use relaxation to
+compute the number of program segments.
+
+@node BFD glossary
+@section BFD glossary
+@cindex glossary for bfd
+@cindex bfd glossary
+
+This is a short glossary of some BFD terms.
+
+@table @asis
+@item a.out
+The a.out object file format. The original Unix object file format.
+Still used on SunOS, though not Solaris. Supports only three sections.
+
+@item archive
+A collection of object files produced and manipulated by the @samp{ar}
+program.
+
+@item backend
+The implementation within BFD of a particular object file format. The
+set of functions which appear in a particular target vector.
+
+@item BFD
+The BFD library itself. Also, each object file, archive, or exectable
+opened by the BFD library has the type @samp{bfd *}, and is sometimes
+referred to as a bfd.
+
+@item COFF
+The Common Object File Format. Used on Unix SVR3. Used by some
+embedded targets, although ELF is normally better.
+
+@item DLL
+A shared library on Windows.
+
+@item dynamic linker
+When a program linked against a shared library is run, the dynamic
+linker will locate the appropriate shared library and arrange to somehow
+include it in the running image.
+
+@item dynamic object
+Another name for an ELF shared library.
+
+@item ECOFF
+The Extended Common Object File Format. Used on Alpha Digital Unix
+(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF.
+
+@item ELF
+The Executable and Linking Format. The object file format used on most
+modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also
+used on many embedded systems.
+
+@item executable
+A program, with instructions and symbols, and perhaps dynamic linking
+information. Normally produced by a linker.
+
+@item LMA
+Load Memory Address. This is the address at which a section will be
+loaded. Compare with VMA, below.
+
+@item NLM
+NetWare Loadable Module. Used to describe the format of an object which
+be loaded into NetWare, which is some kind of PC based network server
+program.
+
+@item object file
+A binary file including machine instructions, symbols, and relocation
+information. Normally produced by an assembler.
+
+@item object file format
+The format of an object file. Typically object files and executables
+for a particular system are in the same format, although executables
+will not contain any relocation information.
+
+@item PE
+The Portable Executable format. This is the object file format used for
+Windows (specifically, Win32) object files. It is based closely on
+COFF, but has a few significant differences.
+
+@item PEI
+The Portable Executable Image format. This is the object file format
+used for Windows (specifically, Win32) executables. It is very similar
+to PE, but includes some additional header information.
+
+@item relocations
+Information used by the linker to adjust section contents. Also called
+relocs.
+
+@item section
+Object files and executable are composed of sections. Sections have
+optional data and optional relocation information.
+
+@item shared library
+A library of functions which may be used by many executables without
+actually being linked into each executable. There are several different
+implementations of shared libraries, each having slightly different
+features.
+
+@item symbol
+Each object file and executable may have a list of symbols, often
+referred to as the symbol table. A symbol is basically a name and an
+address. There may also be some additional information like the type of
+symbol, although the type of a symbol is normally something simple like
+function or object, and should be confused with the more complex C
+notion of type. Typically every global function and variable in a C
+program will have an associated symbol.
+
+@item target vector
+A set of functions which implement support for a particular object file
+format. The @samp{bfd_target} structure.
+
+@item Win32
+The current Windows API, implemented by Windows 95 and later and Windows
+NT 3.51 and later, but not by Windows 3.1.
+
+@item XCOFF
+The eXtended Common Object File Format. Used on AIX. A variant of
+COFF, with a completely different symbol table implementation.
+
+@item VMA
+Virtual Memory Address. This is the address a section will have when
+an executable is run. Compare with LMA, above.
+@end table
+
+@node Index
+@unnumberedsec Index
+@printindex cp
+
+@contents
+@bye
diff --git a/bfd/doc/bfdsumm.texi b/bfd/doc/bfdsumm.texi
new file mode 100644
index 0000000..844531a
--- /dev/null
+++ b/bfd/doc/bfdsumm.texi
@@ -0,0 +1,148 @@
+@c This summary of BFD is shared by the BFD and LD docs.
+When an object file is opened, BFD subroutines automatically determine
+the format of the input object file. They then build a descriptor in
+memory with pointers to routines that will be used to access elements of
+the object file's data structures.
+
+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 a memory pointer to the routine from the
+relevant BFD back end 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 to take the newly
+created symbol table and convert it into the chosen output format.
+
+@menu
+* BFD information loss:: Information Loss
+* Canonical format:: The BFD canonical object-file format
+@end menu
+
+@node BFD information loss
+@subsection Information Loss
+
+@emph{Information can be lost during output.} The output formats
+supported by BFD do not provide identical facilities, and
+information which can 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 (e.g.,
+@code{a.out}) or has sections without names (e.g., 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,
+there is no information lost 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 Canonical format
+@subsection The BFD canonical object-file format
+
+The greatest potential for loss of information occurs when there is the least
+overlap between the information provided by the source format, that
+stored by the canonical format, and that needed by the
+destination format. A brief description of the canonical form may help
+you understand which kinds of data you can count on preserving across
+conversions.
+@cindex BFD canonical format
+@cindex internal object-file format
+
+@table @emph
+@item files
+Information stored on a per-file basis includes target machine
+architecture, particular implementation format type, a demand pageable
+bit, and a write protected bit. 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 used with one
+another.
+
+@item sections
+Each section in the input file contains the name of the section, the
+section's original address in the object file, size and alignment
+information, various flags, and pointers into other BFD data
+structures.
+
+@item symbols
+Each symbol contains a pointer to the information for 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, it relocates all
+symbols to make them relative to the base of the section where they were
+defined. Doing this ensures that each symbol points to its containing
+section. Each symbol also has a varying amount of hidden 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{ld} 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 by passing messages through the relocation type
+descriptor and the symbol pointer. Therefore, relocations can be performed
+on output data using a relocation method that is 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 68k 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 finding out 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
diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
new file mode 100644
index 0000000..eba69c2
--- /dev/null
+++ b/bfd/doc/chew.c
@@ -0,0 +1,1579 @@
+/* chew
+ Copyright (C) 1990, 91, 92, 93, 94, 95, 96, 1998
+ Free Software Foundation, Inc.
+ Contributed by steve chamberlain @cygnus
+
+This file is part of BFD, the Binary File Descriptor library.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
+
+/* Yet another way of extracting documentation from source.
+ No, I haven't finished it yet, but I hope you people like it better
+ than the old way
+
+ sac
+
+ Basically, this is a sort of string forth, maybe we should call it
+ struth?
+
+ You define new words thus:
+ : <newword> <oldwords> ;
+
+*/
+
+/* Primitives provided by the program:
+
+ Two stacks are provided, a string stack and an integer stack.
+
+ Internal state variables:
+ internal_wanted - indicates whether `-i' was passed
+ internal_mode - user-settable
+
+ Commands:
+ push_text
+ ! - pop top of integer stack for address, pop next for value; store
+ @ - treat value on integer stack as the address of an integer; push
+ that integer on the integer stack after popping the "address"
+ hello - print "hello\n" to stdout
+ stdout - put stdout marker on TOS
+ stderr - put stderr marker on TOS
+ print - print TOS-1 on TOS (eg: "hello\n" stdout print)
+ skip_past_newline
+ catstr - fn icatstr
+ copy_past_newline - append input, up to and including newline into TOS
+ dup - fn other_dup
+ drop - discard TOS
+ idrop - ditto
+ remchar - delete last character from TOS
+ get_stuff_in_command
+ do_fancy_stuff - translate <<foo>> to @code{foo} in TOS
+ bulletize - if "o" lines found, prepend @itemize @bullet to TOS
+ and @item to each "o" line; append @end itemize
+ courierize - put @example around . and | lines, translate {* *} { }
+ exit - fn chew_exit
+ swap
+ outputdots - strip out lines without leading dots
+ paramstuff - convert full declaration into "PARAMS" form if not already
+ maybecatstr - do catstr if internal_mode == internal_wanted, discard
+ value in any case
+ translatecomments - turn {* and *} into comment delimiters
+ kill_bogus_lines - get rid of extra newlines
+ indent
+ internalmode - pop from integer stack, set `internalmode' to that value
+ print_stack_level - print current stack depth to stderr
+ strip_trailing_newlines - go ahead, guess...
+ [quoted string] - push string onto string stack
+ [word starting with digit] - push atol(str) onto integer stack
+
+ A command must be all upper-case, and alone on a line.
+
+ Foo. */
+
+
+#include <ansidecl.h>
+#include "sysdep.h"
+#include <assert.h>
+#include <stdio.h>
+#include <ctype.h>
+
+#define DEF_SIZE 5000
+#define STACK 50
+
+int internal_wanted;
+int internal_mode;
+
+int warning;
+
+/* Here is a string type ... */
+
+typedef struct buffer
+{
+ char *ptr;
+ unsigned long write_idx;
+ unsigned long size;
+} string_type;
+
+
+#ifdef __STDC__
+static void init_string_with_size (string_type *, unsigned int);
+static void init_string (string_type *);
+static int find (string_type *, char *);
+static void write_buffer (string_type *, FILE *);
+static void delete_string (string_type *);
+static char *addr (string_type *, unsigned int);
+static char at (string_type *, unsigned int);
+static void catchar (string_type *, int);
+static void overwrite_string (string_type *, string_type *);
+static void catbuf (string_type *, char *, unsigned int);
+static void cattext (string_type *, char *);
+static void catstr (string_type *, string_type *);
+#endif
+
+
+static void DEFUN(init_string_with_size,(buffer, size),
+ string_type *buffer AND
+ unsigned int size )
+{
+ buffer->write_idx = 0;
+ buffer->size = size;
+ buffer->ptr = malloc(size);
+}
+
+static void DEFUN(init_string,(buffer),
+ string_type *buffer)
+{
+ init_string_with_size(buffer, DEF_SIZE);
+
+}
+
+static int DEFUN(find, (str, what),
+ string_type *str AND
+ char *what)
+{
+ unsigned int i;
+ char *p;
+ p = what;
+ for (i = 0; i < str->write_idx && *p; i++)
+ {
+ if (*p == str->ptr[i])
+ p++;
+ else
+ p = what;
+ }
+ return (*p == 0);
+
+}
+
+static void DEFUN(write_buffer,(buffer, f),
+ string_type *buffer AND
+ FILE *f)
+{
+ fwrite(buffer->ptr, buffer->write_idx, 1, f);
+}
+
+
+static void DEFUN(delete_string,(buffer),
+ string_type *buffer)
+{
+ free(buffer->ptr);
+}
+
+
+static char *DEFUN(addr, (buffer, idx),
+ string_type *buffer AND
+ unsigned int idx)
+{
+ return buffer->ptr + idx;
+}
+
+static char DEFUN(at,(buffer, pos),
+ string_type *buffer AND
+ unsigned int pos)
+{
+ if (pos >= buffer->write_idx)
+ return 0;
+ return buffer->ptr[pos];
+}
+
+static void DEFUN(catchar,(buffer, ch),
+ string_type *buffer AND
+ int ch)
+{
+ if (buffer->write_idx == buffer->size)
+ {
+ buffer->size *=2;
+ buffer->ptr = realloc(buffer->ptr, buffer->size);
+ }
+
+ buffer->ptr[buffer->write_idx ++ ] = ch;
+}
+
+
+static void DEFUN(overwrite_string,(dst, src),
+ string_type *dst AND
+ string_type *src)
+{
+ free(dst->ptr);
+ dst->size = src->size;
+ dst->write_idx = src->write_idx;
+ dst->ptr = src->ptr;
+}
+
+static void DEFUN(catbuf,(buffer, buf, len),
+ string_type *buffer AND
+ char *buf AND
+ unsigned int len)
+{
+ if (buffer->write_idx + len >= buffer->size)
+ {
+ while (buffer->write_idx + len >= buffer->size)
+ buffer->size *= 2;
+ buffer->ptr = realloc (buffer->ptr, buffer->size);
+ }
+ memcpy (buffer->ptr + buffer->write_idx, buf, len);
+ buffer->write_idx += len;
+}
+
+static void DEFUN(cattext,(buffer, string),
+ string_type *buffer AND
+ char *string)
+{
+ catbuf (buffer, string, (unsigned int) strlen (string));
+}
+
+static void DEFUN(catstr,(dst, src),
+ string_type *dst AND
+ string_type *src)
+{
+ catbuf (dst, src->ptr, src->write_idx);
+}
+
+
+static unsigned int
+DEFUN(skip_white_and_stars,(src, idx),
+ string_type *src AND
+ unsigned int idx)
+{
+ char c;
+ while ((c = at(src,idx)),
+ isspace ((unsigned char) c)
+ || (c == '*'
+ /* Don't skip past end-of-comment or star as first
+ character on its line. */
+ && at(src,idx +1) != '/'
+ && at(src,idx -1) != '\n'))
+ idx++;
+ return idx;
+}
+
+/***********************************************************************/
+
+
+string_type stack[STACK];
+string_type *tos;
+
+unsigned int idx = 0; /* Pos in input buffer */
+string_type *ptr; /* and the buffer */
+typedef void (*stinst_type)();
+stinst_type *pc;
+stinst_type sstack[STACK];
+stinst_type *ssp = &sstack[0];
+long istack[STACK];
+long *isp = &istack[0];
+
+typedef int *word_type;
+
+
+
+struct dict_struct
+{
+ char *word;
+ struct dict_struct *next;
+ stinst_type *code;
+ int code_length;
+ int code_end;
+ int var;
+
+};
+typedef struct dict_struct dict_type;
+#define WORD(x) static void x()
+
+static void
+die (msg)
+ char *msg;
+{
+ fprintf (stderr, "%s\n", msg);
+ exit (1);
+}
+
+static void
+check_range ()
+{
+ if (tos < stack)
+ die ("underflow in string stack");
+ if (tos >= stack + STACK)
+ die ("overflow in string stack");
+}
+
+static void
+icheck_range ()
+{
+ if (isp < istack)
+ die ("underflow in integer stack");
+ if (isp >= istack + STACK)
+ die ("overflow in integer stack");
+}
+
+#ifdef __STDC__
+static void exec (dict_type *);
+static void call (void);
+static void remchar (void), strip_trailing_newlines (void), push_number (void);
+static void push_text (void);
+static void remove_noncomments (string_type *, string_type *);
+static void print_stack_level (void);
+static void paramstuff (void), translatecomments (void);
+static void outputdots (void), courierize (void), bulletize (void);
+static void do_fancy_stuff (void);
+static int iscommand (string_type *, unsigned int);
+static int copy_past_newline (string_type *, unsigned int, string_type *);
+static void icopy_past_newline (void), kill_bogus_lines (void), indent (void);
+static void get_stuff_in_command (void), swap (void), other_dup (void);
+static void drop (void), idrop (void);
+static void icatstr (void), skip_past_newline (void), internalmode (void);
+static void maybecatstr (void);
+static char *nextword (char *, char **);
+dict_type *lookup_word (char *);
+static void perform (void);
+dict_type *newentry (char *);
+unsigned int add_to_definition (dict_type *, stinst_type);
+void add_intrinsic (char *, void (*)());
+void add_var (char *);
+void compile (char *);
+static void bang (void);
+static void atsign (void);
+static void hello (void);
+static void stdout_ (void);
+static void stderr_ (void);
+static void print (void);
+static void read_in (string_type *, FILE *);
+static void usage (void);
+static void chew_exit (void);
+#endif
+
+static void DEFUN(exec,(word),
+ dict_type *word)
+{
+ pc = word->code;
+ while (*pc)
+ (*pc)();
+}
+WORD(call)
+{
+ stinst_type *oldpc = pc;
+ dict_type *e;
+ e = (dict_type *)(pc [1]);
+ exec(e);
+ pc = oldpc + 2;
+
+}
+
+WORD(remchar)
+{
+ if (tos->write_idx)
+ tos->write_idx--;
+ pc++;
+}
+
+static void
+strip_trailing_newlines ()
+{
+ while ((isspace ((unsigned char) at (tos, tos->write_idx - 1))
+ || at (tos, tos->write_idx - 1) == '\n')
+ && tos->write_idx > 0)
+ tos->write_idx--;
+ pc++;
+}
+
+WORD(push_number)
+{
+ isp++;
+ icheck_range ();
+ pc++;
+ *isp = (long)(*pc);
+ pc++;
+}
+
+WORD(push_text)
+{
+ tos++;
+ check_range ();
+ init_string(tos);
+ pc++;
+ cattext(tos,*((char **)pc));
+ pc++;
+
+}
+
+
+/* This function removes everything not inside comments starting on
+ the first char of the line from the string, also when copying
+ comments, removes blank space and leading *'s.
+ Blank lines are turned into one blank line. */
+
+static void
+DEFUN(remove_noncomments,(src,dst),
+ string_type *src AND
+ string_type *dst)
+{
+ unsigned int idx = 0;
+
+ while (at(src,idx))
+ {
+ /* Now see if we have a comment at the start of the line */
+ if (at(src,idx) == '\n'
+ && at(src,idx+1) == '/'
+ && at(src,idx+2) == '*')
+ {
+ idx+=3;
+
+ idx = skip_white_and_stars(src,idx);
+
+ /* Remove leading dot */
+ if (at(src, idx) == '.')
+ idx++;
+
+ /* Copy to the end of the line, or till the end of the
+ comment */
+ while (at(src, idx))
+ {
+ if (at(src, idx) == '\n')
+ {
+ /* end of line, echo and scrape of leading blanks */
+ if (at(src,idx +1) == '\n')
+ catchar(dst,'\n');
+ catchar(dst,'\n');
+ idx++;
+ idx = skip_white_and_stars(src, idx);
+ }
+ else if (at(src, idx) == '*' && at(src,idx+1) == '/')
+ {
+ idx +=2 ;
+ cattext(dst,"\nENDDD\n");
+ break;
+ }
+ else
+ {
+ catchar(dst, at(src, idx));
+ idx++;
+ }
+ }
+ }
+ else idx++;
+ }
+}
+
+static void
+print_stack_level ()
+{
+ fprintf (stderr, "current string stack depth = %d, ", tos - stack);
+ fprintf (stderr, "current integer stack depth = %d\n", isp - istack);
+ pc++;
+}
+
+/* turn:
+ foobar name(stuff);
+ into:
+ foobar
+ name PARAMS ((stuff));
+ and a blank line.
+ */
+
+static void
+DEFUN_VOID(paramstuff)
+{
+ unsigned int openp;
+ unsigned int fname;
+ unsigned int idx;
+ string_type out;
+ init_string(&out);
+
+
+ /* make sure that it's not already param'd or proto'd */
+ if(find(tos,"PARAMS") || find(tos,"PROTO") || !find(tos,"(")) {
+ catstr(&out,tos);
+ }
+ else
+ {
+ /* Find the open paren */
+ for (openp = 0; at(tos, openp) != '(' && at(tos,openp); openp++)
+ ;
+
+ fname = openp;
+ /* Step back to the fname */
+ fname--;
+ while (fname && isspace((unsigned char) at(tos, fname)))
+ fname --;
+ while (fname
+ && !isspace((unsigned char) at(tos,fname))
+ && at(tos,fname) != '*')
+ fname--;
+
+ fname++;
+
+ for (idx = 0; idx < fname; idx++) /* Output type */
+ {
+ catchar(&out, at(tos,idx));
+ }
+
+ cattext(&out, "\n"); /* Insert a newline between type and fnname */
+
+ for (idx = fname; idx < openp; idx++) /* Output fnname */
+ {
+ catchar(&out, at(tos,idx));
+ }
+
+ cattext(&out," PARAMS (");
+
+ while (at(tos,idx) && at(tos,idx) !=';')
+ {
+ catchar(&out, at(tos, idx));
+ idx++;
+ }
+ cattext(&out,");\n\n");
+ }
+ overwrite_string(tos, &out);
+ pc++;
+
+}
+
+
+
+/* turn {*
+ and *} into comments */
+
+WORD(translatecomments)
+{
+ unsigned int idx = 0;
+ string_type out;
+ init_string(&out);
+
+ while (at(tos, idx))
+ {
+ if (at(tos,idx) == '{' && at(tos,idx+1) =='*')
+ {
+ cattext(&out,"/*");
+ idx+=2;
+ }
+ else if (at(tos,idx) == '*' && at(tos,idx+1) =='}')
+ {
+ cattext(&out,"*/");
+ idx+=2;
+ }
+ else
+ {
+ catchar(&out, at(tos, idx));
+ idx++;
+ }
+ }
+
+
+ overwrite_string(tos, &out);
+
+ pc++;
+
+}
+
+#if 0
+
+/* This is not currently used. */
+
+/* turn everything not starting with a . into a comment */
+
+WORD(manglecomments)
+{
+ unsigned int idx = 0;
+ string_type out;
+ init_string(&out);
+
+ while (at(tos, idx))
+ {
+ if (at(tos,idx) == '\n' && at(tos,idx+1) =='*')
+ {
+ cattext(&out," /*");
+ idx+=2;
+ }
+ else if (at(tos,idx) == '*' && at(tos,idx+1) =='}')
+ {
+ cattext(&out,"*/");
+ idx+=2;
+ }
+ else
+ {
+ catchar(&out, at(tos, idx));
+ idx++;
+ }
+ }
+
+
+ overwrite_string(tos, &out);
+
+ pc++;
+
+}
+
+#endif
+
+/* Mod tos so that only lines with leading dots remain */
+static void
+DEFUN_VOID(outputdots)
+{
+ unsigned int idx = 0;
+ string_type out;
+ init_string(&out);
+
+ while (at(tos, idx))
+ {
+ if (at(tos, idx) == '\n' && at(tos, idx+1) == '.')
+ {
+ char c;
+ idx += 2;
+
+ while ((c = at(tos, idx)) && c != '\n')
+ {
+ if (c == '{' && at(tos,idx+1) =='*')
+ {
+ cattext(&out," /*");
+ idx+=2;
+ }
+ else if (c == '*' && at(tos,idx+1) =='}')
+ {
+ cattext(&out,"*/");
+ idx+=2;
+ }
+ else
+ {
+ catchar(&out, c);
+ idx++;
+ }
+ }
+ catchar(&out,'\n');
+ }
+ else
+ {
+ idx++;
+ }
+ }
+
+ overwrite_string(tos, &out);
+ pc++;
+
+}
+
+/* Find lines starting with . and | and put example around them on tos */
+WORD(courierize)
+{
+ string_type out;
+ unsigned int idx = 0;
+ int command = 0;
+
+ init_string(&out);
+
+ while (at(tos, idx))
+ {
+ if (at(tos, idx) == '\n'
+ && (at(tos, idx +1 ) == '.'
+ || at(tos,idx+1) == '|'))
+ {
+ cattext(&out,"\n@example\n");
+ do
+ {
+ idx += 2;
+
+ while (at(tos, idx) && at(tos, idx)!='\n')
+ {
+ if (at(tos,idx)=='{' && at(tos,idx+1) =='*')
+ {
+ cattext(&out," /*");
+ idx+=2;
+ }
+ else if (at(tos,idx)=='*' && at(tos,idx+1) =='}')
+ {
+ cattext(&out,"*/");
+ idx+=2;
+ }
+ else if (at(tos,idx) == '{' && !command)
+ {
+ cattext(&out,"@{");
+ idx++;
+ }
+ else if (at(tos,idx) == '}' && !command)
+ {
+ cattext(&out,"@}");
+ idx++;
+ }
+ else
+ {
+ if (at(tos,idx) == '@')
+ command = 1;
+ else if (isspace((unsigned char) at(tos,idx))
+ || at(tos,idx) == '}')
+ command = 0;
+ catchar(&out, at(tos, idx));
+ idx++;
+ }
+
+ }
+ catchar(&out,'\n');
+ }
+ while (at(tos, idx) == '\n'
+ && ((at(tos, idx+1) == '.')
+ || (at(tos,idx+1) == '|')))
+ ;
+ cattext(&out,"@end example");
+ }
+ else
+ {
+ catchar(&out, at(tos, idx));
+ idx++;
+ }
+ }
+
+ overwrite_string(tos, &out);
+ pc++;
+
+
+}
+
+/* Finds any lines starting with "o ", if there are any, then turns
+ on @itemize @bullet, and @items each of them. Then ends with @end
+ itemize, inplace at TOS*/
+
+
+WORD(bulletize)
+{
+ unsigned int idx = 0;
+ int on = 0;
+ string_type out;
+ init_string(&out);
+
+ while (at(tos, idx)) {
+ if (at(tos, idx) == '@' &&
+ at(tos, idx+1) == '*')
+ {
+ cattext(&out,"*");
+ idx+=2;
+ }
+
+ else
+ if (at(tos, idx) == '\n' &&
+ at(tos, idx+1) == 'o' &&
+ isspace((unsigned char) at(tos, idx +2)))
+ {
+ if (!on)
+ {
+ cattext(&out,"\n@itemize @bullet\n");
+ on = 1;
+
+ }
+ cattext(&out,"\n@item\n");
+ idx+=3;
+ }
+ else
+ {
+ catchar(&out, at(tos, idx));
+ if (on && at(tos, idx) == '\n' &&
+ at(tos, idx+1) == '\n' &&
+ at(tos, idx+2) != 'o')
+ {
+ cattext(&out, "@end itemize");
+ on = 0;
+ }
+ idx++;
+
+ }
+ }
+ if (on)
+ {
+ cattext(&out,"@end itemize\n");
+ }
+
+ delete_string(tos);
+ *tos = out;
+ pc++;
+
+}
+
+/* Turn <<foo>> into @code{foo} in place at TOS*/
+
+
+WORD(do_fancy_stuff)
+{
+ unsigned int idx = 0;
+ string_type out;
+ init_string(&out);
+ while (at(tos, idx))
+ {
+ if (at(tos, idx) == '<'
+ && at(tos, idx+1) == '<'
+ && !isspace((unsigned char) at(tos,idx + 2)))
+ {
+ /* This qualifies as a << startup */
+ idx +=2;
+ cattext(&out,"@code{");
+ while(at(tos,idx) &&
+ at(tos,idx) != '>' )
+ {
+ catchar(&out, at(tos, idx));
+ idx++;
+
+ }
+ cattext(&out,"}");
+ idx+=2;
+ }
+ else
+ {
+ catchar(&out, at(tos, idx));
+ idx++;
+ }
+ }
+ delete_string(tos);
+ *tos = out;
+ pc++;
+
+}
+/* A command is all upper case,and alone on a line */
+static int
+DEFUN( iscommand,(ptr, idx),
+ string_type *ptr AND
+ unsigned int idx)
+{
+ unsigned int len = 0;
+ while (at(ptr,idx)) {
+ if (isupper((unsigned char) at(ptr,idx)) || at(ptr,idx) == ' ' ||
+ at(ptr,idx) == '_')
+ {
+ len++;
+ idx++;
+ }
+ else if(at(ptr,idx) == '\n')
+ {
+ if (len > 3) return 1;
+ return 0;
+ }
+ else return 0;
+ }
+ return 0;
+
+}
+
+
+static int
+DEFUN(copy_past_newline,(ptr, idx, dst),
+ string_type *ptr AND
+ unsigned int idx AND
+ string_type *dst)
+{
+ int column = 0;
+
+ while (at(ptr, idx) && at(ptr, idx) != '\n')
+ {
+ if (at (ptr, idx) == '\t')
+ {
+ /* Expand tabs. Neither makeinfo nor TeX can cope well with
+ them. */
+ do
+ catchar (dst, ' ');
+ while (++column & 7);
+ }
+ else
+ {
+ catchar(dst, at(ptr, idx));
+ column++;
+ }
+ idx++;
+
+ }
+ catchar(dst, at(ptr, idx));
+ idx++;
+ return idx;
+
+}
+
+WORD(icopy_past_newline)
+{
+ tos++;
+ check_range ();
+ init_string(tos);
+ idx = copy_past_newline(ptr, idx, tos);
+ pc++;
+}
+
+/* indent
+ Take the string at the top of the stack, do some prettying */
+
+
+WORD(kill_bogus_lines)
+{
+ int sl ;
+
+ int idx = 0;
+ int c;
+ int dot = 0 ;
+
+ string_type out;
+ init_string(&out);
+ /* Drop leading nl */
+ while (at(tos,idx) == '\n')
+ {
+ idx++;
+ }
+ c = idx;
+
+ /* If the first char is a '.' prepend a newline so that it is
+ recognized properly later. */
+ if (at (tos, idx) == '.')
+ catchar (&out, '\n');
+
+ /* Find the last char */
+ while (at(tos,idx))
+ {
+ idx++;
+ }
+
+ /* find the last non white before the nl */
+ idx--;
+
+ while (idx && isspace((unsigned char) at(tos,idx)))
+ idx--;
+ idx++;
+
+ /* Copy buffer upto last char, but blank lines before and after
+ dots don't count */
+ sl = 1;
+
+ while (c < idx)
+ {
+ if (at(tos,c) == '\n'
+ && at(tos,c+1) == '\n'
+ && at(tos,c+2) == '.')
+ {
+ /* Ignore two newlines before a dot*/
+ c++;
+ }
+ else if (at(tos,c) == '.' && sl)
+ {
+ /* remember that this line started with a dot */
+ dot=2;
+ }
+ else if (at(tos,c) == '\n'
+ && at(tos,c+1) == '\n'
+ && dot)
+ {
+ c++;
+ /* Ignore two newlines when last line was dot */
+ }
+
+ catchar(&out, at(tos,c));
+ if (at(tos,c) == '\n')
+ {
+ sl = 1;
+
+ if (dot == 2)dot=1;else dot = 0;
+ }
+ else
+ sl = 0;
+
+ c++;
+
+ }
+
+ /* Append nl*/
+ catchar(&out, '\n');
+ pc++;
+ delete_string(tos);
+ *tos = out;
+
+
+}
+
+WORD(indent)
+{
+ string_type out;
+ int tab = 0;
+ int idx = 0;
+ int ol =0;
+ init_string(&out);
+ while (at(tos,idx)) {
+ switch (at(tos,idx))
+ {
+ case '\n':
+ cattext(&out,"\n");
+ idx++;
+ if (tab && at(tos,idx))
+ {
+ cattext(&out," ");
+ }
+ ol = 0;
+ break;
+ case '(':
+ tab++;
+ if (ol == 0)
+ cattext(&out," ");
+ idx++;
+ cattext(&out,"(");
+ ol = 1;
+ break;
+ case ')':
+ tab--;
+ cattext(&out,")");
+ idx++;
+ ol=1;
+
+ break;
+ default:
+ catchar(&out,at(tos,idx));
+ ol=1;
+
+ idx++;
+ break;
+ }
+ }
+
+ pc++;
+ delete_string(tos);
+ *tos = out;
+
+}
+
+
+WORD(get_stuff_in_command)
+{
+ tos++;
+ check_range ();
+ init_string(tos);
+
+ while (at(ptr, idx)) {
+ if (iscommand(ptr, idx)) break;
+ idx = copy_past_newline(ptr, idx, tos);
+ }
+ pc++;
+}
+
+WORD(swap)
+{
+ string_type t;
+
+ t = tos[0];
+ tos[0] = tos[-1];
+ tos[-1] =t;
+ pc++;
+
+}
+
+WORD(other_dup)
+{
+ tos++;
+ check_range ();
+ init_string(tos);
+ catstr(tos, tos-1);
+ pc++;
+}
+
+WORD(drop)
+{
+ tos--;
+ check_range ();
+ pc++;
+}
+
+WORD(idrop)
+{
+ isp--;
+ icheck_range ();
+ pc++;
+}
+
+WORD(icatstr)
+{
+ tos--;
+ check_range ();
+ catstr(tos, tos+1);
+ delete_string(tos+1);
+ pc++;
+}
+
+WORD(skip_past_newline)
+{
+ while (at(ptr,idx)
+ && at(ptr,idx) != '\n')
+ idx++;
+ idx++;
+ pc++;
+}
+
+
+WORD(internalmode)
+{
+ internal_mode = *(isp);
+ isp--;
+ icheck_range ();
+ pc++;
+}
+
+WORD(maybecatstr)
+{
+ if (internal_wanted == internal_mode)
+ {
+ catstr(tos-1, tos);
+ }
+ delete_string(tos);
+ tos--;
+ check_range ();
+ pc++;
+}
+
+char *
+DEFUN(nextword,(string, word),
+ char *string AND
+ char **word)
+{
+ char *word_start;
+ int idx;
+ char *dst;
+ char *src;
+
+ int length = 0;
+
+ while (isspace((unsigned char) *string) || *string == '-') {
+ if (*string == '-')
+ {
+ while (*string && *string != '\n')
+ string++;
+
+ }
+ else {
+ string++;
+ }
+ }
+ if (!*string) return 0;
+
+ word_start = string;
+ if (*string == '"')
+ {
+ do
+ {
+ string++;
+ length++;
+ if (*string == '\\')
+ {
+ string += 2;
+ length += 2;
+ }
+ }
+ while (*string != '"');
+ }
+ else
+ {
+ while (!isspace((unsigned char) *string))
+ {
+ string++;
+ length++;
+
+ }
+ }
+
+ *word = malloc(length + 1);
+
+ dst = *word;
+ src = word_start;
+
+
+ for (idx= 0; idx < length; idx++)
+ {
+ if (src[idx] == '\\')
+ switch (src[idx+1])
+ {
+ case 'n':
+ *dst++ = '\n';
+ idx++;
+ break;
+ case '"':
+ case '\\':
+ *dst++ = src[idx+1];
+ idx++;
+ break;
+ default:
+ *dst++ = '\\';
+ break;
+ }
+ else
+ *dst++ = src[idx];
+ }
+ *dst++ = 0;
+
+
+
+
+
+ if(*string)
+ return string + 1;
+ else
+ return 0;
+
+}
+dict_type *root;
+dict_type *
+DEFUN(lookup_word,(word),
+ char *word)
+{
+ dict_type *ptr = root;
+ while (ptr) {
+ if (strcmp(ptr->word, word) == 0) return ptr;
+ ptr = ptr->next;
+
+ }
+ if (warning)
+ fprintf(stderr,"Can't find %s\n",word);
+ return 0;
+
+
+}
+
+static void DEFUN_VOID(perform)
+{
+ tos = stack;
+
+ while (at(ptr, idx)) {
+ /* It's worth looking through the command list */
+ if (iscommand(ptr, idx))
+ {
+ char *next;
+ dict_type *word ;
+
+ (void) nextword(addr(ptr, idx), &next);
+
+
+ word = lookup_word(next);
+
+
+
+
+ if (word)
+ {
+ exec(word);
+ }
+ else
+ {
+ if (warning)
+ fprintf(stderr,"warning, %s is not recognised\n", next);
+ skip_past_newline();
+ }
+
+ }
+ else skip_past_newline();
+
+ }
+}
+
+dict_type *
+DEFUN(newentry,(word),
+ char *word)
+{
+ dict_type *new = (dict_type *)malloc(sizeof(dict_type));
+ new->word = word;
+ new->next = root;
+ root = new;
+ new->code = (stinst_type *)malloc(sizeof(stinst_type ));
+ new->code_length = 1;
+ new->code_end = 0;
+ return new;
+
+}
+
+
+unsigned int
+DEFUN(add_to_definition,(entry, word),
+ dict_type *entry AND
+ stinst_type word)
+{
+ if (entry->code_end == entry->code_length)
+ {
+ entry->code_length += 2;
+ entry->code =
+ (stinst_type *) realloc((char *)(entry->code),
+ entry->code_length *sizeof(word_type));
+ }
+ entry->code[entry->code_end] = word;
+
+return entry->code_end++;
+}
+
+
+
+
+
+
+
+void
+DEFUN(add_intrinsic,(name, func),
+ char *name AND
+ void (*func)())
+{
+ dict_type *new = newentry(name);
+ add_to_definition(new, func);
+ add_to_definition(new, 0);
+}
+
+void
+DEFUN(add_var,(name),
+ char *name)
+{
+ dict_type *new = newentry(name);
+ add_to_definition(new, push_number);
+ add_to_definition(new, (stinst_type)(&(new->var)));
+ add_to_definition(new,0);
+}
+
+
+void
+DEFUN(compile, (string),
+ char *string)
+{
+ /* add words to the dictionary */
+ char *word;
+ string = nextword(string, &word);
+ while (string && *string && word[0])
+ {
+ if (strcmp(word,"var")==0)
+ {
+ string=nextword(string, &word);
+
+ add_var(word);
+ string=nextword(string, &word);
+ }
+else
+
+ if (word[0] == ':')
+ {
+ dict_type *ptr;
+ /* Compile a word and add to dictionary */
+ string = nextword(string, &word);
+
+ ptr = newentry(word);
+ string = nextword(string, &word);
+ while (word[0] != ';' )
+ {
+ switch (word[0])
+ {
+ case '"':
+ /* got a string, embed magic push string
+ function */
+ add_to_definition(ptr, push_text);
+ add_to_definition(ptr, (stinst_type)(word+1));
+ break;
+ case '0':
+ case '1':
+ case '2':
+ case '3':
+ case '4':
+ case '5':
+ case '6':
+ case '7':
+ case '8':
+ case '9':
+ /* Got a number, embedd the magic push number
+ function */
+ add_to_definition(ptr, push_number);
+ add_to_definition(ptr, (stinst_type)atol(word));
+ break;
+ default:
+ add_to_definition(ptr, call);
+ add_to_definition(ptr, (stinst_type)lookup_word(word));
+ }
+
+ string = nextword(string, &word);
+ }
+ add_to_definition(ptr,0);
+ string = nextword(string, &word);
+ }
+ else
+ {
+ fprintf(stderr,"syntax error at %s\n",string-1);
+ }
+ }
+
+}
+
+
+static void DEFUN_VOID(bang)
+{
+ *(long *)((isp[0])) = isp[-1];
+ isp-=2;
+ icheck_range ();
+ pc++;
+}
+
+WORD(atsign)
+{
+ isp[0] = *(long *)(isp[0]);
+ pc++;
+}
+
+WORD(hello)
+{
+ printf("hello\n");
+ pc++;
+}
+
+WORD(stdout_)
+{
+ isp++;
+ icheck_range ();
+ *isp = 1;
+ pc++;
+}
+
+WORD(stderr_)
+{
+ isp++;
+ icheck_range ();
+ *isp = 2;
+ pc++;
+}
+
+WORD(print)
+{
+ if (*isp == 1)
+ write_buffer (tos, stdout);
+ else if (*isp == 2)
+ write_buffer (tos, stderr);
+ else
+ fprintf (stderr, "print: illegal print destination `%ld'\n", *isp);
+ isp--;
+ tos--;
+ icheck_range ();
+ check_range ();
+ pc++;
+}
+
+
+static void DEFUN(read_in, (str, file),
+ string_type *str AND
+ FILE *file)
+{
+ char buff[10000];
+ unsigned int r;
+ do
+ {
+ r = fread(buff, 1, sizeof(buff), file);
+ catbuf(str, buff, r);
+ }
+ while (r);
+ buff[0] = 0;
+
+ catbuf(str, buff,1);
+}
+
+
+static void DEFUN_VOID(usage)
+{
+ fprintf(stderr,"usage: -[d|i|g] <file >file\n");
+ exit(33);
+}
+
+/* There is no reliable way to declare exit. Sometimes it returns
+ int, and sometimes it returns void. Sometimes it changes between
+ OS releases. Trying to get it declared correctly in the hosts file
+ is a pointless waste of time. */
+
+static void
+chew_exit ()
+{
+ exit (0);
+}
+
+int DEFUN(main,(ac,av),
+int ac AND
+char *av[])
+{
+ unsigned int i;
+ string_type buffer;
+ string_type pptr;
+
+ init_string(&buffer);
+ init_string(&pptr);
+ init_string(stack+0);
+ tos=stack+1;
+ ptr = &pptr;
+
+ add_intrinsic("push_text", push_text);
+ add_intrinsic("!", bang);
+ add_intrinsic("@", atsign);
+ add_intrinsic("hello",hello);
+ add_intrinsic("stdout",stdout_);
+ add_intrinsic("stderr",stderr_);
+ add_intrinsic("print",print);
+ add_intrinsic("skip_past_newline", skip_past_newline );
+ add_intrinsic("catstr", icatstr );
+ add_intrinsic("copy_past_newline", icopy_past_newline );
+ add_intrinsic("dup", other_dup );
+ add_intrinsic("drop", drop);
+ add_intrinsic("idrop", idrop);
+ add_intrinsic("remchar", remchar );
+ add_intrinsic("get_stuff_in_command", get_stuff_in_command );
+ add_intrinsic("do_fancy_stuff", do_fancy_stuff );
+ add_intrinsic("bulletize", bulletize );
+ add_intrinsic("courierize", courierize );
+ /* If the following line gives an error, exit() is not declared in the
+ ../hosts/foo.h file for this host. Fix it there, not here! */
+ /* No, don't fix it anywhere; see comment on chew_exit--Ian Taylor. */
+ add_intrinsic("exit", chew_exit );
+ add_intrinsic("swap", swap );
+ add_intrinsic("outputdots", outputdots );
+ add_intrinsic("paramstuff", paramstuff );
+ add_intrinsic("maybecatstr", maybecatstr );
+ add_intrinsic("translatecomments", translatecomments );
+ add_intrinsic("kill_bogus_lines", kill_bogus_lines);
+ add_intrinsic("indent", indent);
+ add_intrinsic("internalmode", internalmode);
+ add_intrinsic("print_stack_level", print_stack_level);
+ add_intrinsic("strip_trailing_newlines", strip_trailing_newlines);
+
+ /* Put a nl at the start */
+ catchar(&buffer,'\n');
+
+ read_in(&buffer, stdin);
+ remove_noncomments(&buffer, ptr);
+ for (i= 1; i < (unsigned int) ac; i++)
+ {
+ if (av[i][0] == '-')
+ {
+ if (av[i][1] == 'f')
+ {
+ string_type b;
+ FILE *f;
+ init_string(&b);
+
+ f = fopen(av[i+1],"r");
+ if (!f)
+ {
+ fprintf(stderr,"Can't open the input file %s\n",av[i+1]);
+ return 33;
+ }
+
+ read_in(&b, f);
+ compile(b.ptr);
+ perform();
+ }
+ else if (av[i][1] == 'i')
+ {
+ internal_wanted = 1;
+ }
+ else if (av[i][1] == 'w')
+ {
+ warning = 1;
+ }
+ else
+ usage ();
+ }
+ }
+ write_buffer(stack+0, stdout);
+ if (tos != stack)
+ {
+ fprintf (stderr, "finishing with current stack level %d\n", tos - stack);
+ return 1;
+ }
+ return 0;
+}
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
new file mode 100644
index 0000000..7a276fe
--- /dev/null
+++ b/bfd/doc/doc.str
@@ -0,0 +1,158 @@
+: DOCDD
+ skip_past_newline
+ get_stuff_in_command kill_bogus_lines catstr
+ ;
+
+: ENDDD
+ skip_past_newline
+ ;
+
+: EXAMPLE
+ skip_past_newline
+ get_stuff_in_command kill_bogus_lines do_fancy_stuff translatecomments
+ courierize catstr
+
+ ;
+
+: INODE
+ "@node " catstr skip_past_newline copy_past_newline catstr
+ ;
+
+: CODE_FRAGMENT
+ EXAMPLE
+ ;
+
+: COMMENT
+ skip_past_newline
+ get_stuff_in_command
+ drop
+ ;
+
+: SYNOPSIS
+ skip_past_newline
+ "@strong{Synopsis}\n" catstr
+ "@example\n" catstr
+ get_stuff_in_command
+ kill_bogus_lines
+ indent
+ catstr
+ "@end example\n" catstr
+
+ ;
+
+: func
+ "@findex " - a
+ skip_past_newline
+ copy_past_newline
+ dup - a x x
+ "@subsubsection @code{" - a x x b
+ swap
+ remchar
+ "}\n" - a x b x c
+ catstr catstr catstr catstr catstr
+ ;
+
+: FUNCTION
+ "@findex " - a
+ skip_past_newline
+ copy_past_newline
+ dup - a x x
+ "@subsubsection @code{" - a x x b
+ swap
+ remchar
+ "}\n" - a x b x c
+ catstr catstr catstr catstr catstr
+ ;
+
+: bodytext
+ get_stuff_in_command
+ bulletize
+ kill_bogus_lines
+ do_fancy_stuff
+ courierize
+ catstr
+ "\n" catstr
+ ;
+
+: asection
+ skip_past_newline
+ catstr
+ copy_past_newline
+ do_fancy_stuff catstr
+ bodytext
+ ;
+
+: SECTION
+ "@section " asection ;
+
+: SUBSECTION
+ "@subsection " asection ;
+
+: SUBSUBSECTION
+ "@subsubsection " asection ;
+
+: subhead
+ skip_past_newline
+ bodytext
+ ;
+
+
+
+
+: DESCRIPTION
+ "@strong{Description}@*\n" catstr subhead ;
+
+: RETURNS
+ "@strong{Returns}@*\n" catstr subhead ;
+
+: INTERNAL_FUNCTION
+ func ;
+
+
+: INTERNAL_DEFINITION
+ func ;
+
+
+: INTERNAL
+ func ;
+
+: TYPEDEF
+ FUNCTION ;
+
+: SENUM
+ skip_past_newline
+ "Here are the possible values for @code{enum "
+ copy_past_newline remchar catstr
+ "}:\n\n" catstr catstr
+ ;
+: ENUM
+ skip_past_newline
+ "@deffn {} "
+ copy_past_newline catstr catstr
+ ;
+: ENUMX
+ skip_past_newline
+ "@deffnx {} "
+ copy_past_newline catstr
+ catstr
+ ;
+: ENUMEQ
+ skip_past_newline
+ "@deffn {} "
+ copy_past_newline catstr catstr
+ skip_past_newline
+ ;
+: ENUMEQX
+ skip_past_newline
+ "@deffnx {} "
+ copy_past_newline catstr
+ catstr
+ skip_past_newline
+ ;
+: ENUMDOC
+ skip_past_newline
+ get_stuff_in_command
+ strip_trailing_newlines
+ catstr
+ "\n@end deffn\n" catstr
+ ;
diff --git a/bfd/doc/makefile.vms b/bfd/doc/makefile.vms
new file mode 100644
index 0000000..a0857c0
--- /dev/null
+++ b/bfd/doc/makefile.vms
@@ -0,0 +1,5 @@
+CFLAGS = /noopt/include=([],[-],[-.-.include])
+LDFLAGS = /nomap
+LDLIBS = ,sys$$library:vaxcrtl.olb/lib
+
+all: chew.exe
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
new file mode 100644
index 0000000..8431c16
--- /dev/null
+++ b/bfd/doc/proto.str
@@ -0,0 +1,135 @@
+
+: SYNOPSIS
+ skip_past_newline
+ get_stuff_in_command
+ paramstuff
+ indent
+ maybecatstr
+;
+
+: ignore
+ skip_past_newline
+ get_stuff_in_command
+ outputdots
+ maybecatstr
+ ;
+
+: CODE_FRAGMENT
+ ignore ;
+
+: external
+ 0 internalmode ignore ;
+
+: internal
+ 1 internalmode ignore ;
+
+- input stack { a b } output b if internal, a if external
+: ifinternal
+ "" swap 1 internalmode maybecatstr
+ swap
+ "" swap 0 internalmode maybecatstr
+ catstr
+ ;
+
+- Put note in output string, regardless of internal mode.
+: COMMENT
+ skip_past_newline
+ get_stuff_in_command
+ translatecomments
+ catstr
+ ;
+
+- SENUM enum-type-name
+- ENUM enum-name
+- ENUMX addl-enum-name
+- ENUMDOC doc for preceding enums
+- ENDSENUM max-enum-name
+
+: make_enum_header
+ dup
+ "enum " swap catstr
+ " {\n" catstr
+ swap " _dummy_first_" swap catstr catstr
+ ",\n" catstr
+ ;
+: make_string_table_header
+ dup
+ "#ifdef _BFD_MAKE_TABLE_" swap catstr swap
+ "\n\nstatic const char *const " swap catstr catstr
+ "_names[] = { \"@@uninitialized@@\",\n" catstr
+ ;
+: SENUM
+ skip_past_newline
+ copy_past_newline
+ remchar
+ dup
+ make_enum_header
+ swap
+ make_string_table_header
+ ifinternal
+ catstr
+ get_stuff_in_command catstr
+ translatecomments ;
+: ENDSENUM
+ skip_past_newline
+ copy_past_newline strip_trailing_newlines
+ dup
+ " " swap catstr " };\n" catstr swap
+ " \"@@overflow: " swap catstr "@@\",\n};\n#endif\n\n" catstr
+ ifinternal
+ catstr
+ ;
+: make_enumerator
+ " " swap catstr
+ ",\n" catstr
+ ;
+: make_enumerator_string
+ " \"" swap catstr
+ "\",\n" catstr
+ ;
+: ENUM
+ skip_past_newline
+ copy_past_newline
+ remchar
+ dup
+ make_enumerator
+ swap
+ make_enumerator_string
+ ifinternal
+ ;
+: ENUMX ENUM catstr ;
+: ENUMEQ
+ skip_past_newline
+ "#define "
+ copy_past_newline remchar
+ catstr
+ " "
+ catstr
+ copy_past_newline
+ catstr
+ "" swap 0 internalmode maybecatstr
+ ;
+: ENUMEQX ENUMEQ catstr ;
+: ENUMDOC
+ skip_past_newline
+ get_stuff_in_command
+ strip_trailing_newlines
+ "\n{* " swap catstr " *}\n" catstr
+ translatecomments
+ - discard it if we're doing internal mode
+ "" swap 0 internalmode maybecatstr
+ swap
+ catstr catstr
+ ;
+: ENDDD external ;
+: SECTION ignore ;
+: SUBSECTION ignore ;
+: SUBSUBSECTION ignore ;
+: INTERNAL_DEFINITION internal ;
+: DESCRIPTION ignore ;
+: FUNCTION external ;
+: RETURNS ignore ;
+: TYPEDEF external ;
+: INTERNAL_FUNCTION internal ;
+: INTERNAL internal ;
+: INODE ignore ;