Mon Aug 19 13:48:22 1991 Roland H. Pesch (pesch at cygint.cygnus.com)

	* aoutx.h, archive.c, archures.c, bfd.c, bfd.texinfo, cache.c,
	coffcode.h, core.c, format.c, libbfd.c, libbfd.h, libcoff.h,
	opncls.c, reloc.c, section.c, syms.c, targets.c (documentation
	segments): used BFD (caps) more consistently as a name in
	discourse, fixed a few other minor typos and uses of fonts

16 files changed, 933 insertions, 229 deletions

diff --git a/bfd/ChangeLog b/bfd/ChangeLog
index eb360f1..9b22c7b 100644
--- a/bfd/ChangeLog
+++ b/bfd/ChangeLog
@@ -1,3 +1,12 @@
+Mon Aug 19 13:48:22 1991  Roland H. Pesch  (pesch at cygint.cygnus.com)
+
+	* aoutx.h, archive.c, archures.c, bfd.c, bfd.texinfo, cache.c,
+	coffcode.h, core.c, format.c, libbfd.c, libbfd.h, libcoff.h,
+	opncls.c, reloc.c, section.c, syms.c, targets.c (documentation
+	segments): used BFD (caps) more consistently as a name in
+	discourse, fixed a few other minor typos and uses of fonts
+	
+
 Thu Aug  8 16:47:43 1991  Steve Chamberlain  (steve at cygint.cygnus.com)
 
 	* coffcode.h: fixed bug where string table size wasn't being swapped.
diff --git a/bfd/aoutx.h b/bfd/aoutx.h
index 90267c0..91a4a3f 100644
--- a/bfd/aoutx.h
+++ b/bfd/aoutx.h
@@ -37,7 +37,7 @@ machine, including @code{sunos.c} - for sun3 and sun4 and
 
 The base file @code{aoutx.h} defines general mechanisms for reading
 and writing records to and from disk, and various other methods which
-bfd requires. It is included by @code{aout32.c} and @code{aout64.c} to
+BFD requires. It is included by @code{aout32.c} and @code{aout64.c} to
 form the names aout_32_swap_exec_header_in,
 aout_64_swap_exec_header_in, etc.
 
@@ -507,7 +507,7 @@ DEFUN(NAME(aout,some_aout_object_p),(abfd, callback_to_real_object_p),
 /*doc*
 *i aout_<size>_mkobject
 
-This routine initializes a bfd for use with a.out files.
+This routine initializes a BFD for use with a.out files.
 
 *; PROTO(boolean, aout_<size>_mkobject, (bfd *));
 */
@@ -601,7 +601,7 @@ DEFUN(NAME(aout,machine_type),(arch, machine),
 /*doc*
 *i aout_<size>_set_arch_mach
 
-Sets the architecture and the machine of the bfd to those values
+Sets the architecture and the machine of the BFD to those values
 supplied. Verifies that the format can support the architecture
 required.
 
@@ -628,7 +628,7 @@ DEFUN(NAME(aout,set_arch_mach),(abfd, arch, machine),
 /*doc*
 *i aout_<size>new_section_hook
 
-Called by the bfd in response to a @code{bfd_make_section} request.
+Called by the BFD in response to a @code{bfd_make_section} request.
 *; PROTO(boolean, aout_<size>_new_section_hook,
          (bfd *abfd,
 	  asection *newsect));
@@ -1681,7 +1681,7 @@ DEFUN(NAME(aout,print_symbol),(ignore_abfd, afile, symbol, how),
 }
 
 /* 
- provided a bfd, a section and an offset into the section, calculate
+ provided a BFD, a section and an offset into the section, calculate
  and return the name of the source file and the line nearest to the
  wanted location.
 */
diff --git a/bfd/archive.c b/bfd/archive.c
index 2f91901..fdac8df 100644
--- a/bfd/archive.c
+++ b/bfd/archive.c
@@ -1,23 +1,22 @@
+/* BFD back-end for archive files (libraries).
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Written by Cygnus Support.  Mostly Gumby Henkel-Wallace's fault.
 
+This file is part of BFD, the Binary File Descriptor library.
 
-/* Copyright (C) 1990, 1991 Free Software Foundation, Inc.
-
-This file is part of BFD, the Binary File Diddler.
-
-BFD is free software; you can redistribute it and/or modify
+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 1, or (at your option)
-any later version.
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
 
-BFD is distributed in the hope that it will be useful,
+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 BFD; see the file COPYING.  If not, write to
-the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
-
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
 /*doc*
 @setfilename archive-info
@@ -25,12 +24,12 @@ the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
 Gumby, you promised to write this bit...
 
-Archives are supported in bfd in @code{archive.c}.
+Archives are supported in BFD in @code{archive.c}.
 
-An archive is represented internally just like another bfd, with a
-pointer to a chain of contained bfds. Archives can be created by
-opening bfds, linking them together and attatching them as children to
-another bfd and then closing the parent bfd. 
+An archive is represented internally just like another BFD, with a
+pointer to a chain of contained BFDs. Archives can be created by
+opening BFDs, linking them together and attatching them as children to
+another BFD and then closing the parent BFD. 
 
 *-*/
 
@@ -125,7 +124,7 @@ _bfd_create_empty_archive_element_shell (obfd)
 }
 
 /*proto* bfd_set_archive_head
-Used whilst processing archives. Sets the head of the chain of bfds
+Used whilst processing archives. Sets the head of the chain of BFDs
 contained in an archive to @var{new_head}. (see chapter on archives)
 *; PROTO(boolean, bfd_set_archive_head, (bfd *output, bfd *new_head));
 */
@@ -289,7 +288,7 @@ snarf_ar_hdr (abfd)
     ared = (struct areltdata *) allocptr;
 
     ared->arch_header = allocptr + sizeof (struct areltdata);
-    memcpy ((char *) ared->arch_header, &hdr, sizeof (struct ar_hdr));
+    memcpy ((char *) ared->arch_header, (char *) &hdr, sizeof (struct ar_hdr));
     ared->parsed_size = parsed_size;
 
     if (filename != NULL) ared->filename = filename;
@@ -340,6 +339,11 @@ get_elt_at_filepos (archive, filepos)
   return NULL;
 }
 
+/*proto* bfd_get_elt_at_index
+
+*; PROTO(bfd *, bfd_get_elt_at_index, (bfd *, int));
+
+*/
 bfd *
 bfd_get_elt_at_index (abfd, index)
      bfd *abfd;
@@ -352,10 +356,10 @@ bfd_get_elt_at_index (abfd, index)
 }
 
 /*proto* bfd_openr_next_archived_file
-Initially provided a bfd containing an archive and NULL, opens a bfd
+Initially provided a BFD containing an archive and NULL, opens a BFD
 on the first contained element and returns that. Subsequent calls to
 bfd_openr_next_archived_file should pass the archive and the previous
-return value to return a created bfd to the next contained element.
+return value to return a created BFD to the next contained element.
 NULL is returned when there are no more.
 
 *; PROTO(bfd*, bfd_openr_next_archived_file,
@@ -596,7 +600,7 @@ bfd_slurp_coff_armap (abfd)
 
   /* We'd like to release these allocations, but we have allocated stuff
      since then (using the same obstack, if bfd_release is obstack based).
-     So they will stick around until the bfd is closed.  */
+     So they will stick around until the BFD is closed.  */
   /*  bfd_release (abfd, (PTR)raw_armap);
       bfd_release (abfd, (PTR)mapdata);  */
   bfd_has_map (abfd) = true;
@@ -954,7 +958,7 @@ bfd_gnu_truncate_arname (abfd, pathname, arhdr)
 
 PROTO (boolean, compute_and_write_armap, (bfd *arch, unsigned int elength));
 
-/* The bfd is open for write and has its format set to bfd_archive */
+/* The BFD is open for write and has its format set to bfd_archive */
 boolean
 _bfd_write_archive_contents (arch)
      bfd *arch;
diff --git a/bfd/archures.c b/bfd/archures.c
index 3a8b0c0..94af442 100644
--- a/bfd/archures.c
+++ b/bfd/archures.c
@@ -21,8 +21,8 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 /*doc*
 @section Architectures
 BFD's idea of an architecture is implimented in @code{archures.c}. BFD
-keeps two atoms in a bfd describing the architecture of the data
-attatched to the bfd, the @code{enum bfd_architecture arch} field and
+keeps two atoms in a BFD describing the architecture of the data
+attatched to the BFD, the @code{enum bfd_architecture arch} field and
 the @code{unsigned long machine} field.
 */
 
