   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.

Adding symbols from an archive
..............................

   When the `_bfd_link_add_symbols' routine is passed an archive, it
must look through the symbols defined by the archive and decide which
elements of the archive should be included in the link.  For each such
element it must call the `add_archive_element' linker callback, and it
must add the symbols from the object file to the linker hash table.

   In most cases the work of looking through the symbols in the archive
should be done by the `_bfd_generic_link_add_archive_symbols' function.
This function builds a hash table from the archive symbol table and
looks through the list of undefined symbols to see which elements
should be included.  `_bfd_generic_link_add_archive_symbols' is passed
a function to call to make the final decision about adding an archive
element to the link and to do the actual work of adding the symbols to
the linker hash table.

   The function passed to `_bfd_generic_link_add_archive_symbols' must
read the symbols of the archive element and decide whether the archive
element should be included in the link.  If the element is to be
included, the `add_archive_element' linker callback routine must be
called with the element as an argument, and the elements symbols must
be added to the linker hash table just as though the element had itself
been passed to the `_bfd_link_add_symbols' function.

   When the a.out `_bfd_link_add_symbols' function receives an archive,
it calls `_bfd_generic_link_add_archive_symbols' passing
`aout_link_check_archive_element' as the function argument.
`aout_link_check_archive_element' calls `aout_link_check_ar_symbols'.
If the latter decides to add the element (an element is only added if
it provides a real, non-common, definition for a previously undefined
or common symbol) it calls the `add_archive_element' callback and then
`aout_link_check_archive_element' calls `aout_link_add_symbols' to
actually add the symbols to the linker hash table.

   The ECOFF back end is unusual in that it does not normally call
`_bfd_generic_link_add_archive_symbols', because ECOFF archives already
contain a hash table of symbols.  The ECOFF back end searches the
archive itself to avoid the overhead of creating a new hash table.

Performing the final link
-------------------------

   When all the input files have been processed, the linker calls the
`_bfd_final_link' entry point of the output BFD.  This routine is
responsible for producing the final output file, which has several
aspects.  It must relocate the contents of the input sections and copy
the data into the output sections.  It must build an output symbol
table including any local symbols from the input files and the global
symbols from the hash table.  When producing relocateable output, it
must modify the input relocs and write them into the output file.
There may also be object format dependent work to be done.

   The linker will also call the `write_object_contents' entry point
when the BFD is closed.  The two entry points must work together in
order to produce the correct output file.

   The details of how this works are inevitably dependent upon the
specific object file format.  The a.out `_bfd_final_link' routine is
`NAME(aout,final_link)'.

Information provided by the linker
..................................

   Before the linker calls the `_bfd_final_link' entry point, it sets
up some data structures for the function to use.

   The `input_bfds' field of the `bfd_link_info' structure will point
to a list of all the input files included in the link.  These files are
linked through the `link_next' field of the `bfd' structure.

   Each section in the output file will have a list of `link_order'
structures attached to the `link_order_head' field (the `link_order'
structure is defined in `bfdlink.h').  These structures describe how to
create the contents of the output section in terms of the contents of
various input sections, fill constants, and, eventually, other types of
information.  They also describe relocs that must be created by the BFD
backend, but do not correspond to any input file; this is used to
support -Ur, which builds constructors while generating a relocateable
object file.

Relocating the section contents
...............................

   The `_bfd_final_link' function should look through the `link_order'
