This is bfdint.info, produced by makeinfo version 4.0 from bfdint.texi.


File: bfdint.info,  Node: Top,  Next: BFD overview,  Up: (dir)

BFD Internals
*************

   This document describes some BFD internal information which may be
helpful when working on BFD.  It is very incomplete.

   This document is not updated regularly, and may be out of date.

   The initial version of this document was written by Ian Lance Taylor
<ian@cygnus.com>.

* Menu:

* BFD overview::		BFD overview
* BFD guidelines::		BFD programming guidelines
* BFD target vector::		BFD target vector
* BFD generated files::		BFD generated files
* BFD multiple compilations::	Files compiled multiple times in BFD
* BFD relocation handling::	BFD relocation handling
* BFD ELF support::		BFD ELF support
* BFD glossary::		Glossary
* Index::			Index


File: bfdint.info,  Node: BFD overview,  Next: BFD guidelines,  Prev: Top,  Up: Top

BFD overview
************

   BFD is a library which provides a single interface to read and write
object files, executables, archive files, and core files in any format.

* Menu:

* BFD library interfaces::	BFD library interfaces
* BFD library users::		BFD library users
* BFD view::			The BFD view of a file
* BFD blindness::		BFD loses information


File: bfdint.info,  Node: BFD library interfaces,  Next: BFD library users,  Up: BFD overview

BFD library interfaces
======================

   One way to look at the BFD library is to divide it into four parts by
type of interface.

   The first interface is the set of generic functions which programs
using the BFD library will call.  These generic function normally
translate directly or indirectly into calls to routines which are
specific to a particular object file format.  Many of these generic
functions are actually defined as macros in `bfd.h'.  These functions
comprise the official BFD interface.

   The second interface is the set of functions which appear in the
target vectors.  This is the bulk of the code in BFD.  A target vector
is a set of function pointers specific to a particular object file
format.  The target vector is used to implement the generic BFD
functions.  These functions are always called through the target
vector, and are never called directly.  The target vector is described
in detail in *Note BFD target vector::.  The set of functions which
appear in a particular target vector is often referred to as a BFD
backend.

   The third interface is a set of oddball functions which are typically
specific to a particular object file format, are not generic functions,
and are called from outside of the BFD library.  These are used as hooks
by the linker and the assembler when a particular object file format
requires some action which the BFD generic interface does not provide.
These functions are typically declared in `bfd.h', but in many cases
they are only provided when BFD is configured with support for a
particular object file format.  These functions live in a grey area, and
are not really part of the official BFD interface.

   The fourth interface is the set of BFD support functions which are
called by the other BFD functions.  These manage issues like memory
allocation, error handling, file access, hash tables, swapping, and the
like.  These functions are never called from outside of the BFD library.


File: bfdint.info,  Node: BFD library users,  Next: BFD view,  Prev: BFD library interfaces,  Up: BFD overview

BFD library users
=================

   Another way to look at the BFD library is to divide it into three
parts by the manner in which it is used.

   The first use is to read an object file.  The object file readers are
programs like `gdb', `nm', `objdump', and `objcopy'.  These programs
use BFD to view an object file in a generic form.  The official BFD
interface is normally fully adequate for these programs.

   The second use is to write an object file.  The object file writers
are programs like `gas' and `objcopy'.  These programs use BFD to
create an object file.  The official BFD interface is normally adequate
for these programs, but for some object file formats the assembler needs
some additional hooks in order to set particular flags or other
information.  The official BFD interface includes functions to copy
private information from one object file to another, and these functions
are used by `objcopy' to avoid information loss.

   The third use is to link object files.  There is only one object file
linker, `ld'.  Originally, `ld' was an object file reader and an object
file writer, and it did the link operation using the generic BFD
structures.  However, this turned out to be too slow and too memory
intensive.

   The official BFD linker functions were written to permit specific BFD
backends to perform the link without translating through the generic
structures, in the normal case where all the input files and output file
have the same object file format.  Not all of the backends currently
implement the new interface, and there are default linking functions
within BFD which use the generic structures and which work with all
backends.

   For several object file formats the linker needs additional hooks
which are not provided by the official BFD interface, particularly for
dynamic linking support.  These functions are typically called from the
linker emulation template.


File: bfdint.info,  Node: BFD view,  Next: BFD blindness,  Prev: BFD library users,  Up: BFD overview

The BFD view of a file
======================

   BFD uses generic structures to manage information.  It translates
data into the generic form when reading files, and out of the generic
form when writing files.

   BFD describes a file as a pointer to the `bfd' type.  A `bfd' is
composed of the following elements.  The BFD information can be
displayed using the `objdump' program with various options.

general information
     The object file format, a few general flags, the start address.

architecture
     The architecture, including both a general processor type (m68k,
     MIPS etc.) and a specific machine number (m68000, R4000, etc.).

sections
     A list of sections.

symbols
     A symbol table.

   BFD represents a section as a pointer to the `asection' type.  Each
section has a name and a size.  Most sections also have an associated
block of data, known as the section contents.  Sections also have
associated flags, a virtual memory address, a load memory address, a
required alignment, a list of relocations, and other miscellaneous
information.

   BFD represents a relocation as a pointer to the `arelent' type.  A
relocation describes an action which the linker must take to modify the
section contents.  Relocations have a symbol, an address, an addend, and
a pointer to a howto structure which describes how to perform the
relocation.  For more information, see *Note BFD relocation handling::.

   BFD represents a symbol as a pointer to the `asymbol' type.  A
