   This file documents the BFD library.

   Copyright (C) 1991 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

typedef asymbol
---------------

An `asymbol' has the form:
.
     typedef struct symbol_cache_entry
     {
     		/* A pointer to the BFD which owns the symbol. This information
     	   is necessary so that a back end can work out what additional
        	   information (invisible to the application writer) is carried
     	   with the symbol.

     	   This field is *almost* redundant, since you can use section->owner
     	   instead, except that some symbols point to the global sections
     	   bfd_{abs,com,und}_section.  This could be fixed by making
     	   these globals be per-bfd (or per-target-flavor).  FIXME. */

       struct _bfd *the_bfd; 	/* Use bfd_asymbol_bfd(sym) to access this field. */

     		/* 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.  This really should be a union of a
               numeric value with a pointer, since some flags indicate that
               a pointer to another symbol is stored here.  */
       symvalue value;

     		/* Attributes of a symbol: */

     #define BSF_NO_FLAGS    0x00

     		/* The symbol has local scope; `static' in `C'. The value
      	   is the offset into the section of the data. */
     #define BSF_LOCAL	0x01

     		/* The symbol has global scope; initialized data in `C'. The
     	   value is the offset into the section of the data. */
     #define BSF_GLOBAL	0x02

     		/* The symbol has global scope, and is exported. The value is
     	   the offset into the section of the data. */
     #define BSF_EXPORT	BSF_GLOBAL 	/* no real difference */

     		/* A normal C symbol would be one of:
     	   `BSF_LOCAL', `BSF_FORT_COMM',  `BSF_UNDEFINED' or
     	   `BSF_GLOBAL' */

     		/* The symbol is a debugging record. The value has an arbitary
     	   meaning. */
     #define BSF_DEBUGGING	0x08

     		/* The symbol denotes a function entry point.  Used in ELF,
     	   perhaps others someday.  */
     #define BSF_FUNCTION    0x10

     		/* Used by the linker. */
     #define BSF_KEEP        0x20
     #define BSF_KEEP_G      0x40

     		/* A weak global symbol, overridable without warnings by
     	   a regular global symbol of the same name.  */
     #define BSF_WEAK        0x80

            	/* This symbol was created to point to a section, e.g. ELF's
     	   STT_SECTION symbols.  */
     #define BSF_SECTION_SYM 0x100

     		/* The symbol used to be a common symbol, but now it is
     	   allocated. */
     #define BSF_OLD_COMMON  0x200

     		/* The default value for common data. */
     #define BFD_FORT_COMM_DEFAULT_VALUE 0

     		/* In some files the type of a symbol sometimes alters its
     	   location in an output file - ie in coff a `ISFCN' symbol
     	   which is also `C_EXT' symbol appears where it was
     	   declared and not at the end of a section.  This bit is set
       	   by the target BFD part to convey this information. */

     #define BSF_NOT_AT_END    0x400

     		/* Signal that the symbol is the label of constructor section. */
     #define BSF_CONSTRUCTOR   0x800

     		/* 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       0x1000

     		/* 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      0x2000

     		/* BSF_FILE marks symbols that contain a file name.  This is used
     	   for ELF STT_FILE symbols.  */
     #define BSF_FILE          0x4000

       flagword flags;

     		/* A pointer to the section to which this symbol is
     	   relative.  This will always be non NULL, there are special
               sections for undefined and absolute symbols */
       struct sec *section;

     		/* Back end special data. This is being phased out in favour
     	   of making this a union. */
       PTR udata;

     } asymbol;

Symbol Handling Functions
-------------------------

`get_symtab_upper_bound'
........................

*Description*
Returns the number of bytes required in a vector of pointers to
`asymbols' for all the symbols in the supplied BFD, including a
terminal NULL pointer. If there are no symbols in the BFD, then 0 is
returned.
     #define get_symtab_upper_bound(abfd) \
          BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))

`bfd_canonicalize_symtab'
.........................

*Description*
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))

`bfd_set_symtab'
................

*Description*
Provided a table of pointers to symbols and a count, writes to the
output BFD the symbols when closed.
*Synopsis*
     boolean bfd_set_symtab (bfd *, asymbol **, unsigned int );

`bfd_print_symbol_vandf'
........................

   *Description*
Prints the value and flags of the symbol supplied to the stream file.
*Synopsis*
     void bfd_print_symbol_vandf(PTR file, asymbol *symbol);

`bfd_make_empty_symbol'
.......................

   *Description*
This function creates a new `asymbol' structure for the BFD, and
returns a pointer to it.  This routine is necessary, since each back
end has private information surrounding the `asymbol'. Building your own
`asymbol' and pointing to it will not create the private information,
and will cause problems later on.
     #define bfd_make_empty_symbol(abfd) \
          BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))

`bfd_make_debug_symbol'
.......................

*Description*
This function creates a new `asymbol' structure for the BFD, to be used
as a debugging symbol.  Further details of its use have yet to be
worked out.
     #define bfd_make_debug_symbol(abfd,ptr,size) \
             BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))

`bfd_decode_symclass'
.....................

*Description*
Return a character corresponding to the symbol class of symbol, or '?'
for an unknown class.
*Synopsis*
     int bfd_decode_symclass(asymbol *symbol);