@@ -122,7 +122,7 @@ struct arch_print {
 /*proto* bfd_prinable_arch_mach
 Return a printable string representing the architecture and machine
 type. The result is only good until the next call to
-bfd_printable_arch_mach.  
+@code{bfd_printable_arch_mach}.  
 *; PROTO(CONST char *,bfd_printable_arch_mach,
     (enum bfd_architecture arch, unsigned long machine));
 */
@@ -344,10 +344,10 @@ scan_960_mach (string, ap, archp, machinep, archspec)
 *i bfd_arch_compatible
 This routine is used to determine whether two BFDs' architectures and machine types are
 compatible.  It calculates the lowest common denominator between the
-two architectures and machine types implied by the bfds and sets the
+two architectures and machine types implied by the BFDs and sets the
 objects pointed at by @var{archp} and @var{machine} if non NULL. 
 
-This routine returns @code{true} if the bfds are of compatible type,
+This routine returns @code{true} if the BFDs are of compatible type,
 otherwise @code{false}.
 *; PROTO(boolean, bfd_arch_compatible,
      (bfd *abfd,
diff --git a/bfd/bfd.c b/bfd/bfd.c
index b78216a..ad30a1b 100644
--- a/bfd/bfd.c
+++ b/bfd/bfd.c
@@ -1,21 +1,22 @@
-/* Copyright (C) 1990, 1991 Free Software Foundation, Inc.
+/* Generic BFD library interface and support routines.
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Written by Cygnus Support.
 
-This file is part of BFD, the Binary File Diddler.
+This file is part of BFD, the Binary File Descriptor library.
 
-BFD is free software; you can redistribute it and/or modify
+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 1, or (at your option)
-any later version.
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
 
-BFD is distributed in the hope that it will be useful,
+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 BFD; see the file COPYING.  If not, write to
-the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
-
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
 /* $Id$ */
 
@@ -23,8 +24,8 @@ the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
 @section typedef bfd
 
 Pointers to bfd structs are the cornerstone of any application using
-libbfd. References though the bfd and to data in the bfd give the
-entire bfd functionality.
+libbfd. References though the BFD and to data in the BFD give the
+entire BFD functionality.
 
 Finally!  The BFD struct itself.  This contains the major data about
 the file, and contains pointers to the rest of the data.
@@ -33,7 +34,7 @@ the file, and contains pointers to the rest of the data.
 
 $struct _bfd 
 ${
-  The filename the application opened the bfd with.
+  The filename the application opened the BFD with.
 
 $  CONST char *filename;                
 
@@ -43,7 +44,7 @@ $  struct bfd_target *xvec;
 
 
 To avoid dragging too many header files into every file that
-includes bfd.h, IOSTREAM has been declared as a "char *", and MTIME
+includes @file{bfd.h}, IOSTREAM has been declared as a "char *", and MTIME
 as a "long".  Their correct types, to which they are cast when used,
 are "FILE *" and "time_t".  
 
@@ -55,13 +56,13 @@ Is the file being cached @xref{File Caching}.
 
 $  boolean cacheable;
 
-Marks whether there was a default target specified when the bfd was
+Marks whether there was a default target specified when the BFD was
 opened. This is used to select what matching algorithm to use to chose
 the back end.
 
 $  boolean target_defaulted;
 
-The caching routines use these to maintain an LRU list of bfds.
+The caching routines use these to maintain an LRU list of BFDs.
 
 $  struct _bfd *lru_prev, *lru_next;
 
@@ -83,11 +84,11 @@ For output files, channel we locked (is this used?).
 
 $int ifd;
 
-The format which belongs to the bfd.
+The format which belongs to the BFD.
 
 $  bfd_format format;
 
-The direction the bfd was opened with
+The direction the BFD was opened with
 
 $  enum bfd_direction {no_direction = 0,
 $                       read_direction = 1,
@@ -123,7 +124,7 @@ $  bfd_vma start_address;
 Used for input and output
 
 $  unsigned int symcount;
-Symtab for output bfd
+Symtab for output BFD
 
 $  struct symbol_cache_entry  **outsymbols;             
 
@@ -352,7 +353,7 @@ int line;
 
 /*proto* bfd_set_start_address
 
-Marks the entry point of an output bfd. Returns @code{true} on
+Marks the entry point of an output BFD. Returns @code{true} on
 success, @code{false} otherwise.
 
 *; PROTO(boolean, bfd_set_start_address,(bfd *, bfd_vma));
@@ -397,9 +398,10 @@ bfd_get_mtime (abfd)
   return abfd->mtime;
 }
 
-/*proto*
-*i stuff
+/*proto* stuff
+
 *+
+
 #define bfd_sizeof_headers(abfd, reloc) \
      BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
 
diff --git a/bfd/bfd.texinfo b/bfd/bfd.texinfo
index 520fa35..a143119 100755
--- a/bfd/bfd.texinfo
+++ b/bfd/bfd.texinfo
@@ -35,7 +35,7 @@ into another language, under the above conditions for modified versions.
 @title{libbfd}
 @subtitle{The Binary File Descriptor Library}
 @sp 1
-@subtitle First Edition---@code{bfd} version < 2.0
+@subtitle First Edition---BFD version < 2.0
 @subtitle April 1991
 @author {Steve Chamberlain}
 @author {Cygnus Support}
@@ -77,8 +77,8 @@ This file documents the binary file descriptor library libbfd.
 @end ifinfo
 
 @menu
-* Overview::			Overview of bfd
-* History::			History of bfd
+* Overview::			Overview of BFD
+* History::			History of BFD
 * Backends::			Backends
 * Porting::			Porting
 * Future::			Future
@@ -98,7 +98,7 @@ BFD body:
 * Internal::
 * File Caching::
 
-Bfd backends:
+BFD backends:
 * a.out backends::
 * coff backends::
 @end menu
@@ -107,40 +107,40 @@ Bfd backends:
 @chapter Introduction
 @cindex BFD
 @cindex what is it?
-Simply put, @code{bfd} is a package which allow applications to use the
+Simply put, BFD is a package which allows applications to use the
 same routines to operate on object files whatever the object file
 format.  A different object file format can be supported simply by
 creating a new BFD back end and adding it to the library.
 
 BFD is split into two parts; the front end and the many back ends.
 @itemize @bullet
-@item The front end of bfd provides the interface to the user. It manages
+@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
+@item The back ends provide BFD its view of the real world. Each back
+end provides a set of calls which the BFD front end can use to maintain
 its canonical form. The back ends also may keep around information for
 their own use, for greater efficiency.
 @end itemize
 @node History, How It Works, Overview,Top
 @section History
 
-One spur behind @code{bfd} was the Intel Oregon's GNU 960 team desire for
-interoperability of applications on their COFF and b.out file formats.
-Cygnus was providing GNU support for the team, and Cygnus were
-contracted to provid the required functionality.
+One spur behind BFD was the desire, on the part of the GNU 960 team at
+Intel Oregon, for interoperability of applications on their COFF and
+b.out file formats.  Cygnus was providing GNU support for the team, and
+Cygnus was contracted to provide the required functionality.
 
-The name came from a conversation Gumby Wallace was
-having with Richard Stallman about the library, RMS said that it
-would be quite hard, Gumby said BFD. (Stallman was right, but the name
-stuck).
+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.
+different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
+coff.
 
 BFD was first implemented by Steve Chamberlain (steve@@cygnus.com),
 John Gilmore (gnu@@cygnus.com),  K. Richard Pixley (rich@@cygnus.com) and
-Gumby Wallace (gumby@@cygnus.com) at Cygnus Support in Palo Alto,
+David Wallace (gumby@@cygnus.com) at Cygnus Support in Palo Alto,
 California.
 
 @node How It Works, History, Porting, Top
@@ -148,19 +148,22 @@ California.
 
 To use the library, include @code{bfd.h} and link with @code{libbfd.a}.	
 
-@code{bfd} provides a common interface to the parts of an object file
-to a calling application. 
+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 structure described in
-@code{include/bfd.h}, called @code{bfd}. Conventionally this pointer is
-called a @code{bfd}, and instances of it within code are called
-@code{abfd}. All operations on the target object file are applied as
-methods to the @code{bfd}, the mapping is defined within @code{bfd.h} in
-a set of macros, all beginning @code{bfd}_something. 
+When an application sucessfully opens a target file (object, archive or
+whatever) a pointer to an internal structure is returned. This pointer
+points to a structure called @code{bfd}, described in
+@code{include/bfd.h}.  Our convention is to call this pointer a BFD, and
+instances of it within code @code{abfd}.  All operations on
+the target object file are applied as methods to the BFD.  The mapping is
+defined within @code{bfd.h} in a set of macros, all beginning
+@samp{bfd}_.
+
+For example, this sequence would do what you would probably expect:
+return the number of sections in an object file attached to a BFD
+@code{abfd}. 
 
-For example, this sequence would do what you expect:
 @lisp
 @cartouche
 #include "bfd.h"
@@ -173,14 +176,14 @@ bfd *abfd;
 @end cartouche
 @end lisp
 
-The metaphor used within @code{bfd} is that an object file has a header,
+The abstraction used within BFD is that an object file has a header,
 a number of sections containing raw data, a set of relocations, and some
-symbol information. Also, @code{bfd}s opened upon archives have the
-additional attribute of an index and contained sub bfds. This approach is
-find for a.out and coff, but looses efficiency when applied to formats
+symbol information. Also, BFDs opened for archives have the
+additional attribute of an index and contain subordinate BFDs. This approach is
+fine for a.out and coff, but loses efficiency when applied to formats
 such as S-records and IEEE-695. 
 
-@section What BFD Version 1 Can't Do
+@section What BFD Version 1 Can Do
 As different information from the the object files is required,
 BFD reads from different sections of the file and processes them.
 For example a very common operation for the linker is processing symbol
@@ -189,8 +192,8 @@ between the object file's representation of symbols and an internal
 canonical format. When the linker asks for the symbol table of an object
 file, it calls through the memory pointer to the relevant BFD
 back end routine which reads and converts the table into a canonical
-form.  The linker then operates upon the common form. When the link is
-finished and the linker writes the symbol table of the output file,
+form.  The linker then operates upon the canonical form. When the link is
+finished and the linker writes the output file's symbol table,
 another BFD back end routine is called which takes the newly
 created symbol table and converts it into the chosen output format.
 
@@ -282,10 +285,13 @@ 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
+stored in the symbol table as long symbol names. 
+@c FIXME: is the enclosed text linker-specific?
+This information would
 be useless to most COFF debuggers and may be thrown away with
 appropriate command line switches. (The GNU debugger @code{gdb} does
 support @code{a.out} style debugging information in COFF).
+@c end linker-query FIXME
 
 There is one word of type information within the symbol, so if the
 format supports symbol type information within symbols (for example COFF,
@@ -328,24 +334,24 @@ What is a backend
 @node Memory Usage, Sections, bfd, Top
 @section Memory Usage
 BFD keeps all its internal structures in obstacks. There is one obstack
-per open bfd file, into which the current state is stored. When a bfd is
+per open BFD file, into which the current state is stored. When a BFD is
 closed, the obstack is deleted, and so everything which has been
 allocated by libbfd for the closing file will be thrown away.
 
 BFD will not free anything created by an application, but pointers into
-bfd structures will be invalidated on a @code{bfd_close}; for example,
+@code{bfd} structures will be invalidated on a @code{bfd_close}; for example,
 after a @code{bfd_close} the vector passed to
 @code{bfd_canonicalize_symtab} will still be around, since it has been
 allocated by the application, but the data that it pointed to will be
 lost.
 
-The general rule is not to close a bfd until all operations dependent
-upon data from the bfd have been completed, or all the data from within
+The general rule is not to close a BFD until all operations dependent
+upon data from the BFD have been completed, or all the data from within
 the file has been copied. To help with the management of memory, there is a function
 (@code{bfd_alloc_size}) which returns the number of bytes in obstacks
-associated with the supplied bfd. This could be used to select the
-greediest open bfd, close it to reclaim the memory, perform some
-operation and reopen the bfd again, to get a fresh copy of the data structures.
+associated with the supplied BFD. This could be used to select the
+greediest open BFD, close it to reclaim the memory, perform some
+operation and reopen the BFD again, to get a fresh copy of the data structures.
 
 @node Sections,Symbols ,Memory Usage, Top
 @include  section.texi
@@ -391,7 +397,7 @@ operation and reopen the bfd again, to get a fresh copy of the data structures.
 * srecord backend::
 @end menu
 @node What to Put Where, aout backends, BFD back end, BFD back end
-All of bfd lives in one directory.
+All of BFD lives in one directory.
 @page
 @node aout backends, coff backends, What to Put Where, BFD back end
 @include  aoutx.texi
diff --git a/bfd/cache.c b/bfd/cache.c
index c3418ea..be85f2b 100644
--- a/bfd/cache.c
+++ b/bfd/cache.c
@@ -1,45 +1,89 @@
-/*** cache.c -- Allows you to have more bfds open than your system has fds. */
+/* BFD library -- caching of file descriptors.
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Hacked by Steve Chamberlain of Cygnus Support (steve@cygnus.com).
 
-/* Copyright (C) 1990, 1991 Free Software Foundation, Inc.
+This file is part of BFD, the Binary File Descriptor library.
 
-This file is part of BFD, the Binary File Diddler.
-
-BFD is free software; you can redistribute it and/or modify
+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 1, or (at your option)
-any later version.
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
 
-BFD is distributed in the hope that it will be useful,
+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 BFD; see the file COPYING.  If not, write to
-the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
+
+/*doc*
+@section File Caching
+The file caching mechanism is embedded within BFD and allows the application to open as many
+BFDs as it wants without regard to the underlying operating system's
+file descriptor limit (often as low as 20 open files).
+
+The module in @code{cache.c} maintains a least recently used list of
+@code{BFD_CACHE_MAX_OPEN} files, and exports the name
+@code{bfd_cache_lookup} which runs around and makes sure that the
+required BFD is open. If not, then it chooses a file to close, closes
+it and opens the one wanted, returning its file handle.
+
+*/
+
+
 
 /* $Id$ */
-#include "sysdep.h"
+#include <sysdep.h>
 #include "bfd.h"
 #include "libbfd.h"
 
-/* The maximum number of FDs opened by bfd */
+
+/*proto-internal* BFD_CACHE_MAX_OPEN
+The maxiumum number of files which the cache will keep open at one
+time.
+*+
 #define BFD_CACHE_MAX_OPEN 10
+*-
+
+*/
+
 
-/* when this exceeds BFD_CACHE_MAX_OPEN, we get to work */
 static int open_files;
 
-static bfd *cache_sentinel;	/* Chain of bfds with active fds we've
+static bfd *cache_sentinel;	/* Chain of BFDs with active fds we've
 				   opened */
 
-bfd *bfd_last_cache;		/* Zero, or a pointer to the topmost
-				   bfd on the chain.  This is used by the
-				   bfd_cache_lookup() macro in libbfd.h
-				   to determine when it can avoid a function
-				   call.  */
+/*proto-internal*  bfd_last_cache
+Zero, or a pointer to the topmost BFD on the chain.  This is used by
+the @code{bfd_cache_lookup} macro in @file{libbfd.h} to determine when
+it can avoid a function call.
+*+
+extern bfd *bfd_last_cache;
+*-
+
+*/
+
+bfd *bfd_last_cache;
+
+/*proto-internal*  bfd_cache_lookup
+Checks to see if the required BFD is the same as the last one looked
+up. If so then it can use the iostream in the BFD with impunity, since
+it can't have changed since the last lookup, otherwise it has to
+perform the complicated lookup function
+*+
+#define bfd_cache_lookup(x) \
+     ((x)==bfd_last_cache? \
+        (FILE*)(bfd_last_cache->iostream): \
+         bfd_cache_lookup_worker(x))
+
+*-
+
+*/
 
 static void bfd_cache_delete();
-
+
 
 static void
 DEFUN_VOID(close_one)
@@ -59,7 +103,7 @@ DEFUN_VOID(close_one)
     bfd_cache_delete(kill);
 }
 
-/* Cuts the bfd abfd out of the chain in the cache */
+/* Cuts the BFD abfd out of the chain in the cache */
 static void 
 DEFUN(snip,(abfd),
       bfd *abfd)
@@ -100,7 +144,12 @@ DEFUN(insert,(x,y),
 }
 
 
-/* Initialize a BFD by putting it on the cache LRU.  */
+/*proto-internal*
+*i bfd_cache_init
+Initialize a BFD by putting it on the cache LRU.
+*; PROTO(void, bfd_cache_init, (bfd *));
+*-*/
+
 void
 DEFUN(bfd_cache_init,(abfd),
       bfd *abfd)
@@ -108,6 +157,12 @@ DEFUN(bfd_cache_init,(abfd),
   cache_sentinel = insert(abfd, cache_sentinel);
 }
 
+
+/*proto-internal*
+*i bfd_cache_close
+Remove the BFD from the cache. If the attatched file is open, then close it too.
+*; PROTO(void, bfd_cache_close, (bfd *));
+*-*/
 void
 DEFUN(bfd_cache_close,(abfd),
       bfd *abfd)
@@ -118,49 +173,60 @@ DEFUN(bfd_cache_close,(abfd),
       bfd_cache_delete(abfd);
     }
 }
-
-/* Call the OS to open a file for this BFD.  Returns the FILE *
-   (possibly null) that results from this operation.  Sets up the
-   BFD so that future accesses know the file is open.  */
 
+/*proto-internal*
+*i bfd_open_file
+Call the OS to open a file for this BFD.  Returns the FILE *
+(possibly null) that results from this operation.  Sets up the
+BFD so that future accesses know the file is open. If the FILE *
+returned is null, then there is won't have been put in the cache, so
+it won't have to be removed from it.
+*; PROTO(FILE *, bfd_open_file, (bfd *));
+*-*/
 FILE *
 DEFUN(bfd_open_file, (abfd),
       bfd *abfd)
 {
-    abfd->cacheable = true;	/* Allow it to be closed later. */
-    if(open_files >= BFD_CACHE_MAX_OPEN) {
-	close_one();
-    }
-    switch (abfd->direction) {
-      case read_direction:
-      case no_direction:
-	abfd->iostream = (char *) fopen(abfd->filename, "r");
-	break;
-      case both_direction:
-      case write_direction:
-	if (abfd->opened_once == true) {
-	    abfd->iostream = (char *) fopen(abfd->filename, "r+");
-	    if (!abfd->iostream) {
-		abfd->iostream = (char *) fopen(abfd->filename, "w+");
-	    }
-	} else {
-	    /*open for creat */
-	    abfd->iostream = (char *) fopen(abfd->filename, "w");
-	    abfd->opened_once = true;
-	}
-	break;
-    }
-    if (abfd->iostream) {
-	open_files++;
-	bfd_cache_init (abfd);
+  abfd->cacheable = true;	/* Allow it to be closed later. */
+  if(open_files >= BFD_CACHE_MAX_OPEN) {
+    close_one();
+  }
+  switch (abfd->direction) {
+  case read_direction:
+  case no_direction:
+    abfd->iostream = (char *) fopen(abfd->filename, "r");
+    break;
+  case both_direction:
+  case write_direction:
+    if (abfd->opened_once == true) {
+      abfd->iostream = (char *) fopen(abfd->filename, "r+");
+      if (!abfd->iostream) {
+	abfd->iostream = (char *) fopen(abfd->filename, "w+");
+      }
+    } else {
+      /*open for creat */
+      abfd->iostream = (char *) fopen(abfd->filename, "w");
+      abfd->opened_once = true;
     }
+    break;
+  }
+  if (abfd->iostream) {
+    open_files++;
+    bfd_cache_init (abfd);
+  }
 
-    return (FILE *)(abfd->iostream);
+  return (FILE *)(abfd->iostream);
 }
 
-/* Find a file descriptor for this BFD.  If necessary, open it.
-   If there are already more than BFD_CACHE_MAX_OPEN files open, try to close
-   one first, to avoid running out of file descriptors.  */
+/*proto-internal*
+*i bfd_cache_lookup_worker
+Called when the macro @code{bfd_cache_lookup} fails to find a quick
+answer. Finds a file descriptor for this BFD.  If necessary, it open it.
+If there are already more than BFD_CACHE_MAX_OPEN files open, it trys to close
+one first, to avoid running out of file descriptors. 
+*; PROTO(FILE *, bfd_cache_lookup_worker, (bfd *));
+
+*-*/
 
 FILE *
 DEFUN(bfd_cache_lookup_worker,(abfd),
@@ -179,7 +245,7 @@ DEFUN(bfd_cache_lookup_worker,(abfd),
 	  cache_sentinel = insert(abfd, cache_sentinel);
 	}
       }
-  /* This is a bfd without a stream -
+  /* This is a BFD without a stream -
      so it must have been closed or never opened.
      find an empty cache entry and use it.  */
   else 
diff --git a/bfd/coffcode.h b/bfd/coffcode.h
index 117a04f..4e3ad85 100644
--- a/bfd/coffcode.h
+++ b/bfd/coffcode.h
@@ -56,7 +56,7 @@ that they match what you need. You will probably also have to add
 @code{#ifdef}s to the code in @code{internalcoff.h} and
 @code{coffcode.h} if your version of coff is too wild.
 
-You can verify that your new bfd backend works quite simply by
+You can verify that your new BFD backend works quite simply by
 building @code{objdump} from the @code{binutils} directory, and
 making sure that its version of what's going on at your host systems
 idea (assuming it has the pretty standard coff dump utility (usually
@@ -69,7 +69,7 @@ it.
 @subsection How The Coff Backend Works
 
 @subsubsection Bit Twiddling
-Each flavour of coff supported in bfd has its own header file
+Each flavour of coff supported in BFD has its own header file
 descibing the external layout of the structures. There is also an
 internal description of the coff layout (in @code{internalcoff.h})
 file (@code{}). A major function of the coff backend is swapping the
@@ -83,15 +83,15 @@ number entry in coff is sometimes 16 bits, and sometimes 32 bits.
 @code{#define}ing @code{PUT_LNSZ_LNNO} and @code{GET_LNSZ_LNNO} will
 select the correct one. No doubt, some day someone will find a version
 of coff which has a varying field size not catered for at the moment.
-To port bfd, that person will have to add more @code{#defines}.
+To port BFD, that person will have to add more @code{#defines}.
 
 Three of the bit twiddling routines are exported to @code{gdb};
 @code{coff_swap_aux_in}, @code{coff_swap_sym_in} and
 @code{coff_swap_linno_in}. @code{GDB} reads the symbol table on its
-own, but uses bfd to fix things up.
+own, but uses BFD to fix things up.
 
 @subsubsection Symbol Reading
-The simple canonical form for symbols used by bfd is not rich enough
+The simple canonical form for symbols used by BFD is not rich enough
 to keep all the information available in a coff symbol table. The back
 end gets around this by keeping the original symbol table around,
 "behind the sceens". 
@@ -119,7 +119,7 @@ table. This pass moves all strings into memory, and replaces them with
 pointers to the strings.
 
 The symbol table is massaged once again, this time to create the
-canonical table used by the bfd application. Each symbol is inspected
+canonical table used by the BFD application. Each symbol is inspected
 in turn, and a decision made (using the @code{sclass} field) about the
 various flags to set in the @code{asymbol} @xref{Symbols}. The
 generated canonical table shares strings with the hidden internal
@@ -131,7 +131,7 @@ symbols which own the functions the linenumbers belong to.
 @subsubsection Symbol Writing
 Writing a symbol to a coff file which didn't come from a coff file
 will lose any debugging information. The @code{asymbol} structure
-remembers the bfd from which was born, and on output the back end
+remembers the BFD from which was born, and on output the back end
 makes sure that the same destination target as source target is
 present.
 
@@ -143,7 +143,7 @@ pointers to pointers. This allows applications like the linker to
 accumulate and output large symbol tables without having to do too
 much byte copying.
 
-The symbol table is not output to a writable bfd until it is closed. 
+The symbol table is not output to a writable BFD until it is closed. 
 The order of operations on the canonical symbol table at that point
 are:
 @table @code
@@ -155,7 +155,7 @@ field in the list with the offset from the first symbol of the current
 symbol. 
 
 Another function of this procedure is to turn the canonical value form
-of bfd into the form used by coff. Internally, bfd expects symbol
+of BFD into the form used by coff. Internally, BFD expects symbol
 values to be offsets from a section base; so a symbol physically at
 0x120, but in a section starting at 0x100, would have the value 0x20.
 Coff expects symbols to contain their final value, so symbols have
@@ -218,7 +218,7 @@ Each canonical asymbol really looks like this:
 $ typedef struct coff_symbol_struct
 $ {
 
-The actual symbol which the rest of bfd works with
+The actual symbol which the rest of BFD works with
 
 $   asymbol symbol;
 
@@ -2906,7 +2906,7 @@ sec_ptr         asect;
 
 /*doc*
 @subsubsection Reading Relocations
-Coff relocations are easily transformed into the internal bfd form
+Coff relocations are easily transformed into the internal BFD form
 (@code{arelent}). 
 
 Reading a coff relocation table is done in the following stages:
@@ -3079,7 +3079,7 @@ asymbol       **symbols;
 #ifndef NO_COFF_SYMBOLS
 
 /*
-provided a bfd, a section and an offset into the section, calculate and
+provided a BFD, a section and an offset into the section, calculate and
 return the name of the source file and the line nearest to the wanted
 location.
 */
@@ -3137,7 +3137,7 @@ DEFUN(coff_find_nearest_line,(abfd,
   }
   /* Now wander though the raw linenumbers of the section */
   /*
-    If this is the same bfd as we were previously called with and this is
+    If this is the same BFD as we were previously called with and this is
     the same section, and the offset we want is further down then we can
     prime the lookup loop
     */
diff --git a/bfd/core.c b/bfd/core.c
index 6835da4..7f1a328 100644
--- a/bfd/core.c
+++ b/bfd/core.c
@@ -49,7 +49,7 @@ DEFUN(bfd_core_file_failing_command,(abfd),
 
 /*proto* bfd_core_file_failing_signal
 Returns the signal number which caused the core dump which generated
-the file the bfd is attatched to.
+the file the BFD is attatched to.
 
 *; PROTO(int, bfd_core_file_failing_signal, (bfd *));
 */
diff --git a/bfd/format.c b/bfd/format.c
new file mode 100644
index 0000000..2dfc293
--- /dev/null
+++ b/bfd/format.c
@@ -0,0 +1,214 @@
+/* Generic BFD support for file formats.
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Written by Cygnus Support.
+
+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., 675 Mass Ave, Cambridge, MA 02139, USA.  */
+
+/*doc*
+@section File Formats
+A format is a BFD concept of high level file contents. The
+formats supported by BFD are:
+@table @code
+@item bfd_object
+The BFD may contain data, symbols, relocations and debug info.
+@item bfd_archive
+The BFD contains other BFDs and an optional index.
+@item bfd_core
+The BFD contains the result of an executable core dump.
+@end table
+*/
+#include "sysdep.h"
+#include "bfd.h"
+#include "libbfd.h"
+
+
+extern bfd_target *target_vector[];
+extern bfd_target *default_vector[];
+
+
+/*proto*
+*i bfd_check_format
+This routine is supplied a BFD and a format. It attempts to verify if
+the file attatched to the BFD is indeed compatible with the format
+specified (ie, one of @code{bfd_object}, @code{bfd_archive} or
+@code{bfd_core}).
+
+If the BFD has been set to a specific @var{target} before the call,
+only the named target and format combination will be checked. If the
+target has not been set, or has been set to @code{default} then all
+the known target backends will be interrogated to determine a match.
+
+The function returns @code{true} on success, otherwise @code{false}
+with one of the following error codes: 
+@table @code
+@item 
+invalid_operation
+if @code{format} is not one of @code{bfd_object}, @code{bfd_archive}
+or @code{bfd_core}.
+@item system_call_error
+if an error occured during a read -  even some file mismatches can
+cause system_call_errros
+@item file_not_recognised
+none of the backends recognised the file format
+@item file_ambiguously_recognized
+more than one backend recognised the file format.
+@end table
+*; PROTO(boolean, bfd_check_format, (bfd *abfd, bfd_format format));
+*-*/
+
+boolean
+DEFUN(bfd_check_format,(abfd, format),
+      bfd *abfd AND
+      bfd_format format)
+{
+  bfd_target **target, *save_targ, *right_targ;
+  int match_count;
+
+  if (!bfd_read_p (abfd) ||
+      ((int)(abfd->format) < (int)bfd_unknown) ||
+      ((int)(abfd->format) >= (int)bfd_type_end)) {
+    bfd_error = invalid_operation;
+    return false;
+  }
+
+  if (abfd->format != bfd_unknown)
+    return (abfd->format == format)? true: false;
+
+  /* presume the answer is yes */
+  abfd->format = format;
+
+  /* If the target type was explicitly specified, just check that target.  */
+
+  if (!abfd->target_defaulted) {
+    bfd_seek (abfd, (file_ptr)0, SEEK_SET);	/* rewind! */
+
+    right_targ = BFD_SEND_FMT (abfd, _bfd_check_format, (abfd));
+    if (right_targ) {
+      abfd->xvec = right_targ;		/* Set the target as returned */
+      return true;			/* File position has moved, BTW */
+    }
+    abfd->format = bfd_unknown;
+    return false;			/* Specified target is not right */
+  }
+
+  /* Since the target type was defaulted, check them 
+     all in the hope that one will be uniquely recognized.  */
+
+  save_targ = abfd->xvec;
+  match_count = 0;
+  right_targ = 0;
+
+  for (target = target_vector; *target != NULL; target++) {
+    bfd_target *temp;
+
+    abfd->xvec = *target;	/* Change BFD's target temporarily */
+    bfd_seek (abfd, (file_ptr)0, SEEK_SET);
+    temp = BFD_SEND_FMT (abfd, _bfd_check_format, (abfd));
+    if (temp) {				/* This format checks out as ok! */
+      right_targ = temp;
+      match_count++;
+      /* If this is the default target, accept it, even if other targets
+	 might match.  People who want those other targets have to set 
+	 the GNUTARGET variable.  */
+      if (temp == default_vector[0])
+	break;
+#ifdef GNU960
+      /* Big- and little-endian b.out archives look the same, but it doesn't
+       * matter: there is no difference in their headers, and member file byte
+       * orders will (I hope) be handled appropriately by bfd.  Ditto for big
+       * and little coff archives.  And the 4 coff/b.out object formats are
+       * unambiguous.  So accept the first match we find.
+       */
+      break;
+#endif
+    }
+  }
+
+  if (match_count == 1) {
+    abfd->xvec = right_targ;		/* Change BFD's target permanently */
+    return true;			/* File position has moved, BTW */
+  }
+
+  abfd->xvec = save_targ;		/* Restore original target type */
+  abfd->format = bfd_unknown;		/* Restore original format */
+  bfd_error = ((match_count == 0) ? file_not_recognized :
+	       file_ambiguously_recognized);
+  return false;
+}
+/*proto*
+*i bfd_set_format
+This function sets the file format of the supplied BFD to the format
+requested. If the target set in the BFD does not support the format
+requested, the format is illegal or the BFD is not open for writing
+than an error occurs.
+*; PROTO(boolean,bfd_set_format,(bfd *, bfd_format));
+*-*/
+boolean
+DEFUN(bfd_set_format,(abfd, format),
+      bfd *abfd AND
+      bfd_format format)
+{
+
+  if (bfd_read_p (abfd) ||
+      ((int)abfd->format < (int)bfd_unknown) ||
+      ((int)abfd->format >= (int)bfd_type_end)) {
+    bfd_error = invalid_operation;
+    return false;
+  }
+
+  if (abfd->format != bfd_unknown)
+    return (abfd->format == format) ? true:false;
+
+  /* presume the answer is yes */
+  abfd->format = format;
+
+  if (!BFD_SEND_FMT (abfd, _bfd_set_format, (abfd))) {
+    abfd->format = bfd_unknown;
+    return false;
+  }
+
+  return true;
+}
+
+
+/*proto*
+*i bfd_format_string
+This function takes one argument, and enumerated type (bfd_format) and
+returns a pointer to a const string "invalid", "object", "archive",
+"core" or "unknown" depending upon the value of the enumeration.
+*; PROTO(CONST char *, bfd_format_string, (bfd_format));
+*-*/
+
+CONST char *
+DEFUN(bfd_format_string,(format),
+     bfd_format format)
+{
+  if (((int)format <(int) bfd_unknown) 
+      || ((int)format >=(int) bfd_type_end)) 
+    return "invalid";
+  
+  switch (format) {
+  case bfd_object:
+    return "object";		/* linker/assember/compiler output */
+  case bfd_archive: 
+    return "archive";		/* object archive file */
+  case bfd_core: 
+    return "core";		/* core dump */
+  default: 
+    return "unknown";
+  }
+}
diff --git a/bfd/libbfd.h b/bfd/libbfd.h
index e33275d..bf84142 100644
--- a/bfd/libbfd.h
+++ b/bfd/libbfd.h
@@ -203,17 +203,17 @@ time.
 /*
 
   bfd_last_cache
-Zero, or a pointer to the topmost bfd on the chain.  This is used by the
-bfd_cache_lookup() macro in libbfd.h to determine when it can avoid a function
-call.  
+Zero, or a pointer to the topmost BFD on the chain.  This is used by
+the @code{bfd_cache_lookup} macro in @file{libbfd.h} to determine when
+it can avoid a function call.
 */
 extern bfd *bfd_last_cache;
 
 /*
 
   bfd_cache_lookup
-Checks to see if the required bfd is the same as the last one looked
-up. If so then it can use the iostream in the bfd with impunity, since
+Checks to see if the required BFD is the same as the last one looked
+up. If so then it can use the iostream in the BFD with impunity, since
 it can't have changed since the last lookup, otherwise it has to
 perform the complicated lookup function
 */
@@ -232,7 +232,7 @@ Initialize a BFD by putting it on the cache LRU.
 /*
 
 *i bfd_cache_close
-Remove the bfd from the cache. If the attatched file is open, then close it too.
+Remove the BFD from the cache. If the attatched file is open, then close it too.
 */
  PROTO(void, bfd_cache_close, (bfd *));
 
diff --git a/bfd/libcoff.h b/bfd/libcoff.h
index 42ca205..a29b9c2 100644
--- a/bfd/libcoff.h
+++ b/bfd/libcoff.h
@@ -135,7 +135,7 @@ Each canonical asymbol really looks like this:
  {
 
 /*
-The actual symbol which the rest of bfd works with
+The actual symbol which the rest of BFD works with
 */
 
    asymbol symbol;
diff --git a/bfd/opncls.c b/bfd/opncls.c
index 2601ef0..962eeb0 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -1,35 +1,35 @@
-/* opncls.c -- open and close a bfd. */
+/* opncls.c -- open and close a BFD.
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Written by Cygnus Support.
 
-/* Copyright (C) 1990, 1991 Free Software Foundation, Inc.
+This file is part of BFD, the Binary File Descriptor library.
 
-This file is part of BFD, the Binary File Diddler.
-
-BFD is free software; you can redistribute it and/or modify
+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 1, or (at your option)
-any later version.
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
 
-BFD is distributed in the hope that it will be useful,
+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 BFD; see the file COPYING.  If not, write to
-the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 
 /* $Id$ */
 
 #include <sysdep.h>
 #include "bfd.h"
 #include "libbfd.h"
-
+#include "obstack.h"
 extern void bfd_cache_init();
 FILE *bfd_open_file();
 
 /* fdopen is a loser -- we should use stdio exclusively.  Unfortunately
    if we do that we can't use fcntl.  */
-
+
 /** Locking 
 
    Locking is loosely controlled by the preprocessor variable
@@ -42,11 +42,12 @@ FILE *bfd_open_file();
    which, of course, knows about any other) we use the fcntl locks,
    because they're Posix.
 
-   The reason that bfd_openr and bfd_fdopenr exist, yet only bfd_openw
-   exists is because of locking.  When we do output, we lock the
-   filename file for output, then open a temporary file which does not
-   actually get its correct filename until closing time.  This is
-   safest, but requires the asymmetry in read and write entry points.
+   The reason that @code{bfd_openr} and @code{bfd_fdopenr} exist, yet
+   only @code{bfd_openw} exists is because of locking.  When we do
+   output, we lock the filename file for output, then open a temporary
+   file which does not actually get its correct filename until closing
+   time.  This is safest, but requires the asymmetry in read and write
+   entry points.
 
    Perhaps, since unix has so many different kinds of locking anyway,
    we should use the emacs lock scheme?... */
@@ -102,8 +103,8 @@ bfd *obfd;
 */
 /*proto*
 *i bfd_openr
-Opens the file supplied (using fopen) with the target supplied, it
-returns a pointer to the created bfd.
+Opens the file supplied (using @code{fopen}) with the target supplied, it
+returns a pointer to the created BFD.
 
 If NULL is returned then an error has occured.
 Possible errors are no_memory, invalid_target or system_call error.
@@ -152,7 +153,7 @@ DEFUN(bfd_openr, (filename, target),
  */
 /*proto*
 *i bfd_fdopenr
-bfd_fdopenr is to bfd_fopenr much like  fdopen is to fopen. It opens a bfd on
+bfd_fdopenr is to bfd_fopenr much like  fdopen is to fopen. It opens a BFD on
 a file already described by the @var{fd} supplied. 
 
 Possible errors are no_memory, invalid_target and system_call error.
@@ -230,12 +231,12 @@ DEFUN(bfd_fdopenr,(filename, target, fd),
 }
 
 /** bfd_openw -- open for writing.
-  Returns a pointer to a freshly-allocated bfd on success, or NULL.
+  Returns a pointer to a freshly-allocated BFD on success, or NULL.
 
   See comment by bfd_fdopenr before you try to modify this function. */
 
 /*proto* bfd_openw
-Creates a bfd, associated with file @var{filename}, using the file
+Creates a BFD, associated with file @var{filename}, using the file
 format @var{target}, and returns a pointer to it.
 
 Possible errors are system_call_error, no_memory, invalid_target.
@@ -276,12 +277,12 @@ DEFUN(bfd_openw,(filename, target),
 }
 
 /*proto* bfd_close
-This function closes a bfd. If the bfd was open for writing, then
+This function closes a BFD. If the BFD was open for writing, then
 pending operations are completed and the file written out and closed.
 If the created file is executable, then @code{chmod} is called to mark
 it as such.
 
-All memory attatched to the bfd's obstacks is released. 
+All memory attatched to the BFD's obstacks is released. 
 
 @code{true} is returned if all is ok, otherwise @code{false}.
 *; PROTO(boolean, bfd_close,(bfd *));
@@ -323,8 +324,8 @@ DEFUN(bfd_close,(abfd),
 }
 
 /*proto* bfd_create
-This routine creates a new bfd in the manner of bfd_openw, but without
-opening a file. The new bfd takes the target from the target used by
+This routine creates a new BFD in the manner of @code{bfd_openw}, but without
+opening a file. The new BFD takes the target from the target used by
 @var{template}. The format is always set to @code{bfd_object}.
 
 *; PROTO(bfd *, bfd_create, (CONST char *filename, bfd *template));
@@ -364,7 +365,7 @@ DEFUN(void bfd_alloc_grow,(abfd, ptr, size),
       PTR ptr AND
       bfd_size_type size)
 {
-   obstack_grow(&(abfd->memory), ptr, size);
+  (void)   obstack_grow(&(abfd->memory), ptr, size);
 }
 DEFUN(PTR bfd_alloc_finish,(abfd),
       bfd *abfd)
@@ -400,7 +401,7 @@ DEFUN(PTR bfd_realloc,(abfd, old, size),
 
 /*proto* bfd_alloc_size
 Return the number of bytes in the obstacks connected to the supplied
-bfd.
+BFD.
 *; PROTO(bfd_size_type,bfd_alloc_size,(bfd *abfd));
 */
 
diff --git a/bfd/reloc.c b/bfd/reloc.c
index 7e44374..ae699d6 100644
--- a/bfd/reloc.c
+++ b/bfd/reloc.c
@@ -21,16 +21,16 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
 /*doc*
 @section Relocations
 
-Bfd maintains relocations in much the same was as it maintains
+BFD maintains relocations in much the same was as it maintains
 symbols; they are left alone until required, then read in en-mass and
 traslated into an internal form. There is a common routine
 @code{bfd_perform_relocation} which acts upon the canonical form to to
 the actual fixup.
 
 Note that relocations are maintained on a per section basis, whilst
-symbols are maintained on a per bfd basis.
+symbols are maintained on a per BFD basis.
 
-All a back end has to do to fit the bfd interface is to create as many
+All a back end has to do to fit the BFD interface is to create as many
 @code{struct reloc_cache_entry} as there are relocations in a
 particuar section, and fill in the right bits:
 
@@ -249,7 +249,7 @@ relocation emitted has no symbol, just a section to relocate against.
 
 I'm not sure what it means when both a symbol pointer an a section
 pointer are present. Some formats use this sort of mechanism to
-describe PIC relocations, but bfd can't to that sort of thing yet.
+describe PIC relocations, but BFD can't to that sort of thing yet.
 @item howto
 The howto field can be imagined as a relocation instruction. It is a
 pointer to a struct which contains information on what to do with all
@@ -263,7 +263,7 @@ possible to create each howto field on demand.
 
 /*proto* reloc_howto_type
 The @code{reloc_howto_type} is a structure which contains all the
-information that bfd needs to know to tie up a back end's data.
+information that BFD needs to know to tie up a back end's data.
 
 *+++
 
diff --git a/bfd/section.c b/bfd/section.c
index 099f0bd..f5b2137 100644
--- a/bfd/section.c
+++ b/bfd/section.c
@@ -1,9 +1,29 @@
+/* Object file "section" support for the BFD library.
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Written by Cygnus Support.
+
+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., 675 Mass Ave, Cambridge, MA 02139, USA.  */
+
 /*doc*
 @section Sections
-Sections are supported in bfd in @code{section.c}.
+Sections are supported in BFD in @code{section.c}.
 
-The raw data contained within a bfd is maintained through the section
-abstraction.  A single bfd may have any number of sections, and keeps
+The raw data contained within a BFD is maintained through the section
+abstraction.  A single BFD may have any number of sections, and keeps
 hold of them by pointing to the first, each one points to the next in
 the list.
 
@@ -17,18 +37,18 @@ the list.
 @node Section Input, Section Output,,Sections
 @comment  node-name,  next,  previous,  up
 @subsection Section Input
-When a bfd is opened for reading, the section structures are created
-and attatched to the bfd.
+When a BFD is opened for reading, the section structures are created
+and attatched to the BFD.
 
 Each section has a name which describes the section in the outside
 world - for example, @code{a.out} would contain at least three
 sections, called @code{.text}, @code{.data} and @code{.bss}. 
 
-Sometimes a bfd will contain more than the 'natural' number of
+Sometimes a BFD will contain more than the 'natural' number of
 sections. A back end may attatch other sections containing constructor
 data, or an application may add a section (using bfd_make_section) to
-the sections attatched to an already open bfd. For example, the linker
-creates a supernumary section @code{COMMON} for each input file's bfd
+the sections attatched to an already open BFD. For example, the linker
+creates a supernumary section @code{COMMON} for each input file's BFD
 to hold information about common storage.
 
 The raw data is not necessarily read in at the same time as the
@@ -42,8 +62,8 @@ the data and relocations.
 
 @node Section Output,typedef asection,Section Input,Sections
 @subsection Section Output
-To write a new object style bfd, the various sections to be written
-have to be created. They are attatched to the bfd in the same way as
+To write a new object style BFD, the various sections to be written
+have to be created. They are attatched to the BFD in the same way as
 input sections, data is written to the sections using
 @code{bfd_set_section_contents}. 
 
@@ -99,7 +119,7 @@ the same as that passed to bfd_make_section.
 
 $    CONST char *name;
 
-The next section in the list belonging to the bfd, or NULL.
+The next section in the list belonging to the BFD, or NULL.
 
 $    struct sec *next;
 
@@ -159,6 +179,15 @@ peform on standard data.
 
 $#define SEC_CONSTRUCTOR 0x100
 
+The section is a constuctor, and should be placed at the end of the ..
+
+$#define SEC_CONSTRUCTOR_TEXT 0x1100
+
+$#define SEC_CONSTRUCTOR_DATA 0x2100
+
+$#define SEC_CONSTRUCTOR_BSS  0x3100
+
+
 The section has contents - a bss section could be
 @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}, a debug section could be
 @code{SEC_HAS_CONTENTS}
@@ -170,6 +199,7 @@ this flag even if they have information which would normally be written.
 
 $#define SEC_NEVER_LOAD 0x400
 
+
 The base address of the section in the address space of the target.
 
 $   bfd_vma vma;
@@ -256,7 +286,7 @@ relocations created to relocate items within it.
 
 $   struct relent_chain *constructor_chain;
 
-The bfd which owns the section.
+The BFD which owns the section.
 
 $   bfd *owner;
 
@@ -293,14 +323,14 @@ DEFUN(bfd_get_section_by_name,(abfd, name),
 
 /*proto* bfd_make_section
 This function creates a new empty section called @var{name} and attatches it
-to the end of the chain of sections for @var{bfd}. An attempt to
+to the end of the chain of sections for the BFD supplied. An attempt to
 create a section with a name which is already in use, returns the old
 section by that name instead.
 
 Possible errors are:
 @table @code
 @item invalid_operation
-If output has already started for this bfd.
+If output has already started for this BFD.
 @item no_memory
 If obstack alloc fails.
 @end table
@@ -357,7 +387,7 @@ DEFUN(bfd_make_section,(abfd, name),
 
 
 /*proto* bfd_set_section_flags
-Attempts to set the attributes of the section named in the bfd
+Attempts to set the attributes of the section named in the BFD
 supplied to the value. Returns true on success, false on error.
 Possible error returns are:
 @table @code
@@ -389,7 +419,7 @@ DEFUN(bfd_set_section_flags,(abfd, section, flags),
 
 /*proto* bfd_map_over_sections
 Calls the provided function @var{func} for each section attatched to
-the bfd @var{abfd}, passing @var{obj} as an argument. The function
+the BFD @var{abfd}, passing @var{obj} as an argument. The function
 will be called as if by 
 
 @example
@@ -435,7 +465,7 @@ Sets @var{section} to the size @var{val}. If the operation is ok, then
 Possible error returns:
 @table @code
 @item invalid_operation
-Writing has started to the bfd, so setting the size is invalid
+Writing has started to the BFD, so setting the size is invalid
 @end table 
 
 *; PROTO(boolean, bfd_set_section_size,
@@ -446,7 +476,7 @@ boolean
 DEFUN(bfd_set_section_size,(abfd, ptr, val),
       bfd *abfd AND
       sec_ptr ptr AND
-      unsigned long val)
+      bfd_size_type val)
 {
   /* Once you've started writing to any section you cannot create or change
      the size of any others. */
@@ -462,7 +492,7 @@ DEFUN(bfd_set_section_size,(abfd, ptr, val),
 }
 
 /*proto* bfd_set_section_contents
-Sets the contents of the section @var{section} in bfd @var{abfd} to
+Sets the contents of the section @var{section} in BFD @var{abfd} to
 the data starting in memory at @var{data}. The data is written to the
 output section starting at offset @var{offset} for @var{count} bytes.
 
@@ -510,7 +540,7 @@ DEFUN(bfd_set_section_contents,(abfd, section, location, offset, count),
 }
 
 /*proto* bfd_get_section_contents
-This function reads data from @var{section} in bfd @var{abfd} into
+This function reads data from @var{section} in BFD @var{abfd} into
 memory starting at @var{location}. The data is read at an offset of
 @var{offset} from the start of the input section, and is read for
 @var{count} bytes.
diff --git a/bfd/syms.c b/bfd/syms.c
new file mode 100644
index 0000000..ec1df2a
--- /dev/null
+++ b/bfd/syms.c
@@ -0,0 +1,372 @@
+/* Generic symbol-table support for the BFD library.
+   Copyright (C) 1990-1991 Free Software Foundation, Inc.
+   Written by Cygnus Support.
+
+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., 675 Mass Ave, Cambridge, MA 02139, USA.  */
+
+/*doc*
+@section Symbols
+BFD trys to maintain as much symbol information as it can when it
+moves information from file to file. BFD passes information to
+applications though the @code{asymbol} structure. When the application
+requests the symbol table, BFD reads the table in the native form and
+translates parts of it into the internal format. To maintain more than
+the infomation passed to applications some targets keep
+some information 'behind the sceans', in a structure only the
+particular back end knows about. For example, the coff back end keeps
+the original symbol table structure as well as the canonical structure
+when a BFD is read in. On output, the coff back end can reconstruct
+the output symbol table so that no information is lost, even
+information unique to coff which BFD doesn't know or understand. If a
+coff symbol table was read, but was written through an a.out back end,
+all the coff specific information would be lost. (.. until BFD 2 :).
+
+The symbol table of a BFD is not necessarily read in until a
+canonicalize request is made. Then the BFD back end fills in a table
+provided by the application with pointers to the canonical
+information.
+
+To output symbols, the application provides BFD with a table of
+pointers to pointers to @code{asymbol}s. This allows applications like
+the linker to output a symbol as read, since the 'behind the sceens'
+information will be still available.
+
+@menu
+* Reading Symbols::
+* Writing Symbols::
+* typedef asymbol::
+* symbol handling functions::
+@end menu
+
+@node Reading Symbols, Writing Symbols, Symbols, Symbols
+@subsection Reading Symbols
+There are two stages to reading a symbol table from a BFD; allocating
+storage, and the actual reading process. This is an excerpt from an
+appliction which reads the symbol table:
+
+*+
+  unsigned int storage_needed;
+  asymbol **symbol_table;
+  unsigned int number_of_symbols;
+  unsigned int i;
+
+  storage_needed = get_symtab_upper_bound (abfd);
+
+  if (storage_needed == 0) {
+     return ;
+  }
+  symbol_table = (asymbol **) malloc (storage_needed);
+    ...
+  number_of_symbols = 
+     bfd_canonicalize_symtab (abfd, symbol_table); 
+
+  for (i = 0; i < number_of_symbols; i++) {
+     process_symbol (symbol_table[i]);
+  }
+*-
+
+All storage for the symbols themselves is in an obstack connected to
+the BFD, and is freed when the BFD is closed.
+
+@node Writing Symbols, typedef asymbol, Reading Symbols, Symbols
+@subsection Writing Symbols
+Writing of a symbol table is automatic when a BFD open for writing
+is closed. The application attatches a vector of pointers to pointers to symbols
+to the BFD being written, and fills in the symbol count. The close and
+cleanup code reads through the table provided and performs all the
+necessary operations. The outputing code must always be provided with
+an 'owned' symbol; one which has come from another BFD, or one which
+has been created using @code{bfd_make_empty_symbol}. 
+
+An example showing the creation of a symbol table with only one
+element:
+
+*+
+#include "bfd.h"
+main() 
+{
+  bfd *abfd;
+  asymbol *ptrs[2];
+  asymbol *new;
+
+  abfd = bfd_openw("foo","a.out-sunos-big");
+  bfd_set_format(abfd, bfd_object);
+  new = bfd_make_empty_symbol(abfd);
+  new->name = "dummy_symbol";
+  new->section = (asection *)0;
+  new->flags = BSF_ABSOLUTE | BSF_GLOBAL;
+  new->value = 0x12345;
+
+  ptrs[0] = new;
+  ptrs[1] = (asymbol *)0;
+  
+  bfd_set_symtab(abfd, ptrs, 1);
+  bfd_close(abfd);
+}
+
+./makesym 
+nm foo
+00012345 A dummy_symbol
+
+
+*-
+
+Many formats cannot represent arbitary symbol information; for
+instance the @code{a.out} object format does not allow an arbitary
+number of sections. A symbol pointing to a section which is not one of
+@code{.text}, @code{.data} or @code{.bss} cannot be described.
+*/
+
+
+/*doc*
+@node typedef asymbol, symbol handling functions, Writing Symbols, Symbols
+
+*/
+/*proto*
+@subsection typedef asymbol
+An @code{asymbol} has the form:
+
+*+++
+
+$typedef struct symbol_cache_entry 
+${
+A pointer to the BFD which owns the symbol. This information is
+necessary so that a back end can work out what additional (invisible to
+the application writer) information is carried with the symbol. 
+
+$  struct _bfd *the_bfd;
+
+The text of the symbol. The name is left alone, and not copied - the
+application may not alter it. 
+
+$   CONST char *name;
+
+The value of the symbol.
+
+$   symvalue value;
+
+Attributes of a symbol:
+
+$#define BSF_NO_FLAGS    0x00
+
+The symbol has local scope; @code{static} in @code{C}. The value is
+the offset into the section of the data.
+
+$#define BSF_LOCAL	0x01
+
+The symbol has global scope; initialized data in @code{C}. The value
+is the offset into the section of the data.
+
+$#define BSF_GLOBAL	0x02
+
+Obsolete
+
+$#define BSF_IMPORT	0x04
+
+The symbol has global scope, and is exported. The value is the offset
+into the section of the data.
+
+$#define BSF_EXPORT	0x08
+
+The symbol is undefined. @code{extern} in @code{C}. The value has no meaning.
+
+$#define BSF_UNDEFINED	0x10	
+
+The symbol is common, initialized to zero; default in @code{C}. The
+value is the size of the object in bytes.
+
+$#define BSF_FORT_COMM	0x20	
+
+A normal @code{C} symbol would be one of:
+@code{BSF_LOCAL}, @code{BSF_FORT_COMM},  @code{BSF_UNDEFINED} or @code{BSF_EXPORT|BSD_GLOBAL}
+
+The symbol is a debugging record. The value has an arbitary meaning.
+
+$#define BSF_DEBUGGING	0x40
+
+The symbol has no section attached, any value is the actual value and
+is not a relative offset to a section.
+
+$#define BSF_ABSOLUTE	0x80
+
+Used by the linker
+
+$#define BSF_KEEP        0x10000
+$#define BSF_KEEP_G      0x80000
+
+Unused
+
+$#define BSF_WEAK        0x100000
+$#define BSF_CTOR        0x200000 
+$#define BSF_FAKE        0x400000 
+
+The symbol used to be a common symbol, but now it is allocated.
+
+$#define BSF_OLD_COMMON  0x800000  
+
+The default value for common data.
+
+$#define BFD_FORT_COMM_DEFAULT_VALUE 0
+
+In some files the type of a symbol sometimes alters its location
+in an output file - ie in coff a @code{ISFCN} symbol which is also @code{C_EXT}
+symbol appears where it was declared and not at the end of a section. 
+This bit is set by the target BFD part to convey this information. 
+
+$#define BSF_NOT_AT_END    0x40000
+
+Signal that the symbol is the label of constructor section.
+
+$#define BSF_CONSTRUCTOR   0x1000000
+
+Signal that the symbol is a warning symbol. If the symbol is a warning
+symbol, then the value field (I know this is tacky) will point to the
+asymbol which when referenced will cause the warning.
+
+$#define BSF_WARNING       0x2000000
+
+Signal that the symbol is indirect. The value of the symbol is a
+pointer to an undefined asymbol which contains the name to use
+instead.
+
+$#define BSF_INDIRECT     0x4000000
+
+$  flagword flags;
+
+Aointer to the section to which this symbol is relative, or 0 if the
+symbol is absolute or undefined. Note that it is not sufficient to set
+this location to 0 to mark a symbol as absolute - the flag
+@code{BSF_ABSOLUTE} must be set also.
+
+$  struct sec *section;
+
+Back end special data. This is being phased out in favour of making
+this a union.
+
+$  PTR udata;	
+$} asymbol;
+*---
+
+*/
+
+#include "sysdep.h"
+#include "bfd.h"
+#include "libbfd.h"
+ 
+/*doc*
+@node symbol handling functions, Symbols, typedef asymbol, Symbols
+@subsection Symbol Handling Functions
+
+*/
+
+/*proto* get_symtab_upper_bound
+Returns the number of bytes required in a vector of pointers to
+@code{asymbols} for all the symbols in the supplied BFD, including a
+terminal NULL pointer. If there are no symbols in the BFD, then 0 is
+returned.
+*+
+#define get_symtab_upper_bound(abfd) \
+     BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
+*-
+
+*/
+
+/*proto* bfd_canonicalize_symtab
+Supplied a BFD and a pointer to an uninitialized vector of pointers.
+This reads in the symbols from the BFD, and fills in the table with
+pointers to the symbols, and a trailing NULL. The routine returns the
+actual number of symbol pointers not including the NULL.
+
+*+
+#define bfd_canonicalize_symtab(abfd, location) \
+     BFD_SEND (abfd, _bfd_canonicalize_symtab,\
+                  (abfd, location))
+
+*-
+*/
+
+
+/*proto* bfd_set_symtab
+Provided a table of pointers to to symbols and a count, writes to the
+output BFD the symbols when closed.
+
+*; PROTO(boolean, bfd_set_symtab, (bfd *, asymbol **, unsigned int ));
+*/
+
+boolean
+bfd_set_symtab (abfd, location, symcount)
+     bfd *abfd;
+     asymbol **location;
+     unsigned int symcount;
+{
+  if ((abfd->format != bfd_object) || (bfd_read_p (abfd))) {
+    bfd_error = invalid_operation;
+    return false;
+  }
+
+  bfd_get_outsymbols (abfd) = location;
+  bfd_get_symcount (abfd) = symcount;
+  return true;
+}
+
+/*proto* bfd_print_symbol_vandf
+Prints the value and flags of the symbol supplied to the stream file.
+
+*; PROTO(void, bfd_print_symbol_vandf, (PTR file, asymbol *symbol));
+*/
+void
+DEFUN(bfd_print_symbol_vandf,(file, symbol),
+PTR file AND
+asymbol *symbol)
+{
+  flagword type = symbol->flags;
+  if (symbol->section != (asection *)NULL)
+      {
+	fprintf_vma(file, symbol->value+symbol->section->vma);
+      }
+  else 
+      {
+	fprintf_vma(file, symbol->value);
+      }
+  fprintf(file," %c%c%c%c%c%c%c%c%c%c",
+	  (type & BSF_LOCAL)  ? 'l':' ',
+	  (type & BSF_GLOBAL) ? 'g' : ' ',
+	  (type & BSF_IMPORT) ? 'i' : ' ',
+	  (type & BSF_EXPORT) ? 'e' : ' ',
+	  (type & BSF_UNDEFINED) ? 'u' : ' ',
+	  (type & BSF_FORT_COMM) ? 'c' : ' ',
+	  (type & BSF_CONSTRUCTOR) ? 'C' : ' ',
+	  (type & BSF_WARNING) ? 'W' : ' ',
+	  (type & BSF_INDIRECT) ? 'I' : ' ',
+	  (type & BSF_DEBUGGING) ? 'd' :' ');
+
+}
+
+
+/*proto*  bfd_make_empty_symbol
+This function creates a new @code{asymbol} structure for the BFD, and
+returns a pointer to it.
+
+This routine is necessary, since each back end has private information
+surrounding the @code{asymbol}. Building your own @code{asymbol} and
+pointing to it will not create the private information, and will cause
+problems later on.
+*+
+#define bfd_make_empty_symbol(abfd) \
+     BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
+*-
+*/