symbol has a name, a pointer to a section, an offset within that
section, and some flags.

   Archive files do not have any sections or symbols.  Instead, BFD
represents an archive file as a file which contains a list of `bfd's.
BFD also provides access to the archive symbol map, as a list of symbol
names.  BFD provides a function to return the `bfd' within the archive
which corresponds to a particular entry in the archive symbol map.


File: bfdint.info,  Node: BFD blindness,  Prev: BFD view,  Up: BFD overview

BFD loses information
=====================

   Most object file formats have information which BFD can not
represent in its generic form, at least as currently defined.

   There is often explicit information which BFD can not represent.  For
example, the COFF version stamp, or the ELF program segments.  BFD
provides special hooks to handle this information when copying,
printing, or linking an object file.  The BFD support for a particular
object file format will normally store this information in private data
and handle it using the special hooks.

   In some cases there is also implicit information which BFD can not
represent.  For example, the MIPS processor distinguishes small and
large symbols, and requires that all small symbls be within 32K of the
GP register.  This means that the MIPS assembler must be able to mark
variables as either small or large, and the MIPS linker must know to put
small symbols within range of the GP register.  Since BFD can not
represent this information, this means that the assembler and linker
must have information that is specific to a particular object file
format which is outside of the BFD library.

   This loss of information indicates areas where the BFD paradigm
breaks down.  It is not actually possible to represent the myriad
differences among object file formats using a single generic interface,
at least not in the manner which BFD does it today.

   Nevertheless, the BFD library does greatly simplify the task of
dealing with object files, and particular problems caused by
information loss can normally be solved using some sort of relatively
constrained hook into the library.


File: bfdint.info,  Node: BFD guidelines,  Next: BFD target vector,  Prev: BFD overview,  Up: Top

BFD programming guidelines
**************************

   There is a lot of poorly written and confusing code in BFD.  New BFD
code should be written to a higher standard.  Merely because some BFD
code is written in a particular manner does not mean that you should
emulate it.

   Here are some general BFD programming guidelines:

   * Follow the GNU coding standards.

   * Avoid global variables.  We ideally want BFD to be fully
     reentrant, so that it can be used in multiple threads.  All uses
     of global or static variables interfere with that.  Initialized
     constant variables are OK, and they should be explicitly marked
     with const.  Instead of global variables, use data attached to a
     BFD or to a linker hash table.

   * All externally visible functions should have names which start with
     `bfd_'.  All such functions should be declared in some header file,
     typically `bfd.h'.  See, for example, the various declarations near
     the end of `bfd-in.h', which mostly declare functions required by
     specific linker emulations.

   * All functions which need to be visible from one file to another
     within BFD, but should not be visible outside of BFD, should start
     with `_bfd_'.  Although external names beginning with `_' are
     prohibited by the ANSI standard, in practice this usage will always
     work, and it is required by the GNU coding standards.

   * Always remember that people can compile using `--enable-targets' to
     build several, or all, targets at once.  It must be possible to
     link together the files for all targets.

   * BFD code should compile with few or no warnings using `gcc -Wall'.
     Some warnings are OK, like the absence of certain function
     declarations which may or may not be declared in system header
     files.  Warnings about ambiguous expressions and the like should
     always be fixed.


File: bfdint.info,  Node: BFD target vector,  Next: BFD generated files,  Prev: BFD guidelines,  Up: Top

BFD target vector
*****************

   BFD supports multiple object file formats by using the "target
vector".  This is simply a set of function pointers which implement
behaviour that is specific to a particular object file format.

   In this section I list all of the entries in the target vector and
describe what they do.

* Menu:

* BFD target vector miscellaneous::	Miscellaneous constants
* BFD target vector swap::		Swapping functions
* BFD target vector format::		Format type dependent functions
* BFD_JUMP_TABLE macros::		BFD_JUMP_TABLE macros
* BFD target vector generic::		Generic functions
* BFD target vector copy::		Copy functions
* BFD target vector core::		Core file support functions
* BFD target vector archive::		Archive functions
* BFD target vector symbols::		Symbol table functions
* BFD target vector relocs::		Relocation support
* BFD target vector write::		Output functions
* BFD target vector link::		Linker functions
* BFD target vector dynamic::		Dynamic linking information functions


File: bfdint.info,  Node: BFD target vector miscellaneous,  Next: BFD target vector swap,  Up: BFD target vector

Miscellaneous constants
=======================

   The target vector starts with a set of constants.

`name'
     The name of the target vector.  This is an arbitrary string.  This
     is how the target vector is named in command line options for
     tools which use BFD, such as the `--oformat' linker option.