structures attached to each section of the output file.  Each
`link_order' structure should either be handled specially, or it should
be passed to the function `_bfd_default_link_order' which will do the
right thing (`_bfd_default_link_order' is defined in `linker.c').

   For efficiency, a `link_order' of type `bfd_indirect_link_order'
whose associated section belongs to a BFD of the same format as the
output BFD must be handled specially.  This type of `link_order'
describes part of an output section in terms of a section belonging to
one of the input files.  The `_bfd_final_link' function should read the
contents of the section and any associated relocs, apply the relocs to
the section contents, and write out the modified section contents.  If
performing a relocateable link, the relocs themselves must also be
modified and written out.

   The functions `_bfd_relocate_contents' and
`_bfd_final_link_relocate' provide some general support for performing
the actual relocations, notably overflow checking.  Their arguments
include information about the symbol the relocation is against and a
`reloc_howto_type' argument which describes the relocation to perform.
These functions are defined in `reloc.c'.

   The a.out function which handles reading, relocating, and writing
section contents is `aout_link_input_section'.  The actual relocation
is done in `aout_link_input_section_std' and
`aout_link_input_section_ext'.

Writing the symbol table
........................

   The `_bfd_final_link' function must gather all the symbols in the
input files and write them out.  It must also write out all the symbols
in the global hash table.  This must be controlled by the `strip' and
`discard' fields of the `bfd_link_info' structure.

   The local symbols of the input files will not have been entered into
the linker hash table.  The `_bfd_final_link' routine must consider
each input file and include the symbols in the output file.  It may be
convenient to do this when looking through the `link_order' structures,
or it may be done by stepping through the `input_bfds' list.

   The `_bfd_final_link' routine must also traverse the global hash
table to gather all the externally visible symbols.  It is possible
that most of the externally visible symbols may be written out when
considering the symbols of each input file, but it is still necessary
to traverse the hash table since the linker script may have defined
some symbols that are not in any of the input files.

   The `strip' field of the `bfd_link_info' structure controls which
symbols are written out.  The possible values are listed in
`bfdlink.h'.  If the value is `strip_some', then the `keep_hash' field
of the `bfd_link_info' structure is a hash table of symbols to keep;
each symbol should be looked up in this hash table, and only symbols
which are present should be included in the output file.

   If the `strip' field of the `bfd_link_info' structure permits local
symbols to be written out, the `discard' field is used to further
controls which local symbols are included in the output file.  If the
value is `discard_l', then all local symbols which begin with a certain
prefix are discarded; this is controlled by the
`bfd_is_local_label_name' entry point.

   The a.out backend handles symbols by calling
`aout_link_write_symbols' on each input BFD and then traversing the
global hash table with the function `aout_link_write_other_symbol'.  It
builds a string table while writing out the symbols, which is written
to the output file at the end of `NAME(aout,final_link)'.

`bfd_link_split_section'
........................

   *Synopsis*
     boolean bfd_link_split_section(bfd *abfd, asection *sec);
   *Description*
Return nonzero if SEC should be split during a reloceatable or final
link.
     #define bfd_link_split_section(abfd, sec) \
            BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))

Hash Tables
===========

   BFD provides a simple set of hash table functions.  Routines are
provided to initialize a hash table, to free a hash table, to look up a
string in a hash table and optionally create an entry for it, and to
traverse a hash table.  There is currently no routine to delete an
string from a hash table.

   The basic hash table does not permit any data to be stored with a
string.  However, a hash table is designed to present a base class from
which other types of hash tables may be derived.  These derived types
may store additional information with the string.  Hash tables were
implemented in this way, rather than simply providing a data pointer in
a hash table entry, because they were designed for use by the linker
back ends.  The linker may create thousands of hash table entries, and
the overhead of allocating private data and storing and following
pointers becomes noticeable.

   The basic hash table code is in `hash.c'.

Creating and freeing a hash table
---------------------------------

   To create a hash table, create an instance of a `struct
bfd_hash_table' (defined in `bfd.h') and call `bfd_hash_table_init' (if
you know approximately how many entries you will need, the function
`bfd_hash_table_init_n', which takes a SIZE argument, may be used).
`bfd_hash_table_init' returns `false' if some sort of error occurs.

   The function `bfd_hash_table_init' take as an argument a function to
use to create new entries.  For a basic hash table, use the function
`bfd_hash_newfunc'.  See Deriving a New Hash Table Type for why you
would want to use a different value for this argument.

   `bfd_hash_table_init' will create an objalloc which will be used to
allocate new entries.  You may allocate memory on this objalloc using
`bfd_hash_allocate'.

   Use `bfd_hash_table_free' to free up all the memory that has been
allocated for a hash table.  This will not free up the `struct
bfd_hash_table' itself, which you must provide.

Looking up or entering a string
-------------------------------

   The function `bfd_hash_lookup' is used both to look up a string in
the hash table and to create a new entry.

   If the CREATE argument is `false', `bfd_hash_lookup' will look up a
string.  If the string is found, it will returns a pointer to a `struct
bfd_hash_entry'.  If the string is not found in the table
`bfd_hash_lookup' will return `NULL'.  You should not modify any of the
fields in the returns `struct bfd_hash_entry'.

   If the CREATE argument is `true', the string will be entered into
the hash table if it is not already there.  Either way a pointer to a
`struct bfd_hash_entry' will be returned, either to the existing
structure or to a newly created one.  In this case, a `NULL' return
means that an error occurred.

   If the CREATE argument is `true', and a new entry is created, the
COPY argument is used to decide whether to copy the string onto the
hash table objalloc or not.  If COPY is passed as `false', you must be
careful not to deallocate or modify the string as long as the hash table
exists.

Traversing a hash table
-----------------------

   The function `bfd_hash_traverse' may be used to traverse a hash
table, calling a function on each element.  The traversal is done in a
random order.

   `bfd_hash_traverse' takes as arguments a function and a generic
`void *' pointer.  The function is called with a hash table entry (a
`struct bfd_hash_entry *') and the generic pointer passed to
`bfd_hash_traverse'.  The function must return a `boolean' value, which
indicates whether to continue traversing the hash table.  If the
function returns `false', `bfd_hash_traverse' will stop the traversal
and return immediately.

Deriving a new hash table type
------------------------------

   Many uses of hash tables want to store additional information which
each entry in the hash table.  Some also find it convenient to store
additional information with the hash table itself.  This may be done
using a derived hash table.

   Since C is not an object oriented language, creating a derived hash
table requires sticking together some boilerplate routines with a few
differences specific to the type of hash table you want to create.

   An example of a derived hash table is the linker hash table.  The
structures for this are defined in `bfdlink.h'.  The functions are in
`linker.c'.

   You may also derive a hash table from an already derived hash table.
For example, the a.out linker backend code uses a hash table derived
from the linker hash table.

Define the derived structures
.............................

   You must define a structure for an entry in the hash table, and a
structure for the hash table itself.

   The first field in the structure for an entry in the hash table must
be of the type used for an entry in the hash table you are deriving
from.  If you are deriving from a basic hash table this is `struct
bfd_hash_entry', which is defined in `bfd.h'.  The first field in the
structure for the hash table itself must be of the type of the hash
table you are deriving from itself.  If you are deriving from a basic
hash table, this is `struct bfd_hash_table'.

   For example, the linker hash table defines `struct
bfd_link_hash_entry' (in `bfdlink.h').  The first field, `root', is of
type `struct bfd_hash_entry'.  Similarly, the first field in `struct
bfd_link_hash_table', `table', is of type `struct bfd_hash_table'.

Write the derived creation routine
..................................

   You must write a routine which will create and initialize an entry
in the hash table.  This routine is passed as the function argument to
`bfd_hash_table_init'.

   In order to permit other hash tables to be derived from the hash
table you are creating, this routine must be written in a standard way.

   The first argument to the creation routine is a pointer to a hash
table entry.  This may be `NULL', in which case the routine should
allocate the right amount of space.  Otherwise the space has already
been allocated by a hash table type derived from this one.

   After allocating space, the creation routine must call the creation
routine of the hash table type it is derived from, passing in a pointer
to the space it just allocated.  This will initialize any fields used
by the base hash table.

   Finally the creation routine must initialize any local fields for
the new hash table type.

   Here is a boilerplate example of a creation routine.  FUNCTION_NAME
is the name of the routine.  ENTRY_TYPE is the type of an entry in the
hash table you are creating.  BASE_NEWFUNC is the name of the creation
routine of the hash table type your hash table is derived from.

     struct bfd_hash_entry *
     FUNCTION_NAME (entry, table, string)
          struct bfd_hash_entry *entry;
          struct bfd_hash_table *table;
          const char *string;
     {
       struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry;

      /* Allocate the structure if it has not already been allocated by a
         derived class.  */
       if (ret == (ENTRY_TYPE *) NULL)
         {
           ret = ((ENTRY_TYPE *)
                  bfd_hash_allocate (table, sizeof (ENTRY_TYPE)));
           if (ret == (ENTRY_TYPE *) NULL)
             return NULL;
         }

      /* Call the allocation method of the base class.  */
       ret = ((ENTRY_TYPE *)
             BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string));

      /* Initialize the local fields here.  */

       return (struct bfd_hash_entry *) ret;
     }
   *Description*
The creation routine for the linker hash table, which is in `linker.c',
looks just like this example.  FUNCTION_NAME is
`_bfd_link_hash_newfunc'.  ENTRY_TYPE is `struct bfd_link_hash_entry'.
BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic
hash table.

   `_bfd_link_hash_newfunc' also initializes the local fields in a
linker hash table entry: `type', `written' and `next'.

Write other derived routines
............................

   You will want to write other routines for your new hash table, as
well.

   You will want an initialization routine which calls the
initialization routine of the hash table you are deriving from and
initializes any other local fields.  For the linker hash table, this is
`_bfd_link_hash_table_init' in `linker.c'.

   You will want a lookup routine which calls the lookup routine of the
hash table you are deriving from and casts the result.  The linker hash
table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an
additional argument which it uses to decide how to return the looked up
value).

   You may want a traversal routine.  This should just call the