`bfd_symbol_info'
.................

   *Description*
Fill in the basic info about symbol that nm needs.  Additional info may
be added by the back-ends after calling this function.
*Synopsis*
     void bfd_symbol_info(asymbol *symbol, symbol_info *ret);

Archives
========

*Description*
Archives are supported in BFD in `archive.c'.  An archive (or library)
is just another BFD.  It has a symbol table, although there's not much
a user program will do with it.  The big difference between an archive
BFD and an ordinary BFD is that the archive doesn't have sections.
Instead it has a chain of BFDs considered its contents.  These BFDs can
be manipulated just like any other.  The BFDs contained in an archive
opened for reading will all be opened for reading; you may put either
input or output BFDs into an archive opened for output; it will be
handled correctly when the archive is closed.  Use
`bfd_openr_next_archived_file' to step through all the contents of an
archive opened for input.  It's not required that you read the entire
archive if you don't want to!  Read it until you find what you want.
Archive contents of output BFDs are chained through the `next' pointer
in a BFD.  The first one is findable through the `archive_head' slot of
the archive.  Set it with `set_archive_head' (q.v.).  A given BFD may
be in only one open output archive at a time.  As expected, the BFD
archive code is more general than the archive code of any given
environment.  BFD archives may contain files of different formats
(e.g., a.out and coff) and even different architectures.  You may even
place archives recursively into archives!  This can cause unexpected
confusion, since some archive formats are more expressive than others.
For instance, Intel COFF archives can preserve long filenames; Sun
a.out archives cannot.  If you move a file from the first to the second
format and back again, the filename may be truncated.  Likewise,
different a.out environments have different conventions as to how they
truncate filenames, whether they preserve directory names in filenames,
etc.  When interoperating with native tools, be sure your files are
homogeneous.  Beware: most of these formats do not react well to the
presence of spaces in filenames.  We do the best we can, but can't
always handle this due to restrctions in the format of archives.  Many
unix utilities are braindead in regards to spaces and such in filenames
anyway, so this shouldn't be much of a restriction.
`bfd_get_next_mapent'
.....................

*Synopsis*
     symindex bfd_get_next_mapent(bfd *, symindex previous, carsym ** sym);
   *Description*
This function steps through an archive's symbol table (if it has one).
Successively updates `sym' with the next symbol's information,
returning that symbol's (internal) index into the symbol table.  Supply
BFD_NO_MORE_SYMBOLS as the `previous' entry to get the first one;
returns BFD_NO_MORE_SYMBOLS when you're already got the last one.  A
`carsym' is a canonical archive symbol.  The only user-visible element
is its name, a null-terminated string.
`bfd_set_archive_head'
......................

*Synopsis*
     boolean bfd_set_archive_head(bfd *output, bfd *new_head);
   *Description*
Used whilst processing archives. Sets the head of the chain of BFDs
contained in an archive to NEW_HEAD.
`bfd_get_elt_at_index'
......................

*Synopsis*
     bfd *bfd_get_elt_at_index(bfd * archive, int index);
   *Description*
Return the bfd which is referenced by the symbol indexed by `index'.
`index' should have been returned by `bfd_get_next_mapent' (q.v.).
`bfd_openr_next_archived_file'
..............................

*Synopsis*
     bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
   *Description*
Initially provided a BFD containing an archive and NULL, opens an
inpout BFD on the first contained element and returns that.  Subsequent
calls to bfd_openr_next_archived_file should pass the archive and the
previous return value to return a created BFD to the next contained
element. NULL is returned when there are no more.

File Formats
============

A format is a BFD concept of high level file contents. The formats
supported by BFD are:
   * bfd_object The BFD may contain data, symbols, relocations and
debug info.
   * bfd_archive The BFD contains other BFDs and an optional index.
   * bfd_core The BFD contains the result of an executable core dump.
`bfd_check_format'
..................

*Synopsis*
     boolean bfd_check_format(bfd *abfd, bfd_format format);
   *Description*
This routine is supplied a BFD and a format. It attempts to verify if
the file attached to the BFD is indeed compatible with the format
specified (ie, one of `bfd_object', `bfd_archive' or `bfd_core').  If
the BFD has been set to a specific 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 `default' then all the known target
backends will be interrogated to determine a match.  If the default
target matches, it is used.  If not, exactly one target must recognize
the file, or an error results.  The function returns `true' on success,
otherwise `false' with one of the following error codes:

   * invalid_operation - if `format' is not one of `bfd_object',
     `bfd_archive' or `bfd_core'.

   * system_call_error - if an error occured during a read - even some
     file mismatches can cause system_call_errors

   * file_not_recognised - none of the backends recognised the file
     format

   * file_ambiguously_recognized - more than one backend recognised the
     file format.
`bfd_set_format'
................

*Synopsis*
     boolean bfd_set_format(bfd *, bfd_format);
   *Description*
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.
`bfd_format_string'
...................

*Synopsis*
     CONST char *bfd_format_string(bfd_format);
   *Description*
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.

Relocations
===========

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
`bfd_perform_relocation' which acts upon the canonical form to do the
actual fixup.  Note that relocations are maintained on a per section
basis, whilst 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 `struct
reloc_cache_entry' as there are relocations in a particular section,
and fill in the right bits:

typedef arelent
---------------

This is the structure of a relocation entry:
.
     typedef enum bfd_reloc_status
     {
            	/* No errors detected */
       bfd_reloc_ok,

            	/* The relocation was performed, but there was an overflow. */
       bfd_reloc_overflow,

            	/* The address to relocate was not within the section supplied. */
       bfd_reloc_outofrange,

            	/* Used by special functions */
       bfd_reloc_continue,

            	/* Unused */
       bfd_reloc_notsupported,

            	/* Unsupported relocation size requested. */
       bfd_reloc_other,

            	/* The symbol to relocate against was undefined. */
       bfd_reloc_undefined,

            	/* The relocation was performed, but may not be ok - presently
               generated only when linking i960 coff files with i960 b.out
               symbols. */
       bfd_reloc_dangerous
      }
      bfd_reloc_status_type;

     typedef struct reloc_cache_entry
     {
            	/* A pointer into the canonical table of pointers  */
       struct symbol_cache_entry **sym_ptr_ptr;

            	/* offset in section */
       bfd_size_type address;

            	/* addend for relocation value */
       bfd_vma addend;

            	/* Pointer to how to perform the required relocation */
       CONST struct reloc_howto_struct *howto;

     } arelent;
   *Description*