`flavour'
     A general description of the type of target.  The following
     flavours are currently defined:

    `bfd_target_unknown_flavour'
          Undefined or unknown.

    `bfd_target_aout_flavour'
          a.out.

    `bfd_target_coff_flavour'
          COFF.

    `bfd_target_ecoff_flavour'
          ECOFF.

    `bfd_target_elf_flavour'
          ELF.

    `bfd_target_ieee_flavour'
          IEEE-695.

    `bfd_target_nlm_flavour'
          NLM.

    `bfd_target_oasys_flavour'
          OASYS.

    `bfd_target_tekhex_flavour'
          Tektronix hex format.

    `bfd_target_srec_flavour'
          Motorola S-record format.

    `bfd_target_ihex_flavour'
          Intel hex format.

    `bfd_target_som_flavour'
          SOM (used on HP/UX).

    `bfd_target_os9k_flavour'
          os9000.

    `bfd_target_versados_flavour'
          VERSAdos.

    `bfd_target_msdos_flavour'
          MS-DOS.

    `bfd_target_evax_flavour'
          openVMS.

`byteorder'
     The byte order of data in the object file.  One of
     `BFD_ENDIAN_BIG', `BFD_ENDIAN_LITTLE', or `BFD_ENDIAN_UNKNOWN'.
     The latter would be used for a format such as S-records which do
     not record the architecture of the data.

`header_byteorder'
     The byte order of header information in the object file.  Normally
     the same as the `byteorder' field, but there are certain cases
     where it may be different.

`object_flags'
     Flags which may appear in the `flags' field of a BFD with this
     format.

`section_flags'
     Flags which may appear in the `flags' field of a section within a
     BFD with this format.

`symbol_leading_char'
     A character which the C compiler normally puts before a symbol.
     For example, an a.out compiler will typically generate the symbol
     `_foo' for a function named `foo' in the C source, in which case
     this field would be `_'.  If there is no such character, this
     field will be `0'.

`ar_pad_char'
     The padding character to use at the end of an archive name.
     Normally `/'.

`ar_max_namelen'
     The maximum length of a short name in an archive.  Normally `14'.

`backend_data'
     A pointer to constant backend data.  This is used by backends to
     store whatever additional information they need to distinguish
     similar target vectors which use the same sets of functions.


File: bfdint.info,  Node: BFD target vector swap,  Next: BFD target vector format,  Prev: BFD target vector miscellaneous,  Up: BFD target vector

Swapping functions
==================

   Every target vector has function pointers used for swapping
information in and out of the target representation.  There are two
sets of functions: one for data information, and one for header
information.  Each set has three sizes: 64-bit, 32-bit, and 16-bit.
Each size has three actual functions: put, get unsigned, and get signed.

   These 18 functions are used to convert data between the host and
target representations.


File: bfdint.info,  Node: BFD target vector format,  Next: BFD_JUMP_TABLE macros,  Prev: BFD target vector swap,  Up: BFD target vector

Format type dependent functions
===============================

   Every target vector has three arrays of function pointers which are
indexed by the BFD format type.  The BFD format types are as follows:

`bfd_unknown'
     Unknown format.  Not used for anything useful.

`bfd_object'
     Object file.

`bfd_archive'
     Archive file.

`bfd_core'
     Core file.

   The three arrays of function pointers are as follows:

`bfd_check_format'
     Check whether the BFD is of a particular format (object file,
     archive file, or core file) corresponding to this target vector.
     This is called by the `bfd_check_format' function when examining
     an existing BFD.  If the BFD matches the desired format, this
     function will initialize any format specific information such as
     the `tdata' field of the BFD.  This function must be called before
     any other BFD target vector function on a file opened for reading.

`bfd_set_format'
     Set the format of a BFD which was created for output.  This is
     called by the `bfd_set_format' function after creating the BFD
     with a function such as `bfd_openw'.  This function will
     initialize format specific information required to write out an
     object file or whatever of the given format.  This function must
     be called before any other BFD target vector function on a file
     opened for writing.

`bfd_write_contents'
     Write out the contents of the BFD in the given format.  This is
     called by `bfd_close' function for a BFD opened for writing.  This
     really should not be an array selected by format type, as the
     `bfd_set_format' function provides all the required information.
     In fact, BFD will fail if a different format is used when calling
     through the `bfd_set_format' and the `bfd_write_contents' arrays;
     fortunately, since `bfd_close' gets it right, this is a difficult
     error to make.


File: bfdint.info,  Node: BFD_JUMP_TABLE macros,  Next: BFD target vector generic,  Prev: BFD target vector format,  Up: BFD target vector

`BFD_JUMP_TABLE' macros
=======================

   Most target vectors are defined using `BFD_JUMP_TABLE' macros.
These macros take a single argument, which is a prefix applied to a set
of functions.  The macros are then used to initialize the fields in the
target vector.

   For example, the `BFD_JUMP_TABLE_RELOCS' macro defines three
functions: `_get_reloc_upper_bound', `_canonicalize_reloc', and
`_bfd_reloc_type_lookup'.  A reference like `BFD_JUMP_TABLE_RELOCS
(foo)' will expand into three functions prefixed with `foo':
`foo_get_reloc_upper_bound', etc.  The `BFD_JUMP_TABLE_RELOCS' macro
will be placed such that those three functions initialize the
appropriate fields in the BFD target vector.

   This is done because it turns out that many different target vectors
can share certain classes of functions.  For example, archives are
similar on most platforms, so most target vectors can use the same
archive functions.  Those target vectors all use
`BFD_JUMP_TABLE_ARCHIVE' with the same argument, calling a set of
functions which is defined in `archive.c'.

   Each of the `BFD_JUMP_TABLE' macros is mentioned below along with
the description of the function pointers which it defines.  The function
pointers will be described using the name without the prefix which the
`BFD_JUMP_TABLE' macro defines.  This name is normally the same as the
name of the field in the target vector structure.  Any differences will
be noted.