traversal routine of the hash table you are deriving from with
appropriate casts.  The linker hash table uses `bfd_link_hash_traverse'
in `linker.c'.

   These routines may simply be defined as macros.  For example, the
a.out backend linker hash table, which is derived from the linker hash
table, uses macros for the lookup and traversal routines.  These are
`aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h.

BFD back ends
*************

   All of BFD lives in one directory.

a.out backends
==============

   *Description*
BFD supports a number of different flavours of a.out format, though the
major differences are only the sizes of the structures on disk, and the
shape of the relocation information.

   The support is split into a basic support file `aoutx.h' and other
files which derive functions from the base. One derivation file is
`aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions
support for sun3, sun4, 386 and 29k a.out files, to create a target
jump vector for a specific target.

   This information is further split out into more specific files for
each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for
the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out
format.

   The base file `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 `aout32.c' and `aout64.c' to form the names
`aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc.

   As an example, this is what goes on to make the back end for a sun4,
from `aout32.c':

            #define ARCH_SIZE 32
            #include "aoutx.h"

   Which exports names:

            ...
            aout_32_canonicalize_reloc
            aout_32_find_nearest_line
            aout_32_get_lineno
            aout_32_get_reloc_upper_bound
            ...

   from `sunos.c':

            #define TARGET_NAME "a.out-sunos-big"
            #define VECNAME    sunos_big_vec
            #include "aoutf1.h"

   requires all the names from `aout32.c', and produces the jump vector

            sunos_big_vec

   The file `host-aout.c' is a special case.  It is for a large set of
hosts that use "more or less standard" a.out files, and for which
cross-debugging is not interesting.  It uses the standard 32-bit a.out
support routines, but determines the file offsets and addresses of the
text, data, and BSS sections, the machine architecture and machine
type, and the entry point address, in a host-dependent manner.  Once
these values have been determined, generic code is used to handle the
object file.

   When porting it to run on a new system, you must supply:

             HOST_PAGE_SIZE
             HOST_SEGMENT_SIZE
             HOST_MACHINE_ARCH       (optional)
             HOST_MACHINE_MACHINE    (optional)
             HOST_TEXT_START_ADDR
             HOST_STACK_END_ADDR

   in the file `../include/sys/h-XXX.h' (for your host).  These values,