Here is a description of each of the fields within a relent:

   * sym_ptr_ptr The symbol table pointer points to a pointer to the
symbol associated with the relocation request. This would naturally be
the pointer into the table returned by the back end's get_symtab
action. See Symbols. The symbol is referenced through a pointer to
a pointer so that tools like the linker can fix up all the symbols of
the same name by modifying only one pointer. The relocation routine
looks in the symbol and uses the base of the section the symbol is
attached to and the value of the symbol as the initial relocation
offset. If the symbol pointer is zero, then the section provided is
looked up.
   * address The address field gives the offset in bytes from the base
of the section data which owns the relocation record to the first byte
of relocatable information. The actual data relocated will be relative
to this point - for example, a relocation type which modifies the
bottom two bytes of a four byte word would not touch the first byte
pointed to in a big endian world.
   * addend The addend is a value provided by the back end to be added
(!) to the relocation offset. Its interpretation is dependent upon the
howto. For example, on the 68k the code:
             char foo[];
             main()
                     {
                     return foo[0x12345678];
                     }

   Could be compiled into:

             linkw fp,#-4
             moveb @#12345678,d0
             extbl d0
             unlk fp
             rts

   This could create a reloc pointing to foo, but leave the offset in
the data (something like)

     RELOCATION RECORDS FOR [.text]:
     offset   type      value
     00000006 32        _foo

     00000000 4e56 fffc          ; linkw fp,#-4
     00000004 1039 1234 5678     ; moveb @#12345678,d0
     0000000a 49c0               ; extbl d0
     0000000c 4e5e               ; unlk fp
     0000000e 4e75               ; rts

   Using coff and an 88k, some instructions don't have enough space in
them to represent the full address range, and pointers have to be
loaded in two parts. So you'd get something like:
             or.u     r13,r0,hi16(_foo+0x12345678)
             ld.b     r2,r13,lo16(_foo+0x12345678)
             jmp      r1
   This should create two relocs, both pointing to _foo, and with
0x12340000 in their addend field. The data would consist of:
     RELOCATION RECORDS FOR [.text]:
     offset   type      value
     00000002 HVRT16    _foo+0x12340000
     00000006 LVRT16    _foo+0x12340000

     00000000 5da05678           ; or.u r13,r0,0x5678
     00000004 1c4d5678           ; ld.b r2,r13,0x5678
     00000008 f400c001           ; jmp r1
   The relocation routine digs out the value from the data, adds it to
the addend to get the original offset and then adds the value of _foo.
Note that all 32 bits have to be kept around somewhere, to cope with
carry from bit 15 to bit 16.  One further example is the sparc and the
a.out format. The sparc has a similar problem to the 88k, in that some
instructions don't have room for an entire offset, but on the sparc the
parts are created odd sized lumps. The designers of the a.out format
chose not to use the data within the section for storing part of the
offset; all the offset is kept within the reloc. Any thing in the data
should be ignored.
             save %sp,-112,%sp
             sethi %hi(_foo+0x12345678),%g2
             ldsb [%g2+%lo(_foo+0x12345678)],%i0
             ret
             restore

   Both relocs contains a pointer to foo, and the offsets would contain
junk.
     RELOCATION RECORDS FOR [.text]:
     offset   type      value
     00000004 HI22      _foo+0x12345678
     00000008 LO10      _foo+0x12345678

     00000000 9de3bf90     ; save %sp,-112,%sp
     00000004 05000000     ; sethi %hi(_foo+0),%g2
     00000008 f048a000     ; ldsb [%g2+%lo(_foo+0)],%i0
     0000000c 81c7e008     ; ret
     00000010 81e80000     ; restore

   * 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 the other information in the reloc record and data section. A