File: bfdint.info,  Node: BFD target vector generic,  Next: BFD target vector copy,  Prev: BFD_JUMP_TABLE macros,  Up: BFD target vector

Generic functions
=================

   The `BFD_JUMP_TABLE_GENERIC' macro is used for some catch all
functions which don't easily fit into other categories.

`_close_and_cleanup'
     Free any target specific information associated with the BFD.
     This is called when any BFD is closed (the `bfd_write_contents'
     function mentioned earlier is only called for a BFD opened for
     writing).  Most targets use `bfd_alloc' to allocate all target
     specific information, and therefore don't have to do anything in
     this function.  This function pointer is typically set to
     `_bfd_generic_close_and_cleanup', which simply returns true.

`_bfd_free_cached_info'
     Free any cached information associated with the BFD which can be
     recreated later if necessary.  This is used to reduce the memory
     consumption required by programs using BFD.  This is normally
     called via the `bfd_free_cached_info' macro.  It is used by the
     default archive routines when computing the archive map.  Most
     targets do not do anything special for this entry point, and just
     set it to `_bfd_generic_free_cached_info', which simply returns
     true.

`_new_section_hook'
     This is called from `bfd_make_section_anyway' whenever a new
     section is created.  Most targets use it to initialize section
     specific information.  This function is called whether or not the
     section corresponds to an actual section in an actual BFD.

`_get_section_contents'
     Get the contents of a section.  This is called from
     `bfd_get_section_contents'.  Most targets set this to
     `_bfd_generic_get_section_contents', which does a `bfd_seek' based
     on the section's `filepos' field and a `bfd_read'.  The
     corresponding field in the target vector is named
     `_bfd_get_section_contents'.

`_get_section_contents_in_window'
     Set a `bfd_window' to hold the contents of a section.  This is
     called from `bfd_get_section_contents_in_window'.  The
     `bfd_window' idea never really caught on, and I don't think this is
     ever called.  Pretty much all targets implement this as
     `bfd_generic_get_section_contents_in_window', which uses
     `bfd_get_section_contents' to do the right thing.  The
     corresponding field in the target vector is named
     `_bfd_get_section_contents_in_window'.


File: bfdint.info,  Node: BFD target vector copy,  Next: BFD target vector core,  Prev: BFD target vector generic,  Up: BFD target vector

Copy functions
==============

   The `BFD_JUMP_TABLE_COPY' macro is used for functions which are
called when copying BFDs, and for a couple of functions which deal with
internal BFD information.

`_bfd_copy_private_bfd_data'
     This is called when copying a BFD, via `bfd_copy_private_bfd_data'.
     If the input and output BFDs have the same format, this will copy
     any private information over.  This is called after all the
     section contents have been written to the output file.  Only a few
     targets do anything in this function.

`_bfd_merge_private_bfd_data'
     This is called when linking, via `bfd_merge_private_bfd_data'.  It
     gives the backend linker code a chance to set any special flags in
     the output file based on the contents of the input file.  Only a
     few targets do anything in this function.

`_bfd_copy_private_section_data'
     This is similar to `_bfd_copy_private_bfd_data', but it is called
     for each section, via `bfd_copy_private_section_data'.  This
     function is called before any section contents have been written.
     Only a few targets do anything in this function.

`_bfd_copy_private_symbol_data'
     This is called via `bfd_copy_private_symbol_data', but I don't
     think anything actually calls it.  If it were defined, it could be
     used to copy private symbol data from one BFD to another.
     However, most BFDs store extra symbol information by allocating
     space which is larger than the `asymbol' structure and storing
     private information in the extra space.  Since `objcopy' and other
     programs copy symbol information by copying pointers to `asymbol'
     structures, the private symbol information is automatically copied
     as well.  Most targets do not do anything in this function.

`_bfd_set_private_flags'
     This is called via `bfd_set_private_flags'.  It is basically a hook
     for the assembler to set magic information.  For example, the
     PowerPC ELF assembler uses it to set flags which appear in the
     e_flags field of the ELF header.  Most targets do not do anything
     in this function.

`_bfd_print_private_bfd_data'
     This is called by `objdump' when the `-p' option is used.  It is
     called via `bfd_print_private_data'.  It prints any interesting
     information about the BFD which can not be otherwise represented
     by BFD and thus can not be printed by `objdump'.  Most targets do
     not do anything in this function.


File: bfdint.info,  Node: BFD target vector core,  Next: BFD target vector archive,  Prev: BFD target vector copy,  Up: BFD target vector

Core file support functions
===========================

   The `BFD_JUMP_TABLE_CORE' macro is used for functions which deal
with core files.  Obviously, these functions only do something
interesting for targets which have core file support.

`_core_file_failing_command'
     Given a core file, this returns the command which was run to
     produce the core file.

`_core_file_failing_signal'
     Given a core file, this returns the signal number which produced
     the core file.

`_core_file_matches_executable_p'
     Given a core file and a BFD for an executable, this returns
     whether the core file was generated by the executable.


File: bfdint.info,  Node: BFD target vector archive,  Next: BFD target vector symbols,  Prev: BFD target vector core,  Up: BFD target vector

Archive functions
=================

   The `BFD_JUMP_TABLE_ARCHIVE' macro is used for functions which deal
with archive files.  Most targets use COFF style archive files
(including ELF targets), and these use `_bfd_archive_coff' as the
argument to `BFD_JUMP_TABLE_ARCHIVE'.  Some targets use BSD/a.out style
archives, and these use `_bfd_archive_bsd'.  (The main difference
between BSD and COFF archives is the format of the archive symbol
table).  Targets with no archive support use `_bfd_noarchive'.
Finally, a few targets have unusual archive handling.

`_slurp_armap'
     Read in the archive symbol table, storing it in private BFD data.
     This is normally called from the archive `check_format' routine.
     The corresponding field in the target vector is named
     `_bfd_slurp_armap'.