plus the structures and macros defined in `a.out.h' on your host
system, will produce a BFD target that will access ordinary a.out files
on your host. To configure a new machine to use `host-aout.c', specify:

            TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
            TDEPFILES= host-aout.o trad-core.o

   in the `config/XXX.mt' file, and modify `configure.in' to use the
`XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration
is selected.

Relocations
-----------

   *Description*
The file `aoutx.h' provides for both the *standard* and *extended*
forms of a.out relocation records.

   The standard records contain only an address, a symbol index, and a
type field. The extended records (used on 29ks and sparcs) also have a
full integer for an addend.

Internal entry points
---------------------

   *Description*
`aoutx.h' exports several routines for accessing the contents of an
a.out file, which are gathered and exported in turn by various format
specific files (eg sunos.c).

`aout_SIZE_swap_exec_header_in'
...............................

   *Synopsis*
     void aout_SIZE_swap_exec_header_in,
        (bfd *abfd,
         struct external_exec *raw_bytes,
         struct internal_exec *execp);
   *Description*
Swap the information in an executable header RAW_BYTES taken from a raw
byte stream memory image into the internal exec header structure EXECP.

`aout_SIZE_swap_exec_header_out'
................................

   *Synopsis*
     void aout_SIZE_swap_exec_header_out
        (bfd *abfd,
         struct internal_exec *execp,
         struct external_exec *raw_bytes);
   *Description*
Swap the information in an internal exec header structure EXECP into
the buffer RAW_BYTES ready for writing to disk.

`aout_SIZE_some_aout_object_p'
..............................

   *Synopsis*
     const bfd_target *aout_SIZE_some_aout_object_p
        (bfd *abfd,
         const bfd_target *(*callback_to_real_object_p)());
   *Description*
Some a.out variant thinks that the file open in ABFD checking is an
a.out file.  Do some more checking, and set up for access if it really
is.  Call back to the calling environment's "finish up" function just
before returning, to handle any last-minute setup.

`aout_SIZE_mkobject'
....................

   *Synopsis*
     boolean aout_SIZE_mkobject, (bfd *abfd);
   *Description*
Initialize BFD ABFD for use with a.out files.

`aout_SIZE_machine_type'
........................

   *Synopsis*
     enum machine_type  aout_SIZE_machine_type
        (enum bfd_architecture arch,
         unsigned long machine));
   *Description*
Keep track of machine architecture and machine type for a.out's. Return
the `machine_type' for a particular architecture and machine, or
`M_UNKNOWN' if that exact architecture and machine can't be represented
in a.out format.

   If the architecture is understood, machine type 0 (default) is
always understood.

`aout_SIZE_set_arch_mach'
.........................

   *Synopsis*
     boolean aout_SIZE_set_arch_mach,
        (bfd *,
         enum bfd_architecture arch,
         unsigned long machine));
   *Description*
Set the architecture and the machine of the BFD ABFD to the values ARCH
and MACHINE.  Verify that ABFD's format can support the architecture
required.

`aout_SIZE_new_section_hook'
............................

   *Synopsis*
     boolean aout_SIZE_new_section_hook,
        (bfd *abfd,
         asection *newsect));
   *Description*
Called by the BFD in response to a `bfd_make_section' request.