back end would normally have a relocation instruction set and turn
relocations into pointers to the correct structure on input - but it
would be possible to create each howto field on demand.
`enum complain_overflow'
........................

Indicates what sort of overflow checking should be done when performing
a relocation.
.
     enum complain_overflow
     {
     		/* Do not complain on overflow. */
       complain_overflow_dont,

     		/* Complain if the bitfield overflows, whether it is considered
     	   as signed or unsigned. */
       complain_overflow_bitfield,

     		/* Complain if the value overflows when considered as signed
     	   number. */
       complain_overflow_signed,

     		/* Complain if the value overflows when considered as an
     	   unsigned number. */
       complain_overflow_unsigned
     };

`reloc_howto_type'
..................

   The `reloc_howto_type' is a structure which contains all the
information that BFD needs to know to tie up a back end's data.
.struct symbol_cache_entry;			/* Forward declaration */

     typedef CONST struct reloc_howto_struct
     {
            	/*  The type field has mainly a documetary use - the back end can
                to what it wants with it, though the normally the back end's
                external idea of what a reloc number would be would be stored
                in this field. For example, the a PC relative word relocation
                in a coff environment would have the type 023 - because that's
                what the outside world calls a R_PCRWORD reloc. */
       unsigned int type;

            	/*  The value the final relocation is shifted right by. This drops
                unwanted data from the relocation.  */
       unsigned int rightshift;

     		/*  The size of the item to be relocated.  This is *not* a
     	    power-of-two measure.
     		 0 : one byte
     		 1 : two bytes
     		 2 : four bytes
     		 3 : nothing done (unless special_function is nonzero)
     		 4 : eight bytes
     		-2 : two bytes, result should be subtracted from the
     		     data instead of added
     	    There is currently no trivial way to extract a "number of
     	    bytes" from a howto pointer.  */
       int size;

            	/*  The number of bits in the item to be relocated.  This is used
     	    when doing overflow checking.  */
       unsigned int bitsize;

            	/*  Notes that the relocation is relative to the location in the
                data section of the addend. The relocation function will
                subtract from the relocation value the address of the location
                being relocated. */
       boolean pc_relative;

     		/*  The bit position of the reloc value in the destination.
     	    The relocated value is left shifted by this amount. */
       unsigned int bitpos;

     		/* What type of overflow error should be checked for when
     	   relocating. */
       enum complain_overflow complain_on_overflow;

            	/* If this field is non null, then the supplied function is
               called rather than the normal function. This allows really
               strange relocation methods to be accomodated (e.g., i960 callj
               instructions). */
       bfd_reloc_status_type (*special_function)
     				    PARAMS ((bfd *abfd,
     					     arelent *reloc_entry,
                                                 struct symbol_cache_entry *symbol,
                                                 PTR data,
                                                 asection *input_section,
                                                 bfd *output_bfd));

            	/* The textual name of the relocation type. */
       char *name;

            	/* When performing a partial link, some formats must modify the
               relocations rather than the data - this flag signals this.*/
       boolean partial_inplace;

            	/* The src_mask is used to select what parts of the read in data
               are to be used in the relocation sum.  E.g., if this was an 8 bit
               bit of data which we read and relocated, this would be
               0x000000ff. When we have relocs which have an addend, such as
               sun4 extended relocs, the value in the offset part of a
               relocating field is garbage so we never use it. In this case
               the mask would be 0x00000000. */
       bfd_vma src_mask;

            	/* The dst_mask is what parts of the instruction are replaced
               into the instruction. In most cases src_mask == dst_mask,
               except in the above special case, where dst_mask would be
               0x000000ff, and src_mask would be 0x00000000.   */
       bfd_vma dst_mask;

            	/* When some formats create PC relative instructions, they leave
               the value of the pc of the place being relocated in the offset
               slot of the instruction, so that a PC relative relocation can
               be made just by adding in an ordinary offset (e.g., sun3 a.out).
               Some formats leave the displacement part of an instruction
               empty (e.g., m88k bcs), this flag signals the fact.*/
       boolean pcrel_offset;

     } reloc_howto_type;

`the HOWTO macro'
.................

   *Description*
The HOWTO define is horrible and will go away.
     #define HOWTO(C, R,S,B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
       {(unsigned)C,R,S,B, P, BI, O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}

*Description*
And will be replaced with the totally magic way. But for the moment, we
are compatible, so do it this way..
     #define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,complain_overflow_dont,FUNCTION, NAME,false,0,0,IN)

*Description*
Helper routine to turn a symbol into a relocation value.
     #define HOWTO_PREPARE(relocation, symbol)      \
       {                                            \
       if (symbol != (asymbol *)NULL) {             \
         if (bfd_is_com_section (symbol->section)) { \
           relocation = 0;                          \
         }                                          \
         else {                                     \
           relocation = symbol->value;              \
         }                                          \
       }                                            \
     }

`reloc_chain'
.............

*Description*
How relocs are tied together
     typedef unsigned char bfd_byte;

     typedef struct relent_chain {
       arelent relent;
       struct   relent_chain *next;
     } arelent_chain;

`bfd_perform_relocation'
........................

*Synopsis*
     bfd_reloc_status_type
     bfd_perform_relocation
        (bfd * abfd,
         arelent *reloc_entry,
         PTR data,
         asection *input_section,
         bfd *output_bfd);
   *Description*
If an output_bfd is supplied to this function the generated image will
be relocatable, the relocations are copied to the output file after
they have been changed to reflect the new state of the world. There are
two ways of reflecting the results of partial linkage in an output
file; by modifying the output data in place, and by modifying the
relocation record.  Some native formats (e.g., basic a.out and basic
coff) have no way of specifying an addend in the relocation type, so the
addend has to go in the output data.  This is no big deal since in
these formats the output data slot will always be big enough for the
addend. Complex reloc types with addends were invented to solve just
this problem.

The howto manager
=================