`_slurp_extended_name_table'
     Read in the extended name table from the archive, if there is one,
     storing it in private BFD data.  This is normally called from the
     archive `check_format' routine.  The corresponding field in the
     target vector is named `_bfd_slurp_extended_name_table'.

`construct_extended_name_table'
     Build and return an extended name table if one is needed to write
     out the archive.  This also adjusts the archive headers to refer
     to the extended name table appropriately.  This is normally called
     from the archive `write_contents' routine.  The corresponding
     field in the target vector is named
     `_bfd_construct_extended_name_table'.

`_truncate_arname'
     This copies a file name into an archive header, truncating it as
     required.  It is normally called from the archive `write_contents'
     routine.  This function is more interesting in targets which do not
     support extended name tables, but I think the GNU `ar' program
     always uses extended name tables anyhow.  The corresponding field
     in the target vector is named `_bfd_truncate_arname'.

`_write_armap'
     Write out the archive symbol table using calls to `bfd_write'.
     This is normally called from the archive `write_contents' routine.
     The corresponding field in the target vector is named `write_armap'
     (no leading underscore).

`_read_ar_hdr'
     Read and parse an archive header.  This handles expanding the
     archive header name into the real file name using the extended
     name table.  This is called by routines which read the archive
     symbol table or the archive itself.  The corresponding field in
     the target vector is named `_bfd_read_ar_hdr_fn'.

`_openr_next_archived_file'
     Given an archive and a BFD representing a file stored within the
     archive, return a BFD for the next file in the archive.  This is
     called via `bfd_openr_next_archived_file'.  The corresponding
     field in the target vector is named `openr_next_archived_file' (no
     leading underscore).

`_get_elt_at_index'
     Given an archive and an index, return a BFD for the file in the
     archive corresponding to that entry in the archive symbol table.
     This is called via `bfd_get_elt_at_index'.  The corresponding
     field in the target vector is named `_bfd_get_elt_at_index'.

`_generic_stat_arch_elt'
     Do a stat on an element of an archive, returning information read
     from the archive header (modification time, uid, gid, file mode,
     size).  This is called via `bfd_stat_arch_elt'.  The corresponding
     field in the target vector is named `_bfd_stat_arch_elt'.

`_update_armap_timestamp'
     After the entire contents of an archive have been written out,
     update the timestamp of the archive symbol table to be newer than
     that of the file.  This is required for a.out style archives.
     This is normally called by the archive `write_contents' routine.
     The corresponding field in the target vector is named
     `_bfd_update_armap_timestamp'.


File: bfdint.info,  Node: BFD target vector symbols,  Next: BFD target vector relocs,  Prev: BFD target vector archive,  Up: BFD target vector

Symbol table functions
======================

   The `BFD_JUMP_TABLE_SYMBOLS' macro is used for functions which deal
with symbols.

`_get_symtab_upper_bound'
     Return a sensible upper bound on the amount of memory which will be
     required to read the symbol table.  In practice most targets
     return the amount of memory required to hold `asymbol' pointers
     for all the symbols plus a trailing `NULL' entry, and store the
     actual symbol information in BFD private data.  This is called via
     `bfd_get_symtab_upper_bound'.  The corresponding field in the
     target vector is named `_bfd_get_symtab_upper_bound'.

`_get_symtab'
     Read in the symbol table.  This is called via
     `bfd_canonicalize_symtab'.  The corresponding field in the target
     vector is named `_bfd_canonicalize_symtab'.

`_make_empty_symbol'
     Create an empty symbol for the BFD.  This is needed because most
     targets store extra information with each symbol by allocating a
     structure larger than an `asymbol' and storing the extra
     information at the end.  This function will allocate the right
     amount of memory, and return what looks like a pointer to an empty
     `asymbol'.  This is called via `bfd_make_empty_symbol'.  The
     corresponding field in the target vector is named
     `_bfd_make_empty_symbol'.

`_print_symbol'
     Print information about the symbol.  This is called via
     `bfd_print_symbol'.  One of the arguments indicates what sort of
     information should be printed:

    `bfd_print_symbol_name'
          Just print the symbol name.

    `bfd_print_symbol_more'
          Print the symbol name and some interesting flags.  I don't
          think anything actually uses this.

    `bfd_print_symbol_all'
          Print all information about the symbol.  This is used by
          `objdump' when run with the `-t' option.  The corresponding
     field in the target vector is named `_bfd_print_symbol'.

`_get_symbol_info'
     Return a standard set of information about the symbol.  This is
     called via `bfd_symbol_info'.  The corresponding field in the
     target vector is named `_bfd_get_symbol_info'.

`_bfd_is_local_label_name'
     Return whether the given string would normally represent the name
     of a local label.  This is called via `bfd_is_local_label' and
     `bfd_is_local_label_name'.  Local labels are normally discarded by
     the assembler.  In the linker, this defines the difference between
     the `-x' and `-X' options.