When an application wants to create a relocation, but doesn't know what
the target machine might call it, it can find out by using this bit of
code.
`bfd_reloc_code_type'
.....................

*Description*
The insides of a reloc code.  The idea is that, eventually, there will
be one enumerator for every type of relocation we ever do.  Pass one of
these values to `bfd_reloc_type_lookup', and it'll return a howto
pointer.  This does mean that the application must determine the correct
enumerator value; you can't get a howto pointer from a random set of
attributes.
.
     typedef enum bfd_reloc_code_real
     {
       	/* Basic absolute relocations */
       BFD_RELOC_64,
       BFD_RELOC_32,
       BFD_RELOC_16,
       BFD_RELOC_8,

       	/* PC-relative relocations */
       BFD_RELOC_64_PCREL,
       BFD_RELOC_32_PCREL,
       BFD_RELOC_24_PCREL,    	/* used by i960 */
       BFD_RELOC_16_PCREL,
       BFD_RELOC_8_PCREL,

       	/* Linkage-table relative */
       BFD_RELOC_32_BASEREL,
       BFD_RELOC_16_BASEREL,
       BFD_RELOC_8_BASEREL,

       	/* The type of reloc used to build a contructor table - at the moment
          probably a 32 bit wide abs address, but the cpu can choose. */
       BFD_RELOC_CTOR,

       	/* 8 bits wide, but used to form an address like 0xffnn */
       BFD_RELOC_8_FFnn,

       	/* 32-bit pc-relative, shifted right 2 bits (i.e., 30-bit
          word displacement, e.g. for SPARC) */
       BFD_RELOC_32_PCREL_S2,

       	/* High 22 bits of 32-bit value, placed into lower 22 bits of
          target word; simple reloc.  */
       BFD_RELOC_HI22,
       	/* Low 10 bits.  */
       BFD_RELOC_LO10,

       	/* Reloc types used for i960/b.out.  */
       BFD_RELOC_I960_CALLJ,

       	/* now for the sparc/elf codes */
       BFD_RELOC_NONE,			/* actually used */
       BFD_RELOC_SPARC_WDISP22,
       BFD_RELOC_SPARC22,
       BFD_RELOC_SPARC13,
       BFD_RELOC_SPARC_GOT10,
       BFD_RELOC_SPARC_GOT13,
       BFD_RELOC_SPARC_GOT22,
       BFD_RELOC_SPARC_PC10,
       BFD_RELOC_SPARC_PC22,
       BFD_RELOC_SPARC_WPLT30,
       BFD_RELOC_SPARC_COPY,
       BFD_RELOC_SPARC_GLOB_DAT,
       BFD_RELOC_SPARC_JMP_SLOT,
       BFD_RELOC_SPARC_RELATIVE,
       BFD_RELOC_SPARC_UA32,

       	/* these are a.out specific? */
       BFD_RELOC_SPARC_BASE13,
       BFD_RELOC_SPARC_BASE22,

       	/* Bits 27..2 of the relocation address shifted right 2 bits;
          simple reloc otherwise.  */
       BFD_RELOC_MIPS_JMP,

       	/* signed 16-bit pc-relative, shifted right 2 bits (e.g. for MIPS) */
       BFD_RELOC_16_PCREL_S2,

       	/* High 16 bits of 32-bit value; simple reloc.  */
       BFD_RELOC_HI16,
       	/* High 16 bits of 32-bit value but the low 16 bits will be sign
          extended and added to form the final result.  If the low 16
          bits form a negative number, we need to add one to the high value
          to compensate for the borrow when the low bits are added.  */
       BFD_RELOC_HI16_S,
       	/* Low 16 bits.  */
       BFD_RELOC_LO16,

       	/* 16 bit relocation relative to the global pointer.  */
       BFD_RELOC_MIPS_GPREL,

       	/* These are, so far, specific to HPPA processors.  I'm not sure that some
          don't duplicate other reloc types, such as BFD_RELOC_32 and _32_PCREL.
          Also, many more were in the list I got that don't fit in well in the
          model BFD uses, so I've omitted them for now.  If we do make this reloc
          type get used for code that really does implement the funky reloc types,
          they'll have to be added to this list.  */
       BFD_RELOC_HPPA_32,
       BFD_RELOC_HPPA_11,
       BFD_RELOC_HPPA_14,
       BFD_RELOC_HPPA_17,

       BFD_RELOC_HPPA_L21,
       BFD_RELOC_HPPA_R11,
       BFD_RELOC_HPPA_R14,
       BFD_RELOC_HPPA_R17,
       BFD_RELOC_HPPA_LS21,
       BFD_RELOC_HPPA_RS11,
       BFD_RELOC_HPPA_RS14,
       BFD_RELOC_HPPA_RS17,
       BFD_RELOC_HPPA_LD21,
       BFD_RELOC_HPPA_RD11,
       BFD_RELOC_HPPA_RD14,
       BFD_RELOC_HPPA_RD17,
       BFD_RELOC_HPPA_LR21,
       BFD_RELOC_HPPA_RR14,
       BFD_RELOC_HPPA_RR17,

       BFD_RELOC_HPPA_GOTOFF_11,
       BFD_RELOC_HPPA_GOTOFF_14,
       BFD_RELOC_HPPA_GOTOFF_L21,
       BFD_RELOC_HPPA_GOTOFF_R11,
       BFD_RELOC_HPPA_GOTOFF_R14,
       BFD_RELOC_HPPA_GOTOFF_LS21,
       BFD_RELOC_HPPA_GOTOFF_RS11,
       BFD_RELOC_HPPA_GOTOFF_RS14,
       BFD_RELOC_HPPA_GOTOFF_LD21,
       BFD_RELOC_HPPA_GOTOFF_RD11,
       BFD_RELOC_HPPA_GOTOFF_RD14,
       BFD_RELOC_HPPA_GOTOFF_LR21,
       BFD_RELOC_HPPA_GOTOFF_RR14,

       BFD_RELOC_HPPA_DLT_32,
       BFD_RELOC_HPPA_DLT_11,
       BFD_RELOC_HPPA_DLT_14,
       BFD_RELOC_HPPA_DLT_L21,
       BFD_RELOC_HPPA_DLT_R11,
       BFD_RELOC_HPPA_DLT_R14,

       BFD_RELOC_HPPA_ABS_CALL_11,
       BFD_RELOC_HPPA_ABS_CALL_14,
       BFD_RELOC_HPPA_ABS_CALL_17,
       BFD_RELOC_HPPA_ABS_CALL_L21,
       BFD_RELOC_HPPA_ABS_CALL_R11,
       BFD_RELOC_HPPA_ABS_CALL_R14,
       BFD_RELOC_HPPA_ABS_CALL_R17,
       BFD_RELOC_HPPA_ABS_CALL_LS21,
       BFD_RELOC_HPPA_ABS_CALL_RS11,
       BFD_RELOC_HPPA_ABS_CALL_RS14,
       BFD_RELOC_HPPA_ABS_CALL_RS17,
       BFD_RELOC_HPPA_ABS_CALL_LD21,
       BFD_RELOC_HPPA_ABS_CALL_RD11,
       BFD_RELOC_HPPA_ABS_CALL_RD14,
       BFD_RELOC_HPPA_ABS_CALL_RD17,
       BFD_RELOC_HPPA_ABS_CALL_LR21,
       BFD_RELOC_HPPA_ABS_CALL_RR14,
       BFD_RELOC_HPPA_ABS_CALL_RR17,

       BFD_RELOC_HPPA_PCREL_CALL_11,
       BFD_RELOC_HPPA_PCREL_CALL_12,
       BFD_RELOC_HPPA_PCREL_CALL_14,
       BFD_RELOC_HPPA_PCREL_CALL_17,
       BFD_RELOC_HPPA_PCREL_CALL_L21,
       BFD_RELOC_HPPA_PCREL_CALL_R11,
       BFD_RELOC_HPPA_PCREL_CALL_R14,
       BFD_RELOC_HPPA_PCREL_CALL_R17,
       BFD_RELOC_HPPA_PCREL_CALL_LS21,
       BFD_RELOC_HPPA_PCREL_CALL_RS11,
       BFD_RELOC_HPPA_PCREL_CALL_RS14,
       BFD_RELOC_HPPA_PCREL_CALL_RS17,
       BFD_RELOC_HPPA_PCREL_CALL_LD21,
       BFD_RELOC_HPPA_PCREL_CALL_RD11,
       BFD_RELOC_HPPA_PCREL_CALL_RD14,
       BFD_RELOC_HPPA_PCREL_CALL_RD17,
       BFD_RELOC_HPPA_PCREL_CALL_LR21,
       BFD_RELOC_HPPA_PCREL_CALL_RR14,
       BFD_RELOC_HPPA_PCREL_CALL_RR17,

       BFD_RELOC_HPPA_PLABEL_32,
       BFD_RELOC_HPPA_PLABEL_11,
       BFD_RELOC_HPPA_PLABEL_14,
       BFD_RELOC_HPPA_PLABEL_L21,
       BFD_RELOC_HPPA_PLABEL_R11,
       BFD_RELOC_HPPA_PLABEL_R14,

       BFD_RELOC_HPPA_UNWIND_ENTRY,
       BFD_RELOC_HPPA_UNWIND_ENTRIES,

       	/* i386/elf relocations */
       BFD_RELOC_386_GOT32,
       BFD_RELOC_386_PLT32,
       BFD_RELOC_386_COPY,
       BFD_RELOC_386_GLOB_DAT,
       BFD_RELOC_386_JUMP_SLOT,
       BFD_RELOC_386_RELATIVE,
       BFD_RELOC_386_GOTOFF,
       BFD_RELOC_386_GOTPC,

       	/* this must be the highest numeric value */
       BFD_RELOC_UNUSED
      } bfd_reloc_code_real_type;

bfd_reloc_type_lookup
=====================

*Synopsis*
     CONST struct reloc_howto_struct *
     bfd_reloc_type_lookup (bfd *abfd, bfd_reloc_code_real_type code);
   *Description*
This routine returns a pointer to a howto struct which when invoked,
will perform the supplied relocation on data from the architecture
noted.
`bfd_default_reloc_type_lookup'
...............................

*Synopsis*
     CONST struct reloc_howto_struct *bfd_default_reloc_type_lookup
        (bfd *abfd AND
         bfd_reloc_code_real_type  code);
   *Description*
Provides a default relocation lookup routine for any architecture.
`bfd_generic_relax_section'
...........................

*Synopsis*
     boolean bfd_generic_relax_section
        (bfd *abfd,
         asection *section,
         asymbol **symbols);
   *Description*
Provides default handling for relaxing for back ends which don't do
relaxing - i.e., does nothing.
`bfd_generic_get_relocated_section_contents'
............................................

*Synopsis*
     bfd_byte *
     bfd_generic_get_relocated_section_contents (bfd *abfd,
         struct bfd_seclet *seclet,
         bfd_byte *data,
         boolean relocateable);
   *Description*
Provides default handling of relocation effort for back ends which
can't be bothered to do it efficiently.

Core files
==========

*Description*
Buff output this facinating topic
`bfd_core_file_failing_command'
...............................

*Synopsis*
     CONST char *bfd_core_file_failing_command(bfd *);
   *Description*
Returns a read-only string explaining what program was running when it
failed and produced the core file being read
`bfd_core_file_failing_signal'
..............................

*Synopsis*
     int bfd_core_file_failing_signal(bfd *);
   *Description*
Returns the signal number which caused the core dump which generated
the file the BFD is attached to.
`core_file_matches_executable_p'
................................

*Synopsis*
     boolean core_file_matches_executable_p
        (bfd *core_bfd, bfd *exec_bfd);
   *Description*
Returns `true' if the core file attached to CORE_BFD was generated by a
run of the executable file attached to EXEC_BFD, or else `false'.

Targets
=======