`_get_lineno'
     Return line number information for a symbol.  This is only
     meaningful for a COFF target.  This is called when writing out
     COFF line numbers.

`_find_nearest_line'
     Given an address within a section, use the debugging information
     to find the matching file name, function name, and line number, if
     any.  This is called via `bfd_find_nearest_line'.  The
     corresponding field in the target vector is named
     `_bfd_find_nearest_line'.

`_bfd_make_debug_symbol'
     Make a debugging symbol.  This is only meaningful for a COFF
     target, where it simply returns a symbol which will be placed in
     the `N_DEBUG' section when it is written out.  This is called via
     `bfd_make_debug_symbol'.

`_read_minisymbols'
     Minisymbols are used to reduce the memory requirements of programs
     like `nm'.  A minisymbol is a cookie pointing to internal symbol
     information which the caller can use to extract complete symbol
     information.  This permits BFD to not convert all the symbols into
     generic form, but to instead convert them one at a time.  This is
     called via `bfd_read_minisymbols'.  Most targets do not implement
     this, and just use generic support which is based on using standard
     `asymbol' structures.

`_minisymbol_to_symbol'
     Convert a minisymbol to a standard `asymbol'.  This is called via
     `bfd_minisymbol_to_symbol'.


File: bfdint.info,  Node: BFD target vector relocs,  Next: BFD target vector write,  Prev: BFD target vector symbols,  Up: BFD target vector

Relocation support
==================

   The `BFD_JUMP_TABLE_RELOCS' macro is used for functions which deal
with relocations.

`_get_reloc_upper_bound'
     Return a sensible upper bound on the amount of memory which will be
     required to read the relocations for a section.  In practice most
     targets return the amount of memory required to hold `arelent'
     pointers for all the relocations plus a trailing `NULL' entry, and
     store the actual relocation information in BFD private data.  This
     is called via `bfd_get_reloc_upper_bound'.

`_canonicalize_reloc'
     Return the relocation information for a section.  This is called
     via `bfd_canonicalize_reloc'.  The corresponding field in the
     target vector is named `_bfd_canonicalize_reloc'.

`_bfd_reloc_type_lookup'
     Given a relocation code, return the corresponding howto structure
     (*note BFD relocation codes::).  This is called via
     `bfd_reloc_type_lookup'.  The corresponding field in the target
     vector is named `reloc_type_lookup'.


File: bfdint.info,  Node: BFD target vector write,  Next: BFD target vector link,  Prev: BFD target vector relocs,  Up: BFD target vector

Output functions
================

   The `BFD_JUMP_TABLE_WRITE' macro is used for functions which deal
with writing out a BFD.

`_set_arch_mach'
     Set the architecture and machine number for a BFD.  This is called
     via `bfd_set_arch_mach'.  Most targets implement this by calling
     `bfd_default_set_arch_mach'.  The corresponding field in the target
     vector is named `_bfd_set_arch_mach'.

`_set_section_contents'
     Write out the contents of a section.  This is called via
     `bfd_set_section_contents'.  The corresponding field in the target
     vector is named `_bfd_set_section_contents'.


File: bfdint.info,  Node: BFD target vector link,  Next: BFD target vector dynamic,  Prev: BFD target vector write,  Up: BFD target vector

Linker functions
================

   The `BFD_JUMP_TABLE_LINK' macro is used for functions called by the
linker.

`_sizeof_headers'
     Return the size of the header information required for a BFD.
     This is used to implement the `SIZEOF_HEADERS' linker script
     function.  It is normally used to align the first section at an
     efficient position on the page.  This is called via
     `bfd_sizeof_headers'.  The corresponding field in the target
     vector is named `_bfd_sizeof_headers'.

`_bfd_get_relocated_section_contents'
     Read the contents of a section and apply the relocation
     information.  This handles both a final link and a relocateable
     link; in the latter case, it adjust the relocation information as
     well.  This is called via `bfd_get_relocated_section_contents'.
     Most targets implement it by calling
     `bfd_generic_get_relocated_section_contents'.

`_bfd_relax_section'
     Try to use relaxation to shrink the size of a section.  This is
     called by the linker when the `-relax' option is used.  This is
     called via `bfd_relax_section'.  Most targets do not support any
     sort of relaxation.

`_bfd_link_hash_table_create'
     Create the symbol hash table to use for the linker.  This linker
     hook permits the backend to control the size and information of
     the elements in the linker symbol hash table.  This is called via
     `bfd_link_hash_table_create'.

`_bfd_link_add_symbols'
     Given an object file or an archive, add all symbols into the linker
     symbol hash table.  Use callbacks to the linker to include archive
     elements in the link.  This is called via `bfd_link_add_symbols'.

`_bfd_final_link'
     Finish the linking process.  The linker calls this hook after all
     of the input files have been read, when it is ready to finish the
     link and generate the output file.  This is called via
     `bfd_final_link'.

`_bfd_link_split_section'
     I don't know what this is for.  Nothing seems to call it.  The only
     non-trivial definition is in `som.c'.


File: bfdint.info,  Node: BFD target vector dynamic,  Prev: BFD target vector link,  Up: BFD target vector