*Description*
Each port of BFD to a different machine requries the creation of a
target back end. All the back end provides to the root part of BFD is a
structure containing pointers to functions which perform certain low
level operations on files. BFD translates the applications's requests
through a pointer into calls to the back end routines.  When a file is
opened with `bfd_openr', its format and target are unknown. BFD uses
various mechanisms to determine how to interpret the file. The
operations performed are:
   * First a BFD is created by calling the internal routine `new_bfd',
     then `bfd_find_target' is called with the target string supplied
     to `bfd_openr' and the new BFD pointer.

   * If a null target string was provided to `bfd_find_target', it
     looks up the environment variable `GNUTARGET' and uses that as the
     target string.

   * If the target string is still NULL, or the target string is
     `default', then the first item in the target vector is used as the
     target type, and `target_defaulted' is set to cause
     `bfd_check_format' to loop through all the targets.  See
     bfd_target.  See Formats.

   * Otherwise, the elements in the target vector are inspected one by
     one, until a match on target name is found. When found, that is
     used.

   * Otherwise the error `invalid_target' is returned to `bfd_openr'.

   * `bfd_openr' attempts to open the file using `bfd_open_file', and
     returns the BFD.  Once the BFD has been opened and the target
selected, the file format may be determined. This is done by calling
`bfd_check_format' on the BFD with a suggested format.  If
`target_defaulted' has been set, each possible target type is tried to
see if it recognizes the specified format.  The routine returns `true'
when the application guesses right.

bfd_target
----------

*Description*
This structure contains everything that BFD knows about a target. It
includes things like its byte order, name, what routines to call to do
various operations, etc.  Every BFD points to a target structure with
its `xvec' member.  These macros are used to dispatch to functions
through the bfd_target vector. They are used in a number of macros
further down in `bfd.h', and are also used when calling various
routines by hand inside the BFD implementation.  The "arglist" argument
must be parenthesized; it contains all the arguments to the called
function.  They make the documentation (more) unpleasant to read, so if
someone wants to fix this and not break the above, please do.
     #define BFD_SEND(bfd, message, arglist) \
                    ((*((bfd)->xvec->message)) arglist)
   For operations which index on the BFD format
     #define BFD_SEND_FMT(bfd, message, arglist) \
                 (((bfd)->xvec->message[(int)((bfd)->format)]) arglist)
   This is the struct which defines the type of BFD this is.  The
`xvec' member of the struct `bfd' itself points here.  Each module that
implements access to a different target under BFD, defines one of these.
FIXME, these names should be rationalised with the names of the entry
points which call them. Too bad we can't have one macro to define them
both!
     typedef struct bfd_target
     {
   Identifies the kind of target, eg SunOS4, Ultrix, etc.
       char *name;
   The "flavour" of a back end is a general indication about the
contents of a file.
       enum target_flavour {
         bfd_target_unknown_flavour,
         bfd_target_aout_flavour,
         bfd_target_coff_flavour,
         bfd_target_ecoff_flavour,
         bfd_target_elf_flavour,
         bfd_target_ieee_flavour,
         bfd_target_nlm_flavour,
         bfd_target_oasys_flavour,
         bfd_target_tekhex_flavour,
         bfd_target_srec_flavour,
         bfd_target_hppa_flavour} flavour;
   The order of bytes within the data area of a file.
       boolean byteorder_big_p;
   The order of bytes within the header parts of a file.
       boolean header_byteorder_big_p;
   This is a mask of all the flags which an executable may have set -
from the set `NO_FLAGS', `HAS_RELOC', ...`D_PAGED'.
       flagword object_flags;
   This is a mask of all the flags which a section may have set - from
the set `SEC_NO_FLAGS', `SEC_ALLOC', ...`SET_NEVER_LOAD'.
       flagword section_flags;
   The character normally found at the front of a symbol (if any),
perhaps _.
       char symbol_leading_char;
   The pad character for filenames within an archive header.
       char ar_pad_char;
   The maximum number of characters in an archive header.
       unsigned short ar_max_namelen;
   The minimum alignment restriction for any section.
       unsigned int align_power_min;
   Entries for byte swapping for data. These are different to the other
entry points, since they don't take BFD as first arg.  Certain other
handlers could do the same.
       bfd_vma      (*bfd_getx64) PARAMS ((bfd_byte *));
       bfd_signed_vma (*bfd_getx_signed_64) PARAMS ((bfd_byte *));
       void         (*bfd_putx64) PARAMS ((bfd_vma, bfd_byte *));
       bfd_vma      (*bfd_getx32) PARAMS ((bfd_byte *));
       bfd_signed_vma (*bfd_getx_signed_32) PARAMS ((bfd_byte *));
       void         (*bfd_putx32) PARAMS ((bfd_vma, bfd_byte *));
       bfd_vma      (*bfd_getx16) PARAMS ((bfd_byte *));
       bfd_signed_vma (*bfd_getx_signed_16) PARAMS ((bfd_byte *));
       void         (*bfd_putx16) PARAMS ((bfd_vma, bfd_byte *));
   Byte swapping for the headers
       bfd_vma      (*bfd_h_getx64) PARAMS ((bfd_byte *));
       bfd_signed_vma (*bfd_h_getx_signed_64) PARAMS ((bfd_byte *));
       void         (*bfd_h_putx64) PARAMS ((bfd_vma, bfd_byte *));
       bfd_vma      (*bfd_h_getx32) PARAMS ((bfd_byte *));
       bfd_signed_vma (*bfd_h_getx_signed_32) PARAMS ((bfd_byte *));
       void         (*bfd_h_putx32) PARAMS ((bfd_vma, bfd_byte *));
       bfd_vma      (*bfd_h_getx16) PARAMS ((bfd_byte *));
       bfd_signed_vma (*bfd_h_getx_signed_16) PARAMS ((bfd_byte *));
       void         (*bfd_h_putx16) PARAMS ((bfd_vma, bfd_byte *));
   Format dependent routines: these are vectors of entry points within
the target vector structure, one for each format to check.  Check the
format of a file being read.  Return bfd_target * or zero.
       struct bfd_target * (*_bfd_check_format[bfd_type_end]) PARAMS ((bfd *));
   Set the format of a file being written.
       boolean             (*_bfd_set_format[bfd_type_end]) PARAMS ((bfd *));
   Write cached information into a file being written, at bfd_close.
       boolean             (*_bfd_write_contents[bfd_type_end]) PARAMS ((bfd *));
   The following functions are defined in `JUMP_TABLE'. The idea is
that the back end writer of `foo' names all the routines
`foo_'ENTRY_POINT, `JUMP_TABLE' will built the entries in this
structure in the right order.  Core file entry points
       char *   (*_core_file_failing_command) PARAMS ((bfd *));
       int      (*_core_file_failing_signal) PARAMS ((bfd *));
       boolean  (*_core_file_matches_executable_p) PARAMS ((bfd *, bfd *));
   Archive entry points
       boolean  (*_bfd_slurp_armap) PARAMS ((bfd *));
       boolean  (*_bfd_slurp_extended_name_table) PARAMS ((bfd *));
       void     (*_bfd_truncate_arname) PARAMS ((bfd *, CONST char *, char *));
       boolean  (*write_armap) PARAMS ((bfd *arch,
                                   unsigned int elength,
                                   struct orl *map,
                                   unsigned int orl_count,
                                   int stridx));
   Standard stuff.
       boolean       (*_close_and_cleanup) PARAMS ((bfd *));
       boolean       (*_bfd_set_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
                                                 file_ptr, bfd_size_type));
       boolean       (*_bfd_get_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
                                                 file_ptr, bfd_size_type));
       boolean       (*_new_section_hook) PARAMS ((bfd *, sec_ptr));
   Symbols and relocations
       unsigned int  (*_get_symtab_upper_bound) PARAMS ((bfd *));
       unsigned int  (*_bfd_canonicalize_symtab) PARAMS ((bfd *,
                                                   struct symbol_cache_entry **));
       unsigned int  (*_get_reloc_upper_bound) PARAMS ((bfd *, sec_ptr));
       unsigned int  (*_bfd_canonicalize_reloc) PARAMS ((bfd *, sec_ptr, arelent **,
                                                   struct symbol_cache_entry **));
       struct symbol_cache_entry  *
                     (*_bfd_make_empty_symbol) PARAMS ((bfd *));
       void          (*_bfd_print_symbol) PARAMS ((bfd *, PTR,
                                           struct symbol_cache_entry *,
                                           bfd_print_symbol_type));
     #define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
       void          (*_bfd_get_symbol_info) PARAMS ((bfd *,
                                           struct symbol_cache_entry *,
                                           symbol_info *));
     #define bfd_get_symbol_info(b,p,e) BFD_SEND(b, _bfd_get_symbol_info, (b,p,e))
       alent *    (*_get_lineno) PARAMS ((bfd *, struct symbol_cache_entry *));

       boolean    (*_bfd_set_arch_mach) PARAMS ((bfd *, enum bfd_architecture,
                         unsigned long));

       bfd *      (*openr_next_archived_file) PARAMS ((bfd *arch, bfd *prev));

       boolean    (*_bfd_find_nearest_line) PARAMS ((bfd *abfd,
                         struct sec *section, struct symbol_cache_entry **symbols,
                         bfd_vma offset, CONST char **file, CONST char **func,
                         unsigned int *line));

       int        (*_bfd_stat_arch_elt) PARAMS ((bfd *, struct stat *));

       int        (*_bfd_sizeof_headers) PARAMS ((bfd *, boolean));

       void       (*_bfd_debug_info_start) PARAMS ((bfd *));
       void       (*_bfd_debug_info_end) PARAMS ((bfd *));
       void       (*_bfd_debug_info_accumulate) PARAMS ((bfd *, struct sec *));

       bfd_byte * (*_bfd_get_relocated_section_contents) PARAMS ((bfd *,
                         struct bfd_seclet *, bfd_byte *data,
                         boolean relocateable));

       boolean    (*_bfd_relax_section) PARAMS ((bfd *, struct sec *,
                         struct symbol_cache_entry **));

       boolean    (*_bfd_seclet_link) PARAMS ((bfd *, PTR data,
                          boolean relocateable));
       /* See documentation on reloc types.  */
      CONST struct reloc_howto_struct *
            (*reloc_type_lookup) PARAMS ((bfd *abfd,
                                          bfd_reloc_code_real_type code));

       /* Back-door to allow format-aware applications to create debug symbols
         while using BFD for everything else.  Currently used by the assembler
         when creating COFF files.  */
      asymbol *  (*_bfd_make_debug_symbol) PARAMS ((
            bfd *abfd,
            void *ptr,
            unsigned long size));
   Data for use by back-end routines, which isn't generic enough to
belong in this structure.
      PTR backend_data;
     } bfd_target;

`bfd_find_target'
.................

*Description*
Returns a pointer to the transfer vector for the object target named
target_name.  If target_name is NULL, chooses the one in the
environment variable GNUTARGET; if that is null or not defined thenthe
first entry in the target list is chosen.  Passing in the string
"default" or setting the environment variable to "default" will cause
the first entry in the target list to be returned, and
"target_defaulted" will be set in the BFD.  This causes
`bfd_check_format' to loop over all the targets to find the one that
matches the file being read.
*Synopsis*
     bfd_target *bfd_find_target(CONST char *, bfd *);

`bfd_target_list'
.................

   *Description*
This function returns a freshly malloced NULL-terminated vector of the
names of all the valid BFD targets. Do not modify the names
*Synopsis*
     CONST char **bfd_target_list(void);