Dynamic linking information functions
=====================================

   The `BFD_JUMP_TABLE_DYNAMIC' macro is used for functions which read
dynamic linking information.

`_get_dynamic_symtab_upper_bound'
     Return a sensible upper bound on the amount of memory which will be
     required to read the dynamic symbol table.  In practice most
     targets return the amount of memory required to hold `asymbol'
     pointers for all the symbols plus a trailing `NULL' entry, and
     store the actual symbol information in BFD private data.  This is
     called via `bfd_get_dynamic_symtab_upper_bound'.  The
     corresponding field in the target vector is named
     `_bfd_get_dynamic_symtab_upper_bound'.

`_canonicalize_dynamic_symtab'
     Read the dynamic symbol table.  This is called via
     `bfd_canonicalize_dynamic_symtab'.  The corresponding field in the
     target vector is named `_bfd_canonicalize_dynamic_symtab'.

`_get_dynamic_reloc_upper_bound'
     Return a sensible upper bound on the amount of memory which will be
     required to read the dynamic relocations.  In practice most targets
     return the amount of memory required to hold `arelent' pointers for
     all the relocations plus a trailing `NULL' entry, and store the
     actual relocation information in BFD private data.  This is called
     via `bfd_get_dynamic_reloc_upper_bound'.  The corresponding field
     in the target vector is named `_bfd_get_dynamic_reloc_upper_bound'.

`_canonicalize_dynamic_reloc'
     Read the dynamic relocations.  This is called via
     `bfd_canonicalize_dynamic_reloc'.  The corresponding field in the
     target vector is named `_bfd_canonicalize_dynamic_reloc'.


File: bfdint.info,  Node: BFD generated files,  Next: BFD multiple compilations,  Prev: BFD target vector,  Up: Top

BFD generated files
*******************

   BFD contains several automatically generated files.  This section
describes them.  Some files are created at configure time, when you
configure BFD.  Some files are created at make time, when you build
BFD.  Some files are automatically rebuilt at make time, but only if
you configure with the `--enable-maintainer-mode' option.  Some files
live in the object directory--the directory from which you run
configure--and some live in the source directory.  All files that live
in the source directory are checked into the CVS repository.

`bfd.h'
     Lives in the object directory.  Created at make time from
     `bfd-in2.h' via `bfd-in3.h'.  `bfd-in3.h' is created at configure
     time from `bfd-in2.h'.  There are automatic dependencies to
     rebuild `bfd-in3.h' and hence `bfd.h' if `bfd-in2.h' changes, so
     you can normally ignore `bfd-in3.h', and just think about
     `bfd-in2.h' and `bfd.h'.

     `bfd.h' is built by replacing a few strings in `bfd-in2.h'.  To
     see them, search for `@' in `bfd-in2.h'.  They mainly control
     whether BFD is built for a 32 bit target or a 64 bit target.

`bfd-in2.h'
     Lives in the source directory.  Created from `bfd-in.h' and several
     other BFD source files.  If you configure with the
     `--enable-maintainer-mode' option, `bfd-in2.h' is rebuilt
     automatically when a source file changes.

`elf32-target.h'
`elf64-target.h'
     Live in the object directory.  Created from `elfxx-target.h'.
     These files are versions of `elfxx-target.h' customized for either
     a 32 bit ELF target or a 64 bit ELF target.

`libbfd.h'
     Lives in the source directory.  Created from `libbfd-in.h' and
     several other BFD source files.  If you configure with the
     `--enable-maintainer-mode' option, `libbfd.h' is rebuilt
     automatically when a source file changes.

`libcoff.h'
     Lives in the source directory.  Created from `libcoff-in.h' and
     `coffcode.h'.  If you configure with the
     `--enable-maintainer-mode' option, `libcoff.h' is rebuilt
     automatically when a source file changes.

`targmatch.h'
     Lives in the object directory.  Created at make time from
     `config.bfd'.  This file is used to map configuration triplets into
     BFD target vector variable names at run time.


File: bfdint.info,  Node: BFD multiple compilations,  Next: BFD relocation handling,  Prev: BFD generated files,  Up: Top

Files compiled multiple times in BFD
************************************

   Several files in BFD are compiled multiple times.  By this I mean
that there are header files which contain function definitions.  These
header files are included by other files, and thus the functions are
compiled once per file which includes them.

   Preprocessor macros are used to control the compilation, so that each
time the files are compiled the resulting functions are slightly
different.  Naturally, if they weren't different, there would be no
reason to compile them multiple times.

   This is a not a particularly good programming technique, and future
BFD work should avoid it.

   * Since this technique is rarely used, even experienced C
     programmers find it confusing.

   * It is difficult to debug programs which use BFD, since there is no
     way to describe which version of a particular function you are
     looking at.

   * Programs which use BFD wind up incorporating two or more slightly
     different versions of the same function, which wastes space in the
     executable.

   * This technique is never required nor is it especially efficient.
     It is always possible to use statically initialized structures
     holding function pointers and magic constants instead.

   The following is a list of the files which are compiled multiple
times.

`aout-target.h'
     Describes a few functions and the target vector for a.out targets.
     This is used by individual a.out targets with different
     definitions of `N_TXTADDR' and similar a.out macros.

`aoutf1.h'
     Implements standard SunOS a.out files.  In principle it supports
     64 bit a.out targets based on the preprocessor macro `ARCH_SIZE',
     but since all known a.out targets are 32 bits, this code may or
     may not work.  This file is only included by a few other files,
     and it is difficult to justify its existence.

`aoutx.h'
     Implements basic a.out support routines.  This file can be
     compiled for either 32 or 64 bit support.  Since all known a.out
     targets are 32 bits, the 64 bit support may or may not work.  I
     believe the original intention was that this file would only be
     included by `aout32.c' and `aout64.c', and that other a.out
     targets would simply refer to the functions it defined.
     Unfortunately, some other a.out targets started including it
     directly, leading to a somewhat confused state of affairs.

`coffcode.h'
     Implements basic COFF support routines.  This file is included by
     every COFF target.  It implements code which handles COFF magic
     numbers as well as various hook functions called by the generic
     COFF functions in `coffgen.c'.  This file is controlled by a
     number of different macros, and more are added regularly.

`coffswap.h'
     Implements COFF swapping routines.  This file is included by
     `coffcode.h', and thus by every COFF target.  It implements the
     routines which swap COFF structures between internal and external
     format.  The main control for this file is the external structure
     definitions in the files in the `include/coff' directory.  A COFF
     target file will include one of those files before including
     `coffcode.h' and thus `coffswap.h'.  There are a few other macros
     which affect `coffswap.h' as well, mostly describing whether
     certain fields are present in the external structures.

`ecoffswap.h'
     Implements ECOFF swapping routines.  This is like `coffswap.h', but
     for ECOFF.  It is included by the ECOFF target files (of which
     there are only two).  The control is the preprocessor macro
     `ECOFF_32' or `ECOFF_64'.

`elfcode.h'
     Implements ELF functions that use external structure definitions.
     This file is included by two other files: `elf32.c' and `elf64.c'.
     It is controlled by the `ARCH_SIZE' macro which is defined to be
     `32' or `64' before including it.  The `NAME' macro is used
     internally to give the functions different names for the two target
     sizes.

`elfcore.h'
     Like `elfcode.h', but for functions that are specific to ELF core
     files.  This is included only by `elfcode.h'.

`elflink.h'
     Like `elfcode.h', but for functions used by the ELF linker.  This
     is included only by `elfcode.h'.

`elfxx-target.h'
     This file is the source for the generated files `elf32-target.h'
     and `elf64-target.h', one of which is included by every ELF target.
     It defines the ELF target vector.

`freebsd.h'
     Presumably intended to be included by all FreeBSD targets, but in
     fact there is only one such target, `i386-freebsd'.  This defines a
     function used to set the right magic number for FreeBSD, as well as
     various macros, and includes `aout-target.h'.

`netbsd.h'
     Like `freebsd.h', except that there are several files which include
     it.

`nlm-target.h'
     Defines the target vector for a standard NLM target.

`nlmcode.h'
     Like `elfcode.h', but for NLM targets.  This is only included by
     `nlm32.c' and `nlm64.c', both of which define the macro
     `ARCH_SIZE' to an appropriate value.  There are no 64 bit NLM
     targets anyhow, so this is sort of useless.

`nlmswap.h'
     Like `coffswap.h', but for NLM targets.  This is included by each
     NLM target, but I think it winds up compiling to the exact same
     code for every target, and as such is fairly useless.

`peicode.h'
     Provides swapping routines and other hooks for PE targets.
     `coffcode.h' will include this rather than `coffswap.h' for a PE
     target.  This defines PE specific versions of the COFF swapping
     routines, and also defines some macros which control `coffcode.h'
     itself.


File: bfdint.info,  Node: BFD relocation handling,  Next: BFD ELF support,  Prev: BFD multiple compilations,  Up: Top

BFD relocation handling
***********************

   The handling of relocations is one of the more confusing aspects of
BFD.  Relocation handling has been implemented in various different
ways, all somewhat incompatible, none perfect.

* Menu:

* BFD relocation concepts::	BFD relocation concepts
* BFD relocation functions::	BFD relocation functions
* BFD relocation codes::	BFD relocation codes
* BFD relocation future::	BFD relocation future


File: bfdint.info,  Node: BFD relocation concepts,  Next: BFD relocation functions,  Up: BFD relocation handling

BFD relocation concepts
=======================

   A relocation is an action which the linker must take when linking.
It describes a change to the contents of a section.  The change is
normally based on the final value of one or more symbols.  Relocations
are created by the assembler when it creates an object file.

   Most relocations are simple.  A typical simple relocation is to set
32 bits at a given offset in a section to the value of a symbol.  This
type of relocation would be generated for code like `int *p = &i;' where
`p' and `i' are global variables.  A relocation for the symbol `i'
would be generated such that the linker would initialize the area of
memory which holds the value of `p' to the value of the symbol `i'.

   Slightly more complex relocations may include an addend, which is a
constant to add to the symbol value before using it.  In some cases a
relocation will require adding the symbol value to the existing contents
of the section in the object file.  In others the relocation will simply
replace the contents of the section with the symbol value.  Some
relocations are PC relative, so that the value to be stored in the
section is the difference between the value of a symbol and the final
address of the section contents.

   In general, relocations can be arbitrarily complex.  For example,
relocations used in dynamic linking systems often require the linker to
allocate space in a different section and use the offset within that
section as the value to store.  In the IEEE object file format,
relocations may involve arbitrary expressions.

   When doing a relocateable link, the linker may or may not have to do
anything with a relocation, depending upon the definition of the
relocation.  Simple relocations generally do not require any special
action.

