summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTristan Gingold <gingold@adacore.com>2009-10-16 12:06:59 +0000
committerTristan Gingold <gingold@adacore.com>2009-10-16 12:06:59 +0000
commitde03bdf76f482fcc86c9f1aec069cab08257602b (patch)
tree4f814f9c08dbd9787ab8171674eb08b45f5f871f
parentee6ea2b1e3def5622ef5f7a63c03514fb1342411 (diff)
downloadgdb-binutils-2_20.tar.gz
bfd/binutils-2_20
2009-10-16 Tristan Gingold <gingold@adacore.com> * configure.in: Bump version to 2.20 * Makefile.am (RELEASE): Set. * configure, Makefile.in: Regenerate.
Diffstat
-rw-r--r--bfd/ChangeLog6
-rw-r--r--bfd/Makefile.am2
-rw-r--r--bfd/Makefile.in2
-rwxr-xr-xbfd/configure2
-rw-r--r--bfd/configure.in2
-rw-r--r--bfd/doc/aoutx.texi213
-rw-r--r--bfd/doc/archive.texi99
-rw-r--r--bfd/doc/archures.texi626
-rw-r--r--bfd/doc/bfd.info11288
-rw-r--r--bfd/doc/bfdio.texi85
-rw-r--r--bfd/doc/bfdt.texi871
-rw-r--r--bfd/doc/bfdver.texi4
-rw-r--r--bfd/doc/bfdwin.texi2
-rw-r--r--bfd/doc/cache.texi65
-rw-r--r--bfd/doc/coffcode.texi685
-rw-r--r--bfd/doc/core.texi60
-rw-r--r--bfd/doc/elf.texi9
-rw-r--r--bfd/doc/elfcode.texi0
-rw-r--r--bfd/doc/format.texi112
-rw-r--r--bfd/doc/hash.texi247
-rw-r--r--bfd/doc/init.texi16
-rw-r--r--bfd/doc/libbfd.texi179
-rw-r--r--bfd/doc/linker.texi412
-rw-r--r--bfd/doc/mmo.texi365
-rw-r--r--bfd/doc/opncls.texi372
-rw-r--r--bfd/doc/reloc.texi2813
-rw-r--r--bfd/doc/section.texi1007
-rw-r--r--bfd/doc/syms.texi479
-rw-r--r--bfd/doc/targets.texi563
-rw-r--r--etc/configure.info2773
-rw-r--r--etc/standards.info5576
31 files changed, 28931 insertions, 4 deletions
diff --git a/bfd/ChangeLog b/bfd/ChangeLog
index c2b03ea2253..316725d9377 100644
--- a/bfd/ChangeLog
+++ b/bfd/ChangeLog
@@ -1,3 +1,9 @@
+2009-10-16 Tristan Gingold <gingold@adacore.com>
+
+ * configure.in: Bump version to 2.20
+ * Makefile.am (RELEASE): Set.
+ * configure, Makefile.in: Regenerate.
+
2009-10-16 Alan Modra <amodra@bigpond.net.au>
PR binutils/10785
diff --git a/bfd/Makefile.am b/bfd/Makefile.am
index 13ace292176..a0c1eaa0902 100644
--- a/bfd/Makefile.am
+++ b/bfd/Makefile.am
@@ -4,7 +4,7 @@ AUTOMAKE_OPTIONS = 1.11 no-dist foreign
ACLOCAL_AMFLAGS = -I . -I .. -I ../config
# Uncomment the following line when doing a release.
-# RELEASE=y
+RELEASE=y
INCDIR = $(srcdir)/../include
CSEARCH = -I. -I$(srcdir) -I$(INCDIR)
diff --git a/bfd/Makefile.in b/bfd/Makefile.in
index 721069f05e7..6bebad7e872 100644
--- a/bfd/Makefile.in
+++ b/bfd/Makefile.in
@@ -317,7 +317,7 @@ AUTOMAKE_OPTIONS = 1.11 no-dist foreign
ACLOCAL_AMFLAGS = -I . -I .. -I ../config
# Uncomment the following line when doing a release.
-# RELEASE=y
+RELEASE = y
INCDIR = $(srcdir)/../include
CSEARCH = -I. -I$(srcdir) -I$(INCDIR)
SUBDIRS = doc po
diff --git a/bfd/configure b/bfd/configure
index 4c845b22266..dcc9bd91528 100755
--- a/bfd/configure
+++ b/bfd/configure
@@ -4116,7 +4116,7 @@ fi
# Define the identity of the package.
PACKAGE=bfd
- VERSION=2.19.92
+ VERSION=2.20
cat >>confdefs.h <<_ACEOF
diff --git a/bfd/configure.in b/bfd/configure.in
index 208b30b9df3..d03a271724e 100644
--- a/bfd/configure.in
+++ b/bfd/configure.in
@@ -8,7 +8,7 @@ AC_CONFIG_SRCDIR([libbfd.c])
AC_CANONICAL_TARGET
AC_ISC_POSIX
-AM_INIT_AUTOMAKE(bfd, 2.19.92)
+AM_INIT_AUTOMAKE(bfd, 2.20)
dnl These must be called before LT_INIT, because it may want
dnl to call AC_CHECK_PROG.
diff --git a/bfd/doc/aoutx.texi b/bfd/doc/aoutx.texi
new file mode 100644
index 00000000000..7cf9787f106
--- /dev/null
+++ b/bfd/doc/aoutx.texi
@@ -0,0 +1,213 @@
+@section a.out backends
+
+
+@strong{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 @file{aoutx.h}
+and other files which derive functions from the base. One
+derivation file is @file{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 @file{sunos.c} for sun3 and sun4,
+@file{newsos3.c} for the Sony NEWS, and @file{demo64.c} for a
+demonstration of a 64 bit a.out format.
+
+The base file @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
+@file{aout32.c} and @file{aout64.c} to form the names
+@code{aout_32_swap_exec_header_in}, @code{aout_64_swap_exec_header_in}, etc.
+
+As an example, this is what goes on to make the back end for a
+sun4, from @file{aout32.c}:
+
+@example
+ #define ARCH_SIZE 32
+ #include "aoutx.h"
+@end example
+
+Which exports names:
+
+@example
+ ...
+ aout_32_canonicalize_reloc
+ aout_32_find_nearest_line
+ aout_32_get_lineno
+ aout_32_get_reloc_upper_bound
+ ...
+@end example
+
+from @file{sunos.c}:
+
+@example
+ #define TARGET_NAME "a.out-sunos-big"
+ #define VECNAME sunos_big_vec
+ #include "aoutf1.h"
+@end example
+
+requires all the names from @file{aout32.c}, and produces the jump vector
+
+@example
+ sunos_big_vec
+@end example
+
+The file @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:
+
+@example
+ HOST_PAGE_SIZE
+ HOST_SEGMENT_SIZE
+ HOST_MACHINE_ARCH (optional)
+ HOST_MACHINE_MACHINE (optional)
+ HOST_TEXT_START_ADDR
+ HOST_STACK_END_ADDR
+@end example
+
+in the file @file{../include/sys/h-@var{XXX}.h} (for your host). These
+values, plus the structures and macros defined in @file{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 @file{host-aout.c}, specify:
+
+@example
+ TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
+ TDEPFILES= host-aout.o trad-core.o
+@end example
+
+in the @file{config/@var{XXX}.mt} file, and modify @file{configure.in}
+to use the
+@file{@var{XXX}.mt} file (by setting "@code{bfd_target=XXX}") when your
+configuration is selected.
+
+@subsection Relocations
+
+
+@strong{Description}@*
+The file @file{aoutx.h} provides for both the @emph{standard}
+and @emph{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.
+
+@subsection Internal entry points
+
+
+@strong{Description}@*
+@file{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).
+
+@findex aout_@var{size}_swap_exec_header_in
+@subsubsection @code{aout_@var{size}_swap_exec_header_in}
+@strong{Synopsis}
+@example
+void aout_@var{size}_swap_exec_header_in,
+ (bfd *abfd,
+ struct external_exec *bytes,
+ struct internal_exec *execp);
+@end example
+@strong{Description}@*
+Swap the information in an executable header @var{raw_bytes} taken
+from a raw byte stream memory image into the internal exec header
+structure @var{execp}.
+
+@findex aout_@var{size}_swap_exec_header_out
+@subsubsection @code{aout_@var{size}_swap_exec_header_out}
+@strong{Synopsis}
+@example
+void aout_@var{size}_swap_exec_header_out
+ (bfd *abfd,
+ struct internal_exec *execp,
+ struct external_exec *raw_bytes);
+@end example
+@strong{Description}@*
+Swap the information in an internal exec header structure
+@var{execp} into the buffer @var{raw_bytes} ready for writing to disk.
+
+@findex aout_@var{size}_some_aout_object_p
+@subsubsection @code{aout_@var{size}_some_aout_object_p}
+@strong{Synopsis}
+@example
+const bfd_target *aout_@var{size}_some_aout_object_p
+ (bfd *abfd,
+ struct internal_exec *execp,
+ const bfd_target *(*callback_to_real_object_p) (bfd *));
+@end example
+@strong{Description}@*
+Some a.out variant thinks that the file open in @var{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.
+
+@findex aout_@var{size}_mkobject
+@subsubsection @code{aout_@var{size}_mkobject}
+@strong{Synopsis}
+@example
+bfd_boolean aout_@var{size}_mkobject, (bfd *abfd);
+@end example
+@strong{Description}@*
+Initialize BFD @var{abfd} for use with a.out files.
+
+@findex aout_@var{size}_machine_type
+@subsubsection @code{aout_@var{size}_machine_type}
+@strong{Synopsis}
+@example
+enum machine_type aout_@var{size}_machine_type
+ (enum bfd_architecture arch,
+ unsigned long machine,
+ bfd_boolean *unknown);
+@end example
+@strong{Description}@*
+Keep track of machine architecture and machine type for
+a.out's. Return the @code{machine_type} for a particular
+architecture and machine, or @code{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.
+
+@findex aout_@var{size}_set_arch_mach
+@subsubsection @code{aout_@var{size}_set_arch_mach}
+@strong{Synopsis}
+@example
+bfd_boolean aout_@var{size}_set_arch_mach,
+ (bfd *,
+ enum bfd_architecture arch,
+ unsigned long machine);
+@end example
+@strong{Description}@*
+Set the architecture and the machine of the BFD @var{abfd} to the
+values @var{arch} and @var{machine}. Verify that @var{abfd}'s format
+can support the architecture required.
+
+@findex aout_@var{size}_new_section_hook
+@subsubsection @code{aout_@var{size}_new_section_hook}
+@strong{Synopsis}
+@example
+bfd_boolean aout_@var{size}_new_section_hook,
+ (bfd *abfd,
+ asection *newsect);
+@end example
+@strong{Description}@*
+Called by the BFD in response to a @code{bfd_make_section}
+request.
+
diff --git a/bfd/doc/archive.texi b/bfd/doc/archive.texi
new file mode 100644
index 00000000000..3d0a97d4b82
--- /dev/null
+++ b/bfd/doc/archive.texi
@@ -0,0 +1,99 @@
+@section Archives
+
+
+@strong{Description}@*
+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 that are considered its contents. These BFDs can
+be manipulated 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; they will be handled correctly when the archive is closed.
+
+Use @code{bfd_openr_next_archived_file} to step through
+the contents of an archive opened for input. You don't
+have to 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
+@code{next} pointer in a BFD. The first one is findable through
+the @code{archive_head} slot of the archive. Set it with
+@code{bfd_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; SunOS 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 case due to restrictions 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.
+
+Archives are supported in BFD in @code{archive.c}.
+
+@subsection Archive functions
+
+
+@findex bfd_get_next_mapent
+@subsubsection @code{bfd_get_next_mapent}
+@strong{Synopsis}
+@example
+symindex bfd_get_next_mapent
+ (bfd *abfd, symindex previous, carsym **sym);
+@end example
+@strong{Description}@*
+Step through archive @var{abfd}'s symbol table (if it
+has one). Successively update @var{sym} with the next symbol's
+information, returning that symbol's (internal) index into the
+symbol table.
+
+Supply @code{BFD_NO_MORE_SYMBOLS} as the @var{previous} entry to get
+the first one; returns @code{BFD_NO_MORE_SYMBOLS} when you've already
+got the last one.
+
+A @code{carsym} is a canonical archive symbol. The only
+user-visible element is its name, a null-terminated string.
+
+@findex bfd_set_archive_head
+@subsubsection @code{bfd_set_archive_head}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head);
+@end example
+@strong{Description}@*
+Set the head of the chain of
+BFDs contained in the archive @var{output} to @var{new_head}.
+
+@findex bfd_openr_next_archived_file
+@subsubsection @code{bfd_openr_next_archived_file}
+@strong{Synopsis}
+@example
+bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous);
+@end example
+@strong{Description}@*
+Provided a BFD, @var{archive}, containing an archive and NULL, open
+an input BFD on the first contained element and returns that.
+Subsequent calls 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.
+
diff --git a/bfd/doc/archures.texi b/bfd/doc/archures.texi
new file mode 100644
index 00000000000..33d7c595a39
--- /dev/null
+++ b/bfd/doc/archures.texi
@@ -0,0 +1,626 @@
+@section Architectures
+BFD keeps one atom in a BFD describing the
+architecture of the data attached to the BFD: a pointer to a
+@code{bfd_arch_info_type}.
+
+Pointers to structures can be requested independently of a BFD
+so that an architecture's information can be interrogated
+without access to an open BFD.
+
+The architecture information is provided by each architecture package.
+The set of default architectures is selected by the macro
+@code{SELECT_ARCHITECTURES}. This is normally set up in the
+@file{config/@var{target}.mt} file of your choice. If the name is not
+defined, then all the architectures supported are included.
+
+When BFD starts up, all the architectures are called with an
+initialize method. It is up to the architecture back end to
+insert as many items into the list of architectures as it wants to;
+generally this would be one for each machine and one for the
+default case (an item with a machine field of 0).
+
+BFD's idea of an architecture is implemented in @file{archures.c}.
+
+@subsection bfd_architecture
+
+
+@strong{Description}@*
+This enum gives the object file's CPU architecture, in a
+global sense---i.e., what processor family does it belong to?
+Another field indicates which processor within
+the family is in use. The machine gives a number which
+distinguishes different versions of the architecture,
+containing, for example, 2 and 3 for Intel i960 KA and i960 KB,
+and 68020 and 68030 for Motorola 68020 and 68030.
+@example
+enum bfd_architecture
+@{
+ bfd_arch_unknown, /* File arch not known. */
+ bfd_arch_obscure, /* Arch known, not one of these. */
+ bfd_arch_m68k, /* Motorola 68xxx */
+#define bfd_mach_m68000 1
+#define bfd_mach_m68008 2
+#define bfd_mach_m68010 3
+#define bfd_mach_m68020 4
+#define bfd_mach_m68030 5
+#define bfd_mach_m68040 6
+#define bfd_mach_m68060 7
+#define bfd_mach_cpu32 8
+#define bfd_mach_fido 9
+#define bfd_mach_mcf_isa_a_nodiv 10
+#define bfd_mach_mcf_isa_a 11
+#define bfd_mach_mcf_isa_a_mac 12
+#define bfd_mach_mcf_isa_a_emac 13
+#define bfd_mach_mcf_isa_aplus 14
+#define bfd_mach_mcf_isa_aplus_mac 15
+#define bfd_mach_mcf_isa_aplus_emac 16
+#define bfd_mach_mcf_isa_b_nousp 17
+#define bfd_mach_mcf_isa_b_nousp_mac 18
+#define bfd_mach_mcf_isa_b_nousp_emac 19
+#define bfd_mach_mcf_isa_b 20
+#define bfd_mach_mcf_isa_b_mac 21
+#define bfd_mach_mcf_isa_b_emac 22
+#define bfd_mach_mcf_isa_b_float 23
+#define bfd_mach_mcf_isa_b_float_mac 24
+#define bfd_mach_mcf_isa_b_float_emac 25
+#define bfd_mach_mcf_isa_c 26
+#define bfd_mach_mcf_isa_c_mac 27
+#define bfd_mach_mcf_isa_c_emac 28
+#define bfd_mach_mcf_isa_c_nodiv 29
+#define bfd_mach_mcf_isa_c_nodiv_mac 30
+#define bfd_mach_mcf_isa_c_nodiv_emac 31
+ bfd_arch_vax, /* DEC Vax */
+ bfd_arch_i960, /* Intel 960 */
+ /* The order of the following is important.
+ lower number indicates a machine type that
+ only accepts a subset of the instructions
+ available to machines with higher numbers.
+ The exception is the "ca", which is
+ incompatible with all other machines except
+ "core". */
+
+#define bfd_mach_i960_core 1
+#define bfd_mach_i960_ka_sa 2
+#define bfd_mach_i960_kb_sb 3
+#define bfd_mach_i960_mc 4
+#define bfd_mach_i960_xa 5
+#define bfd_mach_i960_ca 6
+#define bfd_mach_i960_jx 7
+#define bfd_mach_i960_hx 8
+
+ bfd_arch_or32, /* OpenRISC 32 */
+
+ bfd_arch_sparc, /* SPARC */
+#define bfd_mach_sparc 1
+/* The difference between v8plus and v9 is that v9 is a true 64 bit env. */
+#define bfd_mach_sparc_sparclet 2
+#define bfd_mach_sparc_sparclite 3
+#define bfd_mach_sparc_v8plus 4
+#define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */
+#define bfd_mach_sparc_sparclite_le 6
+#define bfd_mach_sparc_v9 7
+#define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */
+#define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */
+#define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */
+/* Nonzero if MACH has the v9 instruction set. */
+#define bfd_mach_sparc_v9_p(mach) \
+ ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \
+ && (mach) != bfd_mach_sparc_sparclite_le)
+/* Nonzero if MACH is a 64 bit sparc architecture. */
+#define bfd_mach_sparc_64bit_p(mach) \
+ ((mach) >= bfd_mach_sparc_v9 && (mach) != bfd_mach_sparc_v8plusb)
+ bfd_arch_spu, /* PowerPC SPU */
+#define bfd_mach_spu 256
+ bfd_arch_mips, /* MIPS Rxxxx */
+#define bfd_mach_mips3000 3000
+#define bfd_mach_mips3900 3900
+#define bfd_mach_mips4000 4000
+#define bfd_mach_mips4010 4010
+#define bfd_mach_mips4100 4100
+#define bfd_mach_mips4111 4111
+#define bfd_mach_mips4120 4120
+#define bfd_mach_mips4300 4300
+#define bfd_mach_mips4400 4400
+#define bfd_mach_mips4600 4600
+#define bfd_mach_mips4650 4650
+#define bfd_mach_mips5000 5000
+#define bfd_mach_mips5400 5400
+#define bfd_mach_mips5500 5500
+#define bfd_mach_mips6000 6000
+#define bfd_mach_mips7000 7000
+#define bfd_mach_mips8000 8000
+#define bfd_mach_mips9000 9000
+#define bfd_mach_mips10000 10000
+#define bfd_mach_mips12000 12000
+#define bfd_mach_mips14000 14000
+#define bfd_mach_mips16000 16000
+#define bfd_mach_mips16 16
+#define bfd_mach_mips5 5
+#define bfd_mach_mips_loongson_2e 3001
+#define bfd_mach_mips_loongson_2f 3002
+#define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01 */
+#define bfd_mach_mips_octeon 6501
+#define bfd_mach_mips_xlr 887682 /* decimal 'XLR' */
+#define bfd_mach_mipsisa32 32
+#define bfd_mach_mipsisa32r2 33
+#define bfd_mach_mipsisa64 64
+#define bfd_mach_mipsisa64r2 65
+ bfd_arch_i386, /* Intel 386 */
+#define bfd_mach_i386_i386 1
+#define bfd_mach_i386_i8086 2
+#define bfd_mach_i386_i386_intel_syntax 3
+#define bfd_mach_x86_64 64
+#define bfd_mach_x86_64_intel_syntax 65
+ bfd_arch_l1om, /* Intel L1OM */
+#define bfd_mach_l1om 66
+#define bfd_mach_l1om_intel_syntax 67
+ bfd_arch_we32k, /* AT&T WE32xxx */
+ bfd_arch_tahoe, /* CCI/Harris Tahoe */
+ bfd_arch_i860, /* Intel 860 */
+ bfd_arch_i370, /* IBM 360/370 Mainframes */
+ bfd_arch_romp, /* IBM ROMP PC/RT */
+ bfd_arch_convex, /* Convex */
+ bfd_arch_m88k, /* Motorola 88xxx */
+ bfd_arch_m98k, /* Motorola 98xxx */
+ bfd_arch_pyramid, /* Pyramid Technology */
+ bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300) */
+#define bfd_mach_h8300 1
+#define bfd_mach_h8300h 2
+#define bfd_mach_h8300s 3
+#define bfd_mach_h8300hn 4
+#define bfd_mach_h8300sn 5
+#define bfd_mach_h8300sx 6
+#define bfd_mach_h8300sxn 7
+ bfd_arch_pdp11, /* DEC PDP-11 */
+ bfd_arch_plugin,
+ bfd_arch_powerpc, /* PowerPC */
+#define bfd_mach_ppc 32
+#define bfd_mach_ppc64 64
+#define bfd_mach_ppc_403 403
+#define bfd_mach_ppc_403gc 4030
+#define bfd_mach_ppc_405 405
+#define bfd_mach_ppc_505 505
+#define bfd_mach_ppc_601 601
+#define bfd_mach_ppc_602 602
+#define bfd_mach_ppc_603 603
+#define bfd_mach_ppc_ec603e 6031
+#define bfd_mach_ppc_604 604
+#define bfd_mach_ppc_620 620
+#define bfd_mach_ppc_630 630
+#define bfd_mach_ppc_750 750
+#define bfd_mach_ppc_860 860
+#define bfd_mach_ppc_a35 35
+#define bfd_mach_ppc_rs64ii 642
+#define bfd_mach_ppc_rs64iii 643
+#define bfd_mach_ppc_7400 7400
+#define bfd_mach_ppc_e500 500
+#define bfd_mach_ppc_e500mc 5001
+ bfd_arch_rs6000, /* IBM RS/6000 */
+#define bfd_mach_rs6k 6000
+#define bfd_mach_rs6k_rs1 6001
+#define bfd_mach_rs6k_rsc 6003
+#define bfd_mach_rs6k_rs2 6002
+ bfd_arch_hppa, /* HP PA RISC */
+#define bfd_mach_hppa10 10
+#define bfd_mach_hppa11 11
+#define bfd_mach_hppa20 20
+#define bfd_mach_hppa20w 25
+ bfd_arch_d10v, /* Mitsubishi D10V */
+#define bfd_mach_d10v 1
+#define bfd_mach_d10v_ts2 2
+#define bfd_mach_d10v_ts3 3
+ bfd_arch_d30v, /* Mitsubishi D30V */
+ bfd_arch_dlx, /* DLX */
+ bfd_arch_m68hc11, /* Motorola 68HC11 */
+ bfd_arch_m68hc12, /* Motorola 68HC12 */
+#define bfd_mach_m6812_default 0
+#define bfd_mach_m6812 1
+#define bfd_mach_m6812s 2
+ bfd_arch_z8k, /* Zilog Z8000 */
+#define bfd_mach_z8001 1
+#define bfd_mach_z8002 2
+ bfd_arch_h8500, /* Renesas H8/500 (formerly Hitachi H8/500) */
+ bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH) */
+#define bfd_mach_sh 1
+#define bfd_mach_sh2 0x20
+#define bfd_mach_sh_dsp 0x2d
+#define bfd_mach_sh2a 0x2a
+#define bfd_mach_sh2a_nofpu 0x2b
+#define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1
+#define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2
+#define bfd_mach_sh2a_or_sh4 0x2a3
+#define bfd_mach_sh2a_or_sh3e 0x2a4
+#define bfd_mach_sh2e 0x2e
+#define bfd_mach_sh3 0x30
+#define bfd_mach_sh3_nommu 0x31
+#define bfd_mach_sh3_dsp 0x3d
+#define bfd_mach_sh3e 0x3e
+#define bfd_mach_sh4 0x40
+#define bfd_mach_sh4_nofpu 0x41
+#define bfd_mach_sh4_nommu_nofpu 0x42
+#define bfd_mach_sh4a 0x4a
+#define bfd_mach_sh4a_nofpu 0x4b
+#define bfd_mach_sh4al_dsp 0x4d
+#define bfd_mach_sh5 0x50
+ bfd_arch_alpha, /* Dec Alpha */
+#define bfd_mach_alpha_ev4 0x10
+#define bfd_mach_alpha_ev5 0x20
+#define bfd_mach_alpha_ev6 0x30
+ bfd_arch_arm, /* Advanced Risc Machines ARM. */
+#define bfd_mach_arm_unknown 0
+#define bfd_mach_arm_2 1
+#define bfd_mach_arm_2a 2
+#define bfd_mach_arm_3 3
+#define bfd_mach_arm_3M 4
+#define bfd_mach_arm_4 5
+#define bfd_mach_arm_4T 6
+#define bfd_mach_arm_5 7
+#define bfd_mach_arm_5T 8
+#define bfd_mach_arm_5TE 9
+#define bfd_mach_arm_XScale 10
+#define bfd_mach_arm_ep9312 11
+#define bfd_mach_arm_iWMMXt 12
+#define bfd_mach_arm_iWMMXt2 13
+ bfd_arch_ns32k, /* National Semiconductors ns32000 */
+ bfd_arch_w65, /* WDC 65816 */
+ bfd_arch_tic30, /* Texas Instruments TMS320C30 */
+ bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X */
+#define bfd_mach_tic3x 30
+#define bfd_mach_tic4x 40
+ bfd_arch_tic54x, /* Texas Instruments TMS320C54X */
+ bfd_arch_tic80, /* TI TMS320c80 (MVP) */
+ bfd_arch_v850, /* NEC V850 */
+#define bfd_mach_v850 1
+#define bfd_mach_v850e 'E'
+#define bfd_mach_v850e1 '1'
+ bfd_arch_arc, /* ARC Cores */
+#define bfd_mach_arc_5 5
+#define bfd_mach_arc_6 6
+#define bfd_mach_arc_7 7
+#define bfd_mach_arc_8 8
+ bfd_arch_m32c, /* Renesas M16C/M32C. */
+#define bfd_mach_m16c 0x75
+#define bfd_mach_m32c 0x78
+ bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D) */
+#define bfd_mach_m32r 1 /* For backwards compatibility. */
+#define bfd_mach_m32rx 'x'
+#define bfd_mach_m32r2 '2'
+ bfd_arch_mn10200, /* Matsushita MN10200 */
+ bfd_arch_mn10300, /* Matsushita MN10300 */
+#define bfd_mach_mn10300 300
+#define bfd_mach_am33 330
+#define bfd_mach_am33_2 332
+ bfd_arch_fr30,
+#define bfd_mach_fr30 0x46523330
+ bfd_arch_frv,
+#define bfd_mach_frv 1
+#define bfd_mach_frvsimple 2
+#define bfd_mach_fr300 300
+#define bfd_mach_fr400 400
+#define bfd_mach_fr450 450
+#define bfd_mach_frvtomcat 499 /* fr500 prototype */
+#define bfd_mach_fr500 500
+#define bfd_mach_fr550 550
+ bfd_arch_moxie, /* The moxie processor */
+#define bfd_mach_moxie 1
+ bfd_arch_mcore,
+ bfd_arch_mep,
+#define bfd_mach_mep 1
+#define bfd_mach_mep_h1 0x6831
+#define bfd_mach_mep_c5 0x6335
+ bfd_arch_ia64, /* HP/Intel ia64 */
+#define bfd_mach_ia64_elf64 64
+#define bfd_mach_ia64_elf32 32
+ bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */
+#define bfd_mach_ip2022 1
+#define bfd_mach_ip2022ext 2
+ bfd_arch_iq2000, /* Vitesse IQ2000. */
+#define bfd_mach_iq2000 1
+#define bfd_mach_iq10 2
+ bfd_arch_mt,
+#define bfd_mach_ms1 1
+#define bfd_mach_mrisc2 2
+#define bfd_mach_ms2 3
+ bfd_arch_pj,
+ bfd_arch_avr, /* Atmel AVR microcontrollers. */
+#define bfd_mach_avr1 1
+#define bfd_mach_avr2 2
+#define bfd_mach_avr25 25
+#define bfd_mach_avr3 3
+#define bfd_mach_avr31 31
+#define bfd_mach_avr35 35
+#define bfd_mach_avr4 4
+#define bfd_mach_avr5 5
+#define bfd_mach_avr51 51
+#define bfd_mach_avr6 6
+ bfd_arch_bfin, /* ADI Blackfin */
+#define bfd_mach_bfin 1
+ bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */
+#define bfd_mach_cr16 1
+ bfd_arch_cr16c, /* National Semiconductor CompactRISC. */
+#define bfd_mach_cr16c 1
+ bfd_arch_crx, /* National Semiconductor CRX. */
+#define bfd_mach_crx 1
+ bfd_arch_cris, /* Axis CRIS */
+#define bfd_mach_cris_v0_v10 255
+#define bfd_mach_cris_v32 32
+#define bfd_mach_cris_v10_v32 1032
+ bfd_arch_s390, /* IBM s390 */
+#define bfd_mach_s390_31 31
+#define bfd_mach_s390_64 64
+ bfd_arch_score, /* Sunplus score */
+#define bfd_mach_score3 3
+#define bfd_mach_score7 7
+ bfd_arch_openrisc, /* OpenRISC */
+ bfd_arch_mmix, /* Donald Knuth's educational processor. */
+ bfd_arch_xstormy16,
+#define bfd_mach_xstormy16 1
+ bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */
+#define bfd_mach_msp11 11
+#define bfd_mach_msp110 110
+#define bfd_mach_msp12 12
+#define bfd_mach_msp13 13
+#define bfd_mach_msp14 14
+#define bfd_mach_msp15 15
+#define bfd_mach_msp16 16
+#define bfd_mach_msp21 21
+#define bfd_mach_msp31 31
+#define bfd_mach_msp32 32
+#define bfd_mach_msp33 33
+#define bfd_mach_msp41 41
+#define bfd_mach_msp42 42
+#define bfd_mach_msp43 43
+#define bfd_mach_msp44 44
+ bfd_arch_xc16x, /* Infineon's XC16X Series. */
+#define bfd_mach_xc16x 1
+#define bfd_mach_xc16xl 2
+#define bfd_mach_xc16xs 3
+ bfd_arch_xtensa, /* Tensilica's Xtensa cores. */
+#define bfd_mach_xtensa 1
+ bfd_arch_maxq, /* Dallas MAXQ 10/20 */
+#define bfd_mach_maxq10 10
+#define bfd_mach_maxq20 20
+ bfd_arch_z80,
+#define bfd_mach_z80strict 1 /* No undocumented opcodes. */
+#define bfd_mach_z80 3 /* With ixl, ixh, iyl, and iyh. */
+#define bfd_mach_z80full 7 /* All undocumented instructions. */
+#define bfd_mach_r800 11 /* R800: successor with multiplication. */
+ bfd_arch_lm32, /* Lattice Mico32 */
+#define bfd_mach_lm32 1
+ bfd_arch_microblaze,/* Xilinx MicroBlaze. */
+ bfd_arch_last
+ @};
+@end example
+
+@subsection bfd_arch_info
+
+
+@strong{Description}@*
+This structure contains information on architectures for use
+within BFD.
+@example
+
+typedef struct bfd_arch_info
+@{
+ int bits_per_word;
+ int bits_per_address;
+ int bits_per_byte;
+ enum bfd_architecture arch;
+ unsigned long mach;
+ const char *arch_name;
+ const char *printable_name;
+ unsigned int section_align_power;
+ /* TRUE if this is the default machine for the architecture.
+ The default arch should be the first entry for an arch so that
+ all the entries for that arch can be accessed via @code{next}. */
+ bfd_boolean the_default;
+ const struct bfd_arch_info * (*compatible)
+ (const struct bfd_arch_info *a, const struct bfd_arch_info *b);
+
+ bfd_boolean (*scan) (const struct bfd_arch_info *, const char *);
+
+ const struct bfd_arch_info *next;
+@}
+bfd_arch_info_type;
+
+@end example
+
+@findex bfd_printable_name
+@subsubsection @code{bfd_printable_name}
+@strong{Synopsis}
+@example
+const char *bfd_printable_name (bfd *abfd);
+@end example
+@strong{Description}@*
+Return a printable string representing the architecture and machine
+from the pointer to the architecture info structure.
+
+@findex bfd_scan_arch
+@subsubsection @code{bfd_scan_arch}
+@strong{Synopsis}
+@example
+const bfd_arch_info_type *bfd_scan_arch (const char *string);
+@end example
+@strong{Description}@*
+Figure out if BFD supports any cpu which could be described with
+the name @var{string}. Return a pointer to an @code{arch_info}
+structure if a machine is found, otherwise NULL.
+
+@findex bfd_arch_list
+@subsubsection @code{bfd_arch_list}
+@strong{Synopsis}
+@example
+const char **bfd_arch_list (void);
+@end example
+@strong{Description}@*
+Return a freshly malloced NULL-terminated vector of the names
+of all the valid BFD architectures. Do not modify the names.
+
+@findex bfd_arch_get_compatible
+@subsubsection @code{bfd_arch_get_compatible}
+@strong{Synopsis}
+@example
+const bfd_arch_info_type *bfd_arch_get_compatible
+ (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns);
+@end example
+@strong{Description}@*
+Determine whether two BFDs' architectures and machine types
+are compatible. Calculates the lowest common denominator
+between the two architectures and machine types implied by
+the BFDs and returns a pointer to an @code{arch_info} structure
+describing the compatible machine.
+
+@findex bfd_default_arch_struct
+@subsubsection @code{bfd_default_arch_struct}
+@strong{Description}@*
+The @code{bfd_default_arch_struct} is an item of
+@code{bfd_arch_info_type} which has been initialized to a fairly
+generic state. A BFD starts life by pointing to this
+structure, until the correct back end has determined the real
+architecture of the file.
+@example
+extern const bfd_arch_info_type bfd_default_arch_struct;
+@end example
+
+@findex bfd_set_arch_info
+@subsubsection @code{bfd_set_arch_info}
+@strong{Synopsis}
+@example
+void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg);
+@end example
+@strong{Description}@*
+Set the architecture info of @var{abfd} to @var{arg}.
+
+@findex bfd_default_set_arch_mach
+@subsubsection @code{bfd_default_set_arch_mach}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_default_set_arch_mach
+ (bfd *abfd, enum bfd_architecture arch, unsigned long mach);
+@end example
+@strong{Description}@*
+Set the architecture and machine type in BFD @var{abfd}
+to @var{arch} and @var{mach}. Find the correct
+pointer to a structure and insert it into the @code{arch_info}
+pointer.
+
+@findex bfd_get_arch
+@subsubsection @code{bfd_get_arch}
+@strong{Synopsis}
+@example
+enum bfd_architecture bfd_get_arch (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the enumerated type which describes the BFD @var{abfd}'s
+architecture.
+
+@findex bfd_get_mach
+@subsubsection @code{bfd_get_mach}
+@strong{Synopsis}
+@example
+unsigned long bfd_get_mach (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the long type which describes the BFD @var{abfd}'s
+machine.
+
+@findex bfd_arch_bits_per_byte
+@subsubsection @code{bfd_arch_bits_per_byte}
+@strong{Synopsis}
+@example
+unsigned int bfd_arch_bits_per_byte (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the number of bits in one of the BFD @var{abfd}'s
+architecture's bytes.
+
+@findex bfd_arch_bits_per_address
+@subsubsection @code{bfd_arch_bits_per_address}
+@strong{Synopsis}
+@example
+unsigned int bfd_arch_bits_per_address (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the number of bits in one of the BFD @var{abfd}'s
+architecture's addresses.
+
+@findex bfd_default_compatible
+@subsubsection @code{bfd_default_compatible}
+@strong{Synopsis}
+@example
+const bfd_arch_info_type *bfd_default_compatible
+ (const bfd_arch_info_type *a, const bfd_arch_info_type *b);
+@end example
+@strong{Description}@*
+The default function for testing for compatibility.
+
+@findex bfd_default_scan
+@subsubsection @code{bfd_default_scan}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_default_scan
+ (const struct bfd_arch_info *info, const char *string);
+@end example
+@strong{Description}@*
+The default function for working out whether this is an
+architecture hit and a machine hit.
+
+@findex bfd_get_arch_info
+@subsubsection @code{bfd_get_arch_info}
+@strong{Synopsis}
+@example
+const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the architecture info struct in @var{abfd}.
+
+@findex bfd_lookup_arch
+@subsubsection @code{bfd_lookup_arch}
+@strong{Synopsis}
+@example
+const bfd_arch_info_type *bfd_lookup_arch
+ (enum bfd_architecture arch, unsigned long machine);
+@end example
+@strong{Description}@*
+Look for the architecture info structure which matches the
+arguments @var{arch} and @var{machine}. A machine of 0 matches the
+machine/architecture structure which marks itself as the
+default.
+
+@findex bfd_printable_arch_mach
+@subsubsection @code{bfd_printable_arch_mach}
+@strong{Synopsis}
+@example
+const char *bfd_printable_arch_mach
+ (enum bfd_architecture arch, unsigned long machine);
+@end example
+@strong{Description}@*
+Return a printable string representing the architecture and
+machine type.
+
+This routine is depreciated.
+
+@findex bfd_octets_per_byte
+@subsubsection @code{bfd_octets_per_byte}
+@strong{Synopsis}
+@example
+unsigned int bfd_octets_per_byte (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the number of octets (8-bit quantities) per target byte
+(minimum addressable unit). In most cases, this will be one, but some
+DSP targets have 16, 32, or even 48 bits per byte.
+
+@findex bfd_arch_mach_octets_per_byte
+@subsubsection @code{bfd_arch_mach_octets_per_byte}
+@strong{Synopsis}
+@example
+unsigned int bfd_arch_mach_octets_per_byte
+ (enum bfd_architecture arch, unsigned long machine);
+@end example
+@strong{Description}@*
+See bfd_octets_per_byte.
+
+This routine is provided for those cases where a bfd * is not
+available
+
diff --git a/bfd/doc/bfd.info b/bfd/doc/bfd.info
new file mode 100644
index 00000000000..576f2c58b5e
--- /dev/null
+++ b/bfd/doc/bfd.info
@@ -0,0 +1,11288 @@
+This is bfd.info, produced by makeinfo version 4.8 from bfd.texinfo.
+
+START-INFO-DIR-ENTRY
+* Bfd: (bfd). The Binary File Descriptor library.
+END-INFO-DIR-ENTRY
+
+ This file documents the BFD library.
+
+ Copyright (C) 1991, 2000, 2001, 2003, 2006, 2007, 2008 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License" and "Funding Free
+Software", the Front-Cover texts being (a) (see below), and with the
+Back-Cover Texts being (b) (see below). A copy of the license is
+included in the section entitled "GNU Free Documentation License".
+
+ (a) The FSF's Front-Cover Text is:
+
+ A GNU Manual
+
+ (b) The FSF's Back-Cover Text is:
+
+ You have freedom to copy and modify this GNU Manual, like GNU
+software. Copies published by the Free Software Foundation raise
+funds for GNU development.
+
+
+File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
+
+ This file documents the binary file descriptor library libbfd.
+
+* Menu:
+
+* Overview:: Overview of BFD
+* BFD front end:: BFD front end
+* BFD back ends:: BFD back ends
+* GNU Free Documentation License:: GNU Free Documentation License
+* BFD Index:: BFD Index
+
+
+File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+BFD is a package which allows applications to use the same routines to
+operate on object files whatever the object file format. A new object
+file format can be supported simply by creating a new BFD back end and
+adding it to the library.
+
+ BFD is split into two parts: the front end, and the back ends (one
+for each object file format).
+ * The front end of BFD provides the interface to the user. It manages
+ memory and various canonical data structures. The front end also
+ decides which back end to use and when to call back end routines.
+
+ * The back ends provide BFD its view of the real world. Each back
+ end provides a set of calls which the BFD front end can use to
+ maintain its canonical form. The back ends also may keep around
+ information for their own use, for greater efficiency.
+
+* Menu:
+
+* History:: History
+* How It Works:: How It Works
+* What BFD Version 2 Can Do:: What BFD Version 2 Can Do
+
+
+File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview
+
+1.1 History
+===========
+
+One spur behind BFD was the desire, on the part of the GNU 960 team at
+Intel Oregon, for interoperability of applications on their COFF and
+b.out file formats. Cygnus was providing GNU support for the team, and
+was contracted to provide the required functionality.
+
+ The name came from a conversation David Wallace was having with
+Richard Stallman about the library: RMS said that it would be quite
+hard--David said "BFD". Stallman was right, but the name stuck.
+
+ At the same time, Ready Systems wanted much the same thing, but for
+different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
+coff.
+
+ BFD was first implemented by members of Cygnus Support; Steve
+Chamberlain (`sac@cygnus.com'), John Gilmore (`gnu@cygnus.com'), K.
+Richard Pixley (`rich@cygnus.com') and David Henkel-Wallace
+(`gumby@cygnus.com').
+
+
+File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview
+
+1.2 How To Use BFD
+==================
+
+To use the library, include `bfd.h' and link with `libbfd.a'.
+
+ BFD provides a common interface to the parts of an object file for a
+calling application.
+
+ When an application successfully opens a target file (object,
+archive, or whatever), a pointer to an internal structure is returned.
+This pointer points to a structure called `bfd', described in `bfd.h'.
+Our convention is to call this pointer a BFD, and instances of it
+within code `abfd'. All operations on the target object file are
+applied as methods to the BFD. The mapping is defined within `bfd.h'
+in a set of macros, all beginning with `bfd_' to reduce namespace
+pollution.
+
+ For example, this sequence does what you would probably expect:
+return the number of sections in an object file attached to a BFD
+`abfd'.
+
+ #include "bfd.h"
+
+ unsigned int number_of_sections (abfd)
+ bfd *abfd;
+ {
+ return bfd_count_sections (abfd);
+ }
+
+ The abstraction used within BFD is that an object file has:
+
+ * a header,
+
+ * a number of sections containing raw data (*note Sections::),
+
+ * a set of relocations (*note Relocations::), and
+
+ * some symbol information (*note Symbols::).
+ Also, BFDs opened for archives have the additional attribute of an
+index and contain subordinate BFDs. This approach is fine for a.out and
+coff, but loses efficiency when applied to formats such as S-records and
+IEEE-695.
+
+
+File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview
+
+1.3 What BFD Version 2 Can Do
+=============================
+
+When an object file is opened, BFD subroutines automatically determine
+the format of the input object file. They then build a descriptor in
+memory with pointers to routines that will be used to access elements of
+the object file's data structures.
+
+ As different information from the object files is required, BFD
+reads from different sections of the file and processes them. For
+example, a very common operation for the linker is processing symbol
+tables. Each BFD back end provides a routine for converting between
+the object file's representation of symbols and an internal canonical
+format. When the linker asks for the symbol table of an object file, it
+calls through a memory pointer to the routine from the relevant BFD
+back end which reads and converts the table into a canonical form. The
+linker then operates upon the canonical form. When the link is finished
+and the linker writes the output file's symbol table, another BFD back
+end routine is called to take the newly created symbol table and
+convert it into the chosen output format.
+
+* Menu:
+
+* BFD information loss:: Information Loss
+* Canonical format:: The BFD canonical object-file format
+
+
+File: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do
+
+1.3.1 Information Loss
+----------------------
+
+_Information can be lost during output._ The output formats supported
+by BFD do not provide identical facilities, and information which can
+be described in one form has nowhere to go in another format. One
+example of this is alignment information in `b.out'. There is nowhere
+in an `a.out' format file to store alignment information on the
+contained data, so when a file is linked from `b.out' and an `a.out'
+image is produced, alignment information will not propagate to the
+output file. (The linker will still use the alignment information
+internally, so the link is performed correctly).
+
+ Another example is COFF section names. COFF files may contain an
+unlimited number of sections, each one with a textual section name. If
+the target of the link is a format which does not have many sections
+(e.g., `a.out') or has sections without names (e.g., the Oasys format),
+the link cannot be done simply. You can circumvent this problem by
+describing the desired input-to-output section mapping with the linker
+command language.
+
+ _Information can be lost during canonicalization._ The BFD internal
+canonical form of the external formats is not exhaustive; there are
+structures in input formats for which there is no direct representation
+internally. This means that the BFD back ends cannot maintain all
+possible data richness through the transformation between external to
+internal and back to external formats.
+
+ This limitation is only a problem when an application reads one
+format and writes another. Each BFD back end is responsible for
+maintaining as much data as possible, and the internal BFD canonical
+form has structures which are opaque to the BFD core, and exported only
+to the back ends. When a file is read in one format, the canonical form
+is generated for BFD and the application. At the same time, the back
+end saves away any information which may otherwise be lost. If the data
+is then written back in the same format, the back end routine will be
+able to use the canonical form provided by the BFD core as well as the
+information it prepared earlier. Since there is a great deal of
+commonality between back ends, there is no information lost when
+linking or copying big endian COFF to little endian COFF, or `a.out' to
+`b.out'. When a mixture of formats is linked, the information is only
+lost from the files whose format differs from the destination.
+
+
+File: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do
+
+1.3.2 The BFD canonical object-file format
+------------------------------------------
+
+The greatest potential for loss of information occurs when there is the
+least overlap between the information provided by the source format,
+that stored by the canonical format, and that needed by the destination
+format. A brief description of the canonical form may help you
+understand which kinds of data you can count on preserving across
+conversions.
+
+_files_
+ Information stored on a per-file basis includes target machine
+ architecture, particular implementation format type, a demand
+ pageable bit, and a write protected bit. Information like Unix
+ magic numbers is not stored here--only the magic numbers' meaning,
+ so a `ZMAGIC' file would have both the demand pageable bit and the
+ write protected text bit set. The byte order of the target is
+ stored on a per-file basis, so that big- and little-endian object
+ files may be used with one another.
+
+_sections_
+ Each section in the input file contains the name of the section,
+ the section's original address in the object file, size and
+ alignment information, various flags, and pointers into other BFD
+ data structures.
+
+_symbols_
+ Each symbol contains a pointer to the information for the object
+ file which originally defined it, its name, its value, and various
+ flag bits. When a BFD back end reads in a symbol table, it
+ relocates all symbols to make them relative to the base of the
+ section where they were defined. Doing this ensures that each
+ symbol points to its containing section. Each symbol also has a
+ varying amount of hidden private data for the BFD back end. Since
+ the symbol points to the original file, the private data format
+ for that symbol is accessible. `ld' can operate on a collection
+ of symbols of wildly different formats without problems.
+
+ Normal global and simple local symbols are maintained on output,
+ so an output file (no matter its format) will retain symbols
+ pointing to functions and to global, static, and common variables.
+ Some symbol information is not worth retaining; in `a.out', type
+ information is stored in the symbol table as long symbol names.
+ This information would be useless to most COFF debuggers; the
+ linker has command line switches to allow users to throw it away.
+
+ There is one word of type information within the symbol, so if the
+ format supports symbol type information within symbols (for
+ example, COFF, IEEE, Oasys) and the type is simple enough to fit
+ within one word (nearly everything but aggregates), the
+ information will be preserved.
+
+_relocation level_
+ Each canonical BFD relocation record contains a pointer to the
+ symbol to relocate to, the offset of the data to relocate, the
+ section the data is in, and a pointer to a relocation type
+ descriptor. Relocation is performed by passing messages through
+ the relocation type descriptor and the symbol pointer. Therefore,
+ relocations can be performed on output data using a relocation
+ method that is only available in one of the input formats. For
+ instance, Oasys provides a byte relocation format. A relocation
+ record requesting this relocation type would point indirectly to a
+ routine to perform this, so the relocation may be performed on a
+ byte being written to a 68k COFF file, even though 68k COFF has no
+ such relocation type.
+
+_line numbers_
+ Object formats can contain, for debugging purposes, some form of
+ mapping between symbols, source line numbers, and addresses in the
+ output file. These addresses have to be relocated along with the
+ symbol information. Each symbol with an associated list of line
+ number records points to the first record of the list. The head
+ of a line number list consists of a pointer to the symbol, which
+ allows finding out the address of the function whose line number
+ is being described. The rest of the list is made up of pairs:
+ offsets into the section and line numbers. Any format which can
+ simply derive this information can pass it successfully between
+ formats (COFF, IEEE and Oasys).
+
+
+File: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top
+
+2 BFD Front End
+***************
+
+2.1 `typedef bfd'
+=================
+
+A BFD has type `bfd'; objects of this type are the cornerstone of any
+application using BFD. Using BFD consists of making references though
+the BFD and to data in the BFD.
+
+ Here is the structure that defines the type `bfd'. It contains the
+major data about the file and pointers to the rest of the data.
+
+
+ enum bfd_direction
+ {
+ no_direction = 0,
+ read_direction = 1,
+ write_direction = 2,
+ both_direction = 3
+ };
+
+ struct bfd
+ {
+ /* A unique identifier of the BFD */
+ unsigned int id;
+
+ /* The filename the application opened the BFD with. */
+ const char *filename;
+
+ /* A pointer to the target jump table. */
+ const struct bfd_target *xvec;
+
+ /* The IOSTREAM, and corresponding IO vector that provide access
+ to the file backing the BFD. */
+ void *iostream;
+ const struct bfd_iovec *iovec;
+
+ /* The caching routines use these to maintain a
+ least-recently-used list of BFDs. */
+ struct bfd *lru_prev, *lru_next;
+
+ /* When a file is closed by the caching routines, BFD retains
+ state information on the file here... */
+ ufile_ptr where;
+
+ /* File modified time, if mtime_set is TRUE. */
+ long mtime;
+
+ /* Reserved for an unimplemented file locking extension. */
+ int ifd;
+
+ /* The format which belongs to the BFD. (object, core, etc.) */
+ bfd_format format;
+
+ /* The direction with which the BFD was opened. */
+ enum bfd_direction direction;
+
+ /* Format_specific flags. */
+ flagword flags;
+
+ /* Values that may appear in the flags field of a BFD. These also
+ appear in the object_flags field of the bfd_target structure, where
+ they indicate the set of flags used by that backend (not all flags
+ are meaningful for all object file formats) (FIXME: at the moment,
+ the object_flags values have mostly just been copied from backend
+ to another, and are not necessarily correct). */
+
+ #define BFD_NO_FLAGS 0x00
+
+ /* BFD contains relocation entries. */
+ #define HAS_RELOC 0x01
+
+ /* BFD is directly executable. */
+ #define EXEC_P 0x02
+
+ /* BFD has line number information (basically used for F_LNNO in a
+ COFF header). */
+ #define HAS_LINENO 0x04
+
+ /* BFD has debugging information. */
+ #define HAS_DEBUG 0x08
+
+ /* BFD has symbols. */
+ #define HAS_SYMS 0x10
+
+ /* BFD has local symbols (basically used for F_LSYMS in a COFF
+ header). */
+ #define HAS_LOCALS 0x20
+
+ /* BFD is a dynamic object. */
+ #define DYNAMIC 0x40
+
+ /* Text section is write protected (if D_PAGED is not set, this is
+ like an a.out NMAGIC file) (the linker sets this by default, but
+ clears it for -r or -N). */
+ #define WP_TEXT 0x80
+
+ /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the
+ linker sets this by default, but clears it for -r or -n or -N). */
+ #define D_PAGED 0x100
+
+ /* BFD is relaxable (this means that bfd_relax_section may be able to
+ do something) (sometimes bfd_relax_section can do something even if
+ this is not set). */
+ #define BFD_IS_RELAXABLE 0x200
+
+ /* This may be set before writing out a BFD to request using a
+ traditional format. For example, this is used to request that when
+ writing out an a.out object the symbols not be hashed to eliminate
+ duplicates. */
+ #define BFD_TRADITIONAL_FORMAT 0x400
+
+ /* This flag indicates that the BFD contents are actually cached
+ in memory. If this is set, iostream points to a bfd_in_memory
+ struct. */
+ #define BFD_IN_MEMORY 0x800
+
+ /* The sections in this BFD specify a memory page. */
+ #define HAS_LOAD_PAGE 0x1000
+
+ /* This BFD has been created by the linker and doesn't correspond
+ to any input file. */
+ #define BFD_LINKER_CREATED 0x2000
+
+ /* This may be set before writing out a BFD to request that it
+ be written using values for UIDs, GIDs, timestamps, etc. that
+ will be consistent from run to run. */
+ #define BFD_DETERMINISTIC_OUTPUT 0x4000
+
+ /* Currently my_archive is tested before adding origin to
+ anything. I believe that this can become always an add of
+ origin, with origin set to 0 for non archive files. */
+ ufile_ptr origin;
+
+ /* The origin in the archive of the proxy entry. This will
+ normally be the same as origin, except for thin archives,
+ when it will contain the current offset of the proxy in the
+ thin archive rather than the offset of the bfd in its actual
+ container. */
+ ufile_ptr proxy_origin;
+
+ /* A hash table for section names. */
+ struct bfd_hash_table section_htab;
+
+ /* Pointer to linked list of sections. */
+ struct bfd_section *sections;
+
+ /* The last section on the section list. */
+ struct bfd_section *section_last;
+
+ /* The number of sections. */
+ unsigned int section_count;
+
+ /* Stuff only useful for object files:
+ The start address. */
+ bfd_vma start_address;
+
+ /* Used for input and output. */
+ unsigned int symcount;
+
+ /* Symbol table for output BFD (with symcount entries).
+ Also used by the linker to cache input BFD symbols. */
+ struct bfd_symbol **outsymbols;
+
+ /* Used for slurped dynamic symbol tables. */
+ unsigned int dynsymcount;
+
+ /* Pointer to structure which contains architecture information. */
+ const struct bfd_arch_info *arch_info;
+
+ /* Stuff only useful for archives. */
+ void *arelt_data;
+ struct bfd *my_archive; /* The containing archive BFD. */
+ struct bfd *archive_next; /* The next BFD in the archive. */
+ struct bfd *archive_head; /* The first BFD in the archive. */
+ struct bfd *nested_archives; /* List of nested archive in a flattened
+ thin archive. */
+
+ /* A chain of BFD structures involved in a link. */
+ struct bfd *link_next;
+
+ /* A field used by _bfd_generic_link_add_archive_symbols. This will
+ be used only for archive elements. */
+ int archive_pass;
+
+ /* Used by the back end to hold private data. */
+ union
+ {
+ struct aout_data_struct *aout_data;
+ struct artdata *aout_ar_data;
+ struct _oasys_data *oasys_obj_data;
+ struct _oasys_ar_data *oasys_ar_data;
+ struct coff_tdata *coff_obj_data;
+ struct pe_tdata *pe_obj_data;
+ struct xcoff_tdata *xcoff_obj_data;
+ struct ecoff_tdata *ecoff_obj_data;
+ struct ieee_data_struct *ieee_data;
+ struct ieee_ar_data_struct *ieee_ar_data;
+ struct srec_data_struct *srec_data;
+ struct verilog_data_struct *verilog_data;
+ struct ihex_data_struct *ihex_data;
+ struct tekhex_data_struct *tekhex_data;
+ struct elf_obj_tdata *elf_obj_data;
+ struct nlm_obj_tdata *nlm_obj_data;
+ struct bout_data_struct *bout_data;
+ struct mmo_data_struct *mmo_data;
+ struct sun_core_struct *sun_core_data;
+ struct sco5_core_struct *sco5_core_data;
+ struct trad_core_struct *trad_core_data;
+ struct som_data_struct *som_data;
+ struct hpux_core_struct *hpux_core_data;
+ struct hppabsd_core_struct *hppabsd_core_data;
+ struct sgi_core_struct *sgi_core_data;
+ struct lynx_core_struct *lynx_core_data;
+ struct osf_core_struct *osf_core_data;
+ struct cisco_core_struct *cisco_core_data;
+ struct versados_data_struct *versados_data;
+ struct netbsd_core_struct *netbsd_core_data;
+ struct mach_o_data_struct *mach_o_data;
+ struct mach_o_fat_data_struct *mach_o_fat_data;
+ struct plugin_data_struct *plugin_data;
+ struct bfd_pef_data_struct *pef_data;
+ struct bfd_pef_xlib_data_struct *pef_xlib_data;
+ struct bfd_sym_data_struct *sym_data;
+ void *any;
+ }
+ tdata;
+
+ /* Used by the application to hold private data. */
+ void *usrdata;
+
+ /* Where all the allocated stuff under this BFD goes. This is a
+ struct objalloc *, but we use void * to avoid requiring the inclusion
+ of objalloc.h. */
+ void *memory;
+
+ /* Is the file descriptor being cached? That is, can it be closed as
+ needed, and re-opened when accessed later? */
+ unsigned int cacheable : 1;
+
+ /* Marks whether there was a default target specified when the
+ BFD was opened. This is used to select which matching algorithm
+ to use to choose the back end. */
+ unsigned int target_defaulted : 1;
+
+ /* ... and here: (``once'' means at least once). */
+ unsigned int opened_once : 1;
+
+ /* Set if we have a locally maintained mtime value, rather than
+ getting it from the file each time. */
+ unsigned int mtime_set : 1;
+
+ /* Flag set if symbols from this BFD should not be exported. */
+ unsigned int no_export : 1;
+
+ /* Remember when output has begun, to stop strange things
+ from happening. */
+ unsigned int output_has_begun : 1;
+
+ /* Have archive map. */
+ unsigned int has_armap : 1;
+
+ /* Set if this is a thin archive. */
+ unsigned int is_thin_archive : 1;
+ };
+
+2.2 Error reporting
+===================
+
+Most BFD functions return nonzero on success (check their individual
+documentation for precise semantics). On an error, they call
+`bfd_set_error' to set an error condition that callers can check by
+calling `bfd_get_error'. If that returns `bfd_error_system_call', then
+check `errno'.
+
+ The easiest way to report a BFD error to the user is to use
+`bfd_perror'.
+
+2.2.1 Type `bfd_error_type'
+---------------------------
+
+The values returned by `bfd_get_error' are defined by the enumerated
+type `bfd_error_type'.
+
+
+ typedef enum bfd_error
+ {
+ bfd_error_no_error = 0,
+ bfd_error_system_call,
+ bfd_error_invalid_target,
+ bfd_error_wrong_format,
+ bfd_error_wrong_object_format,
+ bfd_error_invalid_operation,
+ bfd_error_no_memory,
+ bfd_error_no_symbols,
+ bfd_error_no_armap,
+ bfd_error_no_more_archived_files,
+ bfd_error_malformed_archive,
+ bfd_error_file_not_recognized,
+ bfd_error_file_ambiguously_recognized,
+ bfd_error_no_contents,
+ bfd_error_nonrepresentable_section,
+ bfd_error_no_debug_section,
+ bfd_error_bad_value,
+ bfd_error_file_truncated,
+ bfd_error_file_too_big,
+ bfd_error_on_input,
+ bfd_error_invalid_error_code
+ }
+ bfd_error_type;
+
+2.2.1.1 `bfd_get_error'
+.......................
+
+*Synopsis*
+ bfd_error_type bfd_get_error (void);
+ *Description*
+Return the current BFD error condition.
+
+2.2.1.2 `bfd_set_error'
+.......................
+
+*Synopsis*
+ void bfd_set_error (bfd_error_type error_tag, ...);
+ *Description*
+Set the BFD error condition to be ERROR_TAG. If ERROR_TAG is
+bfd_error_on_input, then this function takes two more parameters, the
+input bfd where the error occurred, and the bfd_error_type error.
+
+2.2.1.3 `bfd_errmsg'
+....................
+
+*Synopsis*
+ const char *bfd_errmsg (bfd_error_type error_tag);
+ *Description*
+Return a string describing the error ERROR_TAG, or the system error if
+ERROR_TAG is `bfd_error_system_call'.
+
+2.2.1.4 `bfd_perror'
+....................
+
+*Synopsis*
+ void bfd_perror (const char *message);
+ *Description*
+Print to the standard error stream a string describing the last BFD
+error that occurred, or the last system error if the last BFD error was
+a system call failure. If MESSAGE is non-NULL and non-empty, the error
+string printed is preceded by MESSAGE, a colon, and a space. It is
+followed by a newline.
+
+2.2.2 BFD error handler
+-----------------------
+
+Some BFD functions want to print messages describing the problem. They
+call a BFD error handler function. This function may be overridden by
+the program.
+
+ The BFD error handler acts like printf.
+
+
+ typedef void (*bfd_error_handler_type) (const char *, ...);
+
+2.2.2.1 `bfd_set_error_handler'
+...............................
+
+*Synopsis*
+ bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
+ *Description*
+Set the BFD error handler function. Returns the previous function.
+
+2.2.2.2 `bfd_set_error_program_name'
+....................................
+
+*Synopsis*
+ void bfd_set_error_program_name (const char *);
+ *Description*
+Set the program name to use when printing a BFD error. This is printed
+before the error message followed by a colon and space. The string
+must not be changed after it is passed to this function.
+
+2.2.2.3 `bfd_get_error_handler'
+...............................
+
+*Synopsis*
+ bfd_error_handler_type bfd_get_error_handler (void);
+ *Description*
+Return the BFD error handler function.
+
+2.3 Miscellaneous
+=================
+
+2.3.1 Miscellaneous functions
+-----------------------------
+
+2.3.1.1 `bfd_get_reloc_upper_bound'
+...................................
+
+*Synopsis*
+ long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
+ *Description*
+Return the number of bytes required to store the relocation information
+associated with section SECT attached to bfd ABFD. If an error occurs,
+return -1.
+
+2.3.1.2 `bfd_canonicalize_reloc'
+................................
+
+*Synopsis*
+ long bfd_canonicalize_reloc
+ (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
+ *Description*
+Call the back end associated with the open BFD ABFD and translate the
+external form of the relocation information attached to SEC into the
+internal canonical form. Place the table into memory at LOC, which has
+been preallocated, usually by a call to `bfd_get_reloc_upper_bound'.
+Returns the number of relocs, or -1 on error.
+
+ The SYMS table is also needed for horrible internal magic reasons.
+
+2.3.1.3 `bfd_set_reloc'
+.......................
+
+*Synopsis*
+ void bfd_set_reloc
+ (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
+ *Description*
+Set the relocation pointer and count within section SEC to the values
+REL and COUNT. The argument ABFD is ignored.
+
+2.3.1.4 `bfd_set_file_flags'
+............................
+
+*Synopsis*
+ bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
+ *Description*
+Set the flag word in the BFD ABFD to the value FLAGS.
+
+ Possible errors are:
+ * `bfd_error_wrong_format' - The target bfd was not of object format.
+
+ * `bfd_error_invalid_operation' - The target bfd was open for
+ reading.
+
+ * `bfd_error_invalid_operation' - The flag word contained a bit
+ which was not applicable to the type of file. E.g., an attempt
+ was made to set the `D_PAGED' bit on a BFD format which does not
+ support demand paging.
+
+2.3.1.5 `bfd_get_arch_size'
+...........................
+
+*Synopsis*
+ int bfd_get_arch_size (bfd *abfd);
+ *Description*
+Returns the architecture address size, in bits, as determined by the
+object file's format. For ELF, this information is included in the
+header.
+
+ *Returns*
+Returns the arch size in bits if known, `-1' otherwise.
+
+2.3.1.6 `bfd_get_sign_extend_vma'
+.................................
+
+*Synopsis*
+ int bfd_get_sign_extend_vma (bfd *abfd);
+ *Description*
+Indicates if the target architecture "naturally" sign extends an
+address. Some architectures implicitly sign extend address values when
+they are converted to types larger than the size of an address. For
+instance, bfd_get_start_address() will return an address sign extended
+to fill a bfd_vma when this is the case.
+
+ *Returns*
+Returns `1' if the target architecture is known to sign extend
+addresses, `0' if the target architecture is known to not sign extend
+addresses, and `-1' otherwise.
+
+2.3.1.7 `bfd_set_start_address'
+...............................
+
+*Synopsis*
+ bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
+ *Description*
+Make VMA the entry point of output BFD ABFD.
+
+ *Returns*
+Returns `TRUE' on success, `FALSE' otherwise.
+
+2.3.1.8 `bfd_get_gp_size'
+.........................
+
+*Synopsis*
+ unsigned int bfd_get_gp_size (bfd *abfd);
+ *Description*
+Return the maximum size of objects to be optimized using the GP
+register under MIPS ECOFF. This is typically set by the `-G' argument
+to the compiler, assembler or linker.
+
+2.3.1.9 `bfd_set_gp_size'
+.........................
+
+*Synopsis*
+ void bfd_set_gp_size (bfd *abfd, unsigned int i);
+ *Description*
+Set the maximum size of objects to be optimized using the GP register
+under ECOFF or MIPS ELF. This is typically set by the `-G' argument to
+the compiler, assembler or linker.
+
+2.3.1.10 `bfd_scan_vma'
+.......................
+
+*Synopsis*
+ bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
+ *Description*
+Convert, like `strtoul', a numerical expression STRING into a `bfd_vma'
+integer, and return that integer. (Though without as many bells and
+whistles as `strtoul'.) The expression is assumed to be unsigned
+(i.e., positive). If given a BASE, it is used as the base for
+conversion. A base of 0 causes the function to interpret the string in
+hex if a leading "0x" or "0X" is found, otherwise in octal if a leading
+zero is found, otherwise in decimal.
+
+ If the value would overflow, the maximum `bfd_vma' value is returned.
+
+2.3.1.11 `bfd_copy_private_header_data'
+.......................................
+
+*Synopsis*
+ bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
+ *Description*
+Copy private BFD header information from the BFD IBFD to the the BFD
+OBFD. This copies information that may require sections to exist, but
+does not require symbol tables. Return `true' on success, `false' on
+error. Possible error returns are:
+
+ * `bfd_error_no_memory' - Not enough memory exists to create private
+ data for OBFD.
+
+ #define bfd_copy_private_header_data(ibfd, obfd) \
+ BFD_SEND (obfd, _bfd_copy_private_header_data, \
+ (ibfd, obfd))
+
+2.3.1.12 `bfd_copy_private_bfd_data'
+....................................
+
+*Synopsis*
+ bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
+ *Description*
+Copy private BFD information from the BFD IBFD to the the BFD OBFD.
+Return `TRUE' on success, `FALSE' on error. Possible error returns are:
+
+ * `bfd_error_no_memory' - Not enough memory exists to create private
+ data for OBFD.
+
+ #define bfd_copy_private_bfd_data(ibfd, obfd) \
+ BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
+ (ibfd, obfd))
+
+2.3.1.13 `bfd_merge_private_bfd_data'
+.....................................
+
+*Synopsis*
+ bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
+ *Description*
+Merge private BFD information from the BFD IBFD to the the output file
+BFD OBFD when linking. Return `TRUE' on success, `FALSE' on error.
+Possible error returns are:
+
+ * `bfd_error_no_memory' - Not enough memory exists to create private
+ data for OBFD.
+
+ #define bfd_merge_private_bfd_data(ibfd, obfd) \
+ BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
+ (ibfd, obfd))
+
+2.3.1.14 `bfd_set_private_flags'
+................................
+
+*Synopsis*
+ bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
+ *Description*
+Set private BFD flag information in the BFD ABFD. Return `TRUE' on
+success, `FALSE' on error. Possible error returns are:
+
+ * `bfd_error_no_memory' - Not enough memory exists to create private
+ data for OBFD.
+
+ #define bfd_set_private_flags(abfd, flags) \
+ BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
+
+2.3.1.15 `Other functions'
+..........................
+
+*Description*
+The following functions exist but have not yet been documented.
+ #define bfd_sizeof_headers(abfd, info) \
+ BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info))
+
+ #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
+ BFD_SEND (abfd, _bfd_find_nearest_line, \
+ (abfd, sec, syms, off, file, func, line))
+
+ #define bfd_find_line(abfd, syms, sym, file, line) \
+ BFD_SEND (abfd, _bfd_find_line, \
+ (abfd, syms, sym, file, line))
+
+ #define bfd_find_inliner_info(abfd, file, func, line) \
+ BFD_SEND (abfd, _bfd_find_inliner_info, \
+ (abfd, file, func, line))
+
+ #define bfd_debug_info_start(abfd) \
+ BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
+
+ #define bfd_debug_info_end(abfd) \
+ BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
+
+ #define bfd_debug_info_accumulate(abfd, section) \
+ BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
+
+ #define bfd_stat_arch_elt(abfd, stat) \
+ BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
+
+ #define bfd_update_armap_timestamp(abfd) \
+ BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
+
+ #define bfd_set_arch_mach(abfd, arch, mach)\
+ BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
+
+ #define bfd_relax_section(abfd, section, link_info, again) \
+ BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
+
+ #define bfd_gc_sections(abfd, link_info) \
+ BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
+
+ #define bfd_merge_sections(abfd, link_info) \
+ BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
+
+ #define bfd_is_group_section(abfd, sec) \
+ BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
+
+ #define bfd_discard_group(abfd, sec) \
+ BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
+
+ #define bfd_link_hash_table_create(abfd) \
+ BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
+
+ #define bfd_link_hash_table_free(abfd, hash) \
+ BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
+
+ #define bfd_link_add_symbols(abfd, info) \
+ BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
+
+ #define bfd_link_just_syms(abfd, sec, info) \
+ BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
+
+ #define bfd_final_link(abfd, info) \
+ BFD_SEND (abfd, _bfd_final_link, (abfd, info))
+
+ #define bfd_free_cached_info(abfd) \
+ BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
+
+ #define bfd_get_dynamic_symtab_upper_bound(abfd) \
+ BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
+
+ #define bfd_print_private_bfd_data(abfd, file)\
+ BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
+
+ #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
+ BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
+
+ #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
+ BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
+ dyncount, dynsyms, ret))
+
+ #define bfd_get_dynamic_reloc_upper_bound(abfd) \
+ BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
+
+ #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
+ BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
+
+ extern bfd_byte *bfd_get_relocated_section_contents
+ (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
+ bfd_boolean, asymbol **);
+
+2.3.1.16 `bfd_alt_mach_code'
+............................
+
+*Synopsis*
+ bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
+ *Description*
+When more than one machine code number is available for the same
+machine type, this function can be used to switch between the preferred
+one (alternative == 0) and any others. Currently, only ELF supports
+this feature, with up to two alternate machine codes.
+
+ struct bfd_preserve
+ {
+ void *marker;
+ void *tdata;
+ flagword flags;
+ const struct bfd_arch_info *arch_info;
+ struct bfd_section *sections;
+ struct bfd_section *section_last;
+ unsigned int section_count;
+ struct bfd_hash_table section_htab;
+ };
+
+2.3.1.17 `bfd_preserve_save'
+............................
+
+*Synopsis*
+ bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
+ *Description*
+When testing an object for compatibility with a particular target
+back-end, the back-end object_p function needs to set up certain fields
+in the bfd on successfully recognizing the object. This typically
+happens in a piecemeal fashion, with failures possible at many points.
+On failure, the bfd is supposed to be restored to its initial state,
+which is virtually impossible. However, restoring a subset of the bfd
+state works in practice. This function stores the subset and
+reinitializes the bfd.
+
+2.3.1.18 `bfd_preserve_restore'
+...............................
+
+*Synopsis*
+ void bfd_preserve_restore (bfd *, struct bfd_preserve *);
+ *Description*
+This function restores bfd state saved by bfd_preserve_save. If MARKER
+is non-NULL in struct bfd_preserve then that block and all subsequently
+bfd_alloc'd memory is freed.
+
+2.3.1.19 `bfd_preserve_finish'
+..............................
+
+*Synopsis*
+ void bfd_preserve_finish (bfd *, struct bfd_preserve *);
+ *Description*
+This function should be called when the bfd state saved by
+bfd_preserve_save is no longer needed. ie. when the back-end object_p
+function returns with success.
+
+2.3.1.20 `bfd_emul_get_maxpagesize'
+...................................
+
+*Synopsis*
+ bfd_vma bfd_emul_get_maxpagesize (const char *);
+ *Description*
+Returns the maximum page size, in bytes, as determined by emulation.
+
+ *Returns*
+Returns the maximum page size in bytes for ELF, 0 otherwise.
+
+2.3.1.21 `bfd_emul_set_maxpagesize'
+...................................
+
+*Synopsis*
+ void bfd_emul_set_maxpagesize (const char *, bfd_vma);
+ *Description*
+For ELF, set the maximum page size for the emulation. It is a no-op
+for other formats.
+
+2.3.1.22 `bfd_emul_get_commonpagesize'
+......................................
+
+*Synopsis*
+ bfd_vma bfd_emul_get_commonpagesize (const char *);
+ *Description*
+Returns the common page size, in bytes, as determined by emulation.
+
+ *Returns*
+Returns the common page size in bytes for ELF, 0 otherwise.
+
+2.3.1.23 `bfd_emul_set_commonpagesize'
+......................................
+
+*Synopsis*
+ void bfd_emul_set_commonpagesize (const char *, bfd_vma);
+ *Description*
+For ELF, set the common page size for the emulation. It is a no-op for
+other formats.
+
+2.3.1.24 `bfd_demangle'
+.......................
+
+*Synopsis*
+ char *bfd_demangle (bfd *, const char *, int);
+ *Description*
+Wrapper around cplus_demangle. Strips leading underscores and other
+such chars that would otherwise confuse the demangler. If passed a g++
+v3 ABI mangled name, returns a buffer allocated with malloc holding the
+demangled name. Returns NULL otherwise and on memory alloc failure.
+
+2.3.1.25 `struct bfd_iovec'
+...........................
+
+*Description*
+The `struct bfd_iovec' contains the internal file I/O class. Each
+`BFD' has an instance of this class and all file I/O is routed through
+it (it is assumed that the instance implements all methods listed
+below).
+ struct bfd_iovec
+ {
+ /* To avoid problems with macros, a "b" rather than "f"
+ prefix is prepended to each method name. */
+ /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching
+ bytes starting at PTR. Return the number of bytes actually
+ transfered (a read past end-of-file returns less than NBYTES),
+ or -1 (setting `bfd_error') if an error occurs. */
+ file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes);
+ file_ptr (*bwrite) (struct bfd *abfd, const void *ptr,
+ file_ptr nbytes);
+ /* Return the current IOSTREAM file offset, or -1 (setting `bfd_error'
+ if an error occurs. */
+ file_ptr (*btell) (struct bfd *abfd);
+ /* For the following, on successful completion a value of 0 is returned.
+ Otherwise, a value of -1 is returned (and `bfd_error' is set). */
+ int (*bseek) (struct bfd *abfd, file_ptr offset, int whence);
+ int (*bclose) (struct bfd *abfd);
+ int (*bflush) (struct bfd *abfd);
+ int (*bstat) (struct bfd *abfd, struct stat *sb);
+ /* Just like mmap: (void*)-1 on failure, mmapped address on success. */
+ void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len,
+ int prot, int flags, file_ptr offset);
+ };
+
+2.3.1.26 `bfd_get_mtime'
+........................
+
+*Synopsis*
+ long bfd_get_mtime (bfd *abfd);
+ *Description*
+Return the file modification time (as read from the file system, or
+from the archive header for archive members).
+
+2.3.1.27 `bfd_get_size'
+.......................
+
+*Synopsis*
+ file_ptr bfd_get_size (bfd *abfd);
+ *Description*
+Return the file size (as read from file system) for the file associated
+with BFD ABFD.
+
+ The initial motivation for, and use of, this routine is not so we
+can get the exact size of the object the BFD applies to, since that
+might not be generally possible (archive members for example). It
+would be ideal if someone could eventually modify it so that such
+results were guaranteed.
+
+ Instead, we want to ask questions like "is this NNN byte sized
+object I'm about to try read from file offset YYY reasonable?" As as
+example of where we might do this, some object formats use string
+tables for which the first `sizeof (long)' bytes of the table contain
+the size of the table itself, including the size bytes. If an
+application tries to read what it thinks is one of these string tables,
+without some way to validate the size, and for some reason the size is
+wrong (byte swapping error, wrong location for the string table, etc.),
+the only clue is likely to be a read error when it tries to read the
+table, or a "virtual memory exhausted" error when it tries to allocate
+15 bazillon bytes of space for the 15 bazillon byte table it is about
+to read. This function at least allows us to answer the question, "is
+the size reasonable?".
+
+2.3.1.28 `bfd_mmap'
+...................
+
+*Synopsis*
+ void *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len,
+ int prot, int flags, file_ptr offset);
+ *Description*
+Return mmap()ed region of the file, if possible and implemented.
+
+* Menu:
+
+* Memory Usage::
+* Initialization::
+* Sections::
+* Symbols::
+* Archives::
+* Formats::
+* Relocations::
+* Core Files::
+* Targets::
+* Architectures::
+* Opening and Closing::
+* Internal::
+* File Caching::
+* Linker Functions::
+* Hash Tables::
+
+
+File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: BFD front end, Up: BFD front end
+
+2.4 Memory Usage
+================
+
+BFD keeps all of its internal structures in obstacks. There is one
+obstack per open BFD file, into which the current state is stored. When
+a BFD is closed, the obstack is deleted, and so everything which has
+been allocated by BFD for the closing file is thrown away.
+
+ BFD does not free anything created by an application, but pointers
+into `bfd' structures become invalid on a `bfd_close'; for example,
+after a `bfd_close' the vector passed to `bfd_canonicalize_symtab' is
+still around, since it has been allocated by the application, but the
+data that it pointed to are lost.
+
+ The general rule is to not close a BFD until all operations dependent
+upon data from the BFD have been completed, or all the data from within
+the file has been copied. To help with the management of memory, there
+is a function (`bfd_alloc_size') which returns the number of bytes in
+obstacks associated with the supplied BFD. This could be used to select
+the greediest open BFD, close it to reclaim the memory, perform some
+operation and reopen the BFD again, to get a fresh copy of the data
+structures.
+
+
+File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end
+
+2.5 Initialization
+==================
+
+2.5.1 Initialization functions
+------------------------------
+
+These are the functions that handle initializing a BFD.
+
+2.5.1.1 `bfd_init'
+..................
+
+*Synopsis*
+ void bfd_init (void);
+ *Description*
+This routine must be called before any other BFD function to initialize
+magical internal data structures.
+
+
+File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end
+
+2.6 Sections
+============
+
+The raw data contained within a BFD is maintained through the section
+abstraction. A single BFD may have any number of sections. It keeps
+hold of them by pointing to the first; each one points to the next in
+the list.
+
+ Sections are supported in BFD in `section.c'.
+
+* Menu:
+
+* Section Input::
+* Section Output::
+* typedef asection::
+* section prototypes::
+
+
+File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections
+
+2.6.1 Section input
+-------------------
+
+When a BFD is opened for reading, the section structures are created
+and attached to the BFD.
+
+ Each section has a name which describes the section in the outside
+world--for example, `a.out' would contain at least three sections,
+called `.text', `.data' and `.bss'.
+
+ Names need not be unique; for example a COFF file may have several
+sections named `.data'.
+
+ Sometimes a BFD will contain more than the "natural" number of
+sections. A back end may attach other sections containing constructor
+data, or an application may add a section (using `bfd_make_section') to
+the sections attached to an already open BFD. For example, the linker
+creates an extra section `COMMON' for each input file's BFD to hold
+information about common storage.
+
+ The raw data is not necessarily read in when the section descriptor
+is created. Some targets may leave the data in place until a
+`bfd_get_section_contents' call is made. Other back ends may read in
+all the data at once. For example, an S-record file has to be read
+once to determine the size of the data. An IEEE-695 file doesn't
+contain raw data in sections, but data and relocation expressions
+intermixed, so the data area has to be parsed to get out the data and
+relocations.
+
+
+File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections
+
+2.6.2 Section output
+--------------------
+
+To write a new object style BFD, the various sections to be written
+have to be created. They are attached to the BFD in the same way as
+input sections; data is written to the sections using
+`bfd_set_section_contents'.
+
+ Any program that creates or combines sections (e.g., the assembler
+and linker) must use the `asection' fields `output_section' and
+`output_offset' to indicate the file sections to which each section
+must be written. (If the section is being created from scratch,
+`output_section' should probably point to the section itself and
+`output_offset' should probably be zero.)
+
+ The data to be written comes from input sections attached (via
+`output_section' pointers) to the output sections. The output section
+structure can be considered a filter for the input section: the output
+section determines the vma of the output data and the name, but the
+input section determines the offset into the output section of the data
+to be written.
+
+ E.g., to create a section "O", starting at 0x100, 0x123 long,
+containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and
+"B" at offset 0x20 (i.e., at vma 0x120) the `asection' structures would
+look like:
+
+ section name "A"
+ output_offset 0x00
+ size 0x20
+ output_section -----------> section name "O"
+ | vma 0x100
+ section name "B" | size 0x123
+ output_offset 0x20 |
+ size 0x103 |
+ output_section --------|
+
+2.6.3 Link orders
+-----------------
+
+The data within a section is stored in a "link_order". These are much
+like the fixups in `gas'. The link_order abstraction allows a section
+to grow and shrink within itself.
+
+ A link_order knows how big it is, and which is the next link_order
+and where the raw data for it is; it also points to a list of
+relocations which apply to it.
+
+ The link_order is used by the linker to perform relaxing on final
+code. The compiler creates code which is as big as necessary to make
+it work without relaxing, and the user can select whether to relax.
+Sometimes relaxing takes a lot of time. The linker runs around the
+relocations to see if any are attached to data which can be shrunk, if
+so it does it on a link_order by link_order basis.
+
+
+File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections
+
+2.6.4 typedef asection
+----------------------
+
+Here is the section structure:
+
+
+ typedef struct bfd_section
+ {
+ /* The name of the section; the name isn't a copy, the pointer is
+ the same as that passed to bfd_make_section. */
+ const char *name;
+
+ /* A unique sequence number. */
+ int id;
+
+ /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */
+ int index;
+
+ /* The next section in the list belonging to the BFD, or NULL. */
+ struct bfd_section *next;
+
+ /* The previous section in the list belonging to the BFD, or NULL. */
+ struct bfd_section *prev;
+
+ /* The field flags contains attributes of the section. Some
+ flags are read in from the object file, and some are
+ synthesized from other information. */
+ flagword flags;
+
+ #define SEC_NO_FLAGS 0x000
+
+ /* Tells the OS to allocate space for this section when loading.
+ This is clear for a section containing debug information only. */
+ #define SEC_ALLOC 0x001
+
+ /* Tells the OS to load the section from the file when loading.
+ This is clear for a .bss section. */
+ #define SEC_LOAD 0x002
+
+ /* The section contains data still to be relocated, so there is
+ some relocation information too. */
+ #define SEC_RELOC 0x004
+
+ /* A signal to the OS that the section contains read only data. */
+ #define SEC_READONLY 0x008
+
+ /* The section contains code only. */
+ #define SEC_CODE 0x010
+
+ /* The section contains data only. */
+ #define SEC_DATA 0x020
+
+ /* The section will reside in ROM. */
+ #define SEC_ROM 0x040
+
+ /* The section contains constructor information. This section
+ type is used by the linker to create lists of constructors and
+ destructors used by `g++'. When a back end sees a symbol
+ which should be used in a constructor list, it creates a new
+ section for the type of name (e.g., `__CTOR_LIST__'), attaches
+ the symbol to it, and builds a relocation. To build the lists
+ of constructors, all the linker has to do is catenate all the
+ sections called `__CTOR_LIST__' and relocate the data
+ contained within - exactly the operations it would peform on
+ standard data. */
+ #define SEC_CONSTRUCTOR 0x080
+
+ /* The section has contents - a data section could be
+ `SEC_ALLOC' | `SEC_HAS_CONTENTS'; a debug section could be
+ `SEC_HAS_CONTENTS' */
+ #define SEC_HAS_CONTENTS 0x100
+
+ /* An instruction to the linker to not output the section
+ even if it has information which would normally be written. */
+ #define SEC_NEVER_LOAD 0x200
+
+ /* The section contains thread local data. */
+ #define SEC_THREAD_LOCAL 0x400
+
+ /* The section has GOT references. This flag is only for the
+ linker, and is currently only used by the elf32-hppa back end.
+ It will be set if global offset table references were detected
+ in this section, which indicate to the linker that the section
+ contains PIC code, and must be handled specially when doing a
+ static link. */
+ #define SEC_HAS_GOT_REF 0x800
+
+ /* The section contains common symbols (symbols may be defined
+ multiple times, the value of a symbol is the amount of
+ space it requires, and the largest symbol value is the one
+ used). Most targets have exactly one of these (which we
+ translate to bfd_com_section_ptr), but ECOFF has two. */
+ #define SEC_IS_COMMON 0x1000
+
+ /* The section contains only debugging information. For
+ example, this is set for ELF .debug and .stab sections.
+ strip tests this flag to see if a section can be
+ discarded. */
+ #define SEC_DEBUGGING 0x2000
+
+ /* The contents of this section are held in memory pointed to
+ by the contents field. This is checked by bfd_get_section_contents,
+ and the data is retrieved from memory if appropriate. */
+ #define SEC_IN_MEMORY 0x4000
+
+ /* The contents of this section are to be excluded by the
+ linker for executable and shared objects unless those
+ objects are to be further relocated. */
+ #define SEC_EXCLUDE 0x8000
+
+ /* The contents of this section are to be sorted based on the sum of
+ the symbol and addend values specified by the associated relocation
+ entries. Entries without associated relocation entries will be
+ appended to the end of the section in an unspecified order. */
+ #define SEC_SORT_ENTRIES 0x10000
+
+ /* When linking, duplicate sections of the same name should be
+ discarded, rather than being combined into a single section as
+ is usually done. This is similar to how common symbols are
+ handled. See SEC_LINK_DUPLICATES below. */
+ #define SEC_LINK_ONCE 0x20000
+
+ /* If SEC_LINK_ONCE is set, this bitfield describes how the linker
+ should handle duplicate sections. */
+ #define SEC_LINK_DUPLICATES 0xc0000
+
+ /* This value for SEC_LINK_DUPLICATES means that duplicate
+ sections with the same name should simply be discarded. */
+ #define SEC_LINK_DUPLICATES_DISCARD 0x0
+
+ /* This value for SEC_LINK_DUPLICATES means that the linker
+ should warn if there are any duplicate sections, although
+ it should still only link one copy. */
+ #define SEC_LINK_DUPLICATES_ONE_ONLY 0x40000
+
+ /* This value for SEC_LINK_DUPLICATES means that the linker
+ should warn if any duplicate sections are a different size. */
+ #define SEC_LINK_DUPLICATES_SAME_SIZE 0x80000
+
+ /* This value for SEC_LINK_DUPLICATES means that the linker
+ should warn if any duplicate sections contain different
+ contents. */
+ #define SEC_LINK_DUPLICATES_SAME_CONTENTS \
+ (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE)
+
+ /* This section was created by the linker as part of dynamic
+ relocation or other arcane processing. It is skipped when
+ going through the first-pass output, trusting that someone
+ else up the line will take care of it later. */
+ #define SEC_LINKER_CREATED 0x100000
+
+ /* This section should not be subject to garbage collection.
+ Also set to inform the linker that this section should not be
+ listed in the link map as discarded. */
+ #define SEC_KEEP 0x200000
+
+ /* This section contains "short" data, and should be placed
+ "near" the GP. */
+ #define SEC_SMALL_DATA 0x400000
+
+ /* Attempt to merge identical entities in the section.
+ Entity size is given in the entsize field. */
+ #define SEC_MERGE 0x800000
+
+ /* If given with SEC_MERGE, entities to merge are zero terminated
+ strings where entsize specifies character size instead of fixed
+ size entries. */
+ #define SEC_STRINGS 0x1000000
+
+ /* This section contains data about section groups. */
+ #define SEC_GROUP 0x2000000
+
+ /* The section is a COFF shared library section. This flag is
+ only for the linker. If this type of section appears in
+ the input file, the linker must copy it to the output file
+ without changing the vma or size. FIXME: Although this
+ was originally intended to be general, it really is COFF
+ specific (and the flag was renamed to indicate this). It
+ might be cleaner to have some more general mechanism to
+ allow the back end to control what the linker does with
+ sections. */
+ #define SEC_COFF_SHARED_LIBRARY 0x4000000
+
+ /* This section contains data which may be shared with other
+ executables or shared objects. This is for COFF only. */
+ #define SEC_COFF_SHARED 0x8000000
+
+ /* When a section with this flag is being linked, then if the size of
+ the input section is less than a page, it should not cross a page
+ boundary. If the size of the input section is one page or more,
+ it should be aligned on a page boundary. This is for TI
+ TMS320C54X only. */
+ #define SEC_TIC54X_BLOCK 0x10000000
+
+ /* Conditionally link this section; do not link if there are no
+ references found to any symbol in the section. This is for TI
+ TMS320C54X only. */
+ #define SEC_TIC54X_CLINK 0x20000000
+
+ /* Indicate that section has the no read flag set. This happens
+ when memory read flag isn't set. */
+ #define SEC_COFF_NOREAD 0x40000000
+
+ /* End of section flags. */
+
+ /* Some internal packed boolean fields. */
+
+ /* See the vma field. */
+ unsigned int user_set_vma : 1;
+
+ /* A mark flag used by some of the linker backends. */
+ unsigned int linker_mark : 1;
+
+ /* Another mark flag used by some of the linker backends. Set for
+ output sections that have an input section. */
+ unsigned int linker_has_input : 1;
+
+ /* Mark flag used by some linker backends for garbage collection. */
+ unsigned int gc_mark : 1;
+
+ /* The following flags are used by the ELF linker. */
+
+ /* Mark sections which have been allocated to segments. */
+ unsigned int segment_mark : 1;
+
+ /* Type of sec_info information. */
+ unsigned int sec_info_type:3;
+ #define ELF_INFO_TYPE_NONE 0
+ #define ELF_INFO_TYPE_STABS 1
+ #define ELF_INFO_TYPE_MERGE 2
+ #define ELF_INFO_TYPE_EH_FRAME 3
+ #define ELF_INFO_TYPE_JUST_SYMS 4
+
+ /* Nonzero if this section uses RELA relocations, rather than REL. */
+ unsigned int use_rela_p:1;
+
+ /* Bits used by various backends. The generic code doesn't touch
+ these fields. */
+
+ /* Nonzero if this section has TLS related relocations. */
+ unsigned int has_tls_reloc:1;
+
+ /* Nonzero if this section has a call to __tls_get_addr. */
+ unsigned int has_tls_get_addr_call:1;
+
+ /* Nonzero if this section has a gp reloc. */
+ unsigned int has_gp_reloc:1;
+
+ /* Nonzero if this section needs the relax finalize pass. */
+ unsigned int need_finalize_relax:1;
+
+ /* Whether relocations have been processed. */
+ unsigned int reloc_done : 1;
+
+ /* End of internal packed boolean fields. */
+
+ /* The virtual memory address of the section - where it will be
+ at run time. The symbols are relocated against this. The
+ user_set_vma flag is maintained by bfd; if it's not set, the
+ backend can assign addresses (for example, in `a.out', where
+ the default address for `.data' is dependent on the specific
+ target and various flags). */
+ bfd_vma vma;
+
+ /* The load address of the section - where it would be in a
+ rom image; really only used for writing section header
+ information. */
+ bfd_vma lma;
+
+ /* The size of the section in octets, as it will be output.
+ Contains a value even if the section has no contents (e.g., the
+ size of `.bss'). */
+ bfd_size_type size;
+
+ /* For input sections, the original size on disk of the section, in
+ octets. This field should be set for any section whose size is
+ changed by linker relaxation. It is required for sections where
+ the linker relaxation scheme doesn't cache altered section and
+ reloc contents (stabs, eh_frame, SEC_MERGE, some coff relaxing
+ targets), and thus the original size needs to be kept to read the
+ section multiple times. For output sections, rawsize holds the
+ section size calculated on a previous linker relaxation pass. */
+ bfd_size_type rawsize;
+
+ /* Relaxation table. */
+ struct relax_table *relax;
+
+ /* Count of used relaxation table entries. */
+ int relax_count;
+
+
+ /* If this section is going to be output, then this value is the
+ offset in *bytes* into the output section of the first byte in the
+ input section (byte ==> smallest addressable unit on the
+ target). In most cases, if this was going to start at the
+ 100th octet (8-bit quantity) in the output section, this value
+ would be 100. However, if the target byte size is 16 bits
+ (bfd_octets_per_byte is "2"), this value would be 50. */
+ bfd_vma output_offset;
+
+ /* The output section through which to map on output. */
+ struct bfd_section *output_section;
+
+ /* The alignment requirement of the section, as an exponent of 2 -
+ e.g., 3 aligns to 2^3 (or 8). */
+ unsigned int alignment_power;
+
+ /* If an input section, a pointer to a vector of relocation
+ records for the data in this section. */
+ struct reloc_cache_entry *relocation;
+
+ /* If an output section, a pointer to a vector of pointers to
+ relocation records for the data in this section. */
+ struct reloc_cache_entry **orelocation;
+
+ /* The number of relocation records in one of the above. */
+ unsigned reloc_count;
+
+ /* Information below is back end specific - and not always used
+ or updated. */
+
+ /* File position of section data. */
+ file_ptr filepos;
+
+ /* File position of relocation info. */
+ file_ptr rel_filepos;
+
+ /* File position of line data. */
+ file_ptr line_filepos;
+
+ /* Pointer to data for applications. */
+ void *userdata;
+
+ /* If the SEC_IN_MEMORY flag is set, this points to the actual
+ contents. */
+ unsigned char *contents;
+
+ /* Attached line number information. */
+ alent *lineno;
+
+ /* Number of line number records. */
+ unsigned int lineno_count;
+
+ /* Entity size for merging purposes. */
+ unsigned int entsize;
+
+ /* Points to the kept section if this section is a link-once section,
+ and is discarded. */
+ struct bfd_section *kept_section;
+
+ /* When a section is being output, this value changes as more
+ linenumbers are written out. */
+ file_ptr moving_line_filepos;
+
+ /* What the section number is in the target world. */
+ int target_index;
+
+ void *used_by_bfd;
+
+ /* If this is a constructor section then here is a list of the
+ relocations created to relocate items within it. */
+ struct relent_chain *constructor_chain;
+
+ /* The BFD which owns the section. */
+ bfd *owner;
+
+ /* A symbol which points at this section only. */
+ struct bfd_symbol *symbol;
+ struct bfd_symbol **symbol_ptr_ptr;
+
+ /* Early in the link process, map_head and map_tail are used to build
+ a list of input sections attached to an output section. Later,
+ output sections use these fields for a list of bfd_link_order
+ structs. */
+ union {
+ struct bfd_link_order *link_order;
+ struct bfd_section *s;
+ } map_head, map_tail;
+ } asection;
+
+ /* Relax table contains information about instructions which can
+ be removed by relaxation -- replacing a long address with a
+ short address. */
+ struct relax_table {
+ /* Address where bytes may be deleted. */
+ bfd_vma addr;
+
+ /* Number of bytes to be deleted. */
+ int size;
+ };
+
+ /* These sections are global, and are managed by BFD. The application
+ and target back end are not permitted to change the values in
+ these sections. New code should use the section_ptr macros rather
+ than referring directly to the const sections. The const sections
+ may eventually vanish. */
+ #define BFD_ABS_SECTION_NAME "*ABS*"
+ #define BFD_UND_SECTION_NAME "*UND*"
+ #define BFD_COM_SECTION_NAME "*COM*"
+ #define BFD_IND_SECTION_NAME "*IND*"
+
+ /* The absolute section. */
+ extern asection bfd_abs_section;
+ #define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
+ #define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
+ /* Pointer to the undefined section. */
+ extern asection bfd_und_section;
+ #define bfd_und_section_ptr ((asection *) &bfd_und_section)
+ #define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
+ /* Pointer to the common section. */
+ extern asection bfd_com_section;
+ #define bfd_com_section_ptr ((asection *) &bfd_com_section)
+ /* Pointer to the indirect section. */
+ extern asection bfd_ind_section;
+ #define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
+ #define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)
+
+ #define bfd_is_const_section(SEC) \
+ ( ((SEC) == bfd_abs_section_ptr) \
+ || ((SEC) == bfd_und_section_ptr) \
+ || ((SEC) == bfd_com_section_ptr) \
+ || ((SEC) == bfd_ind_section_ptr))
+
+ /* Macros to handle insertion and deletion of a bfd's sections. These
+ only handle the list pointers, ie. do not adjust section_count,
+ target_index etc. */
+ #define bfd_section_list_remove(ABFD, S) \
+ do \
+ { \
+ asection *_s = S; \
+ asection *_next = _s->next; \
+ asection *_prev = _s->prev; \
+ if (_prev) \
+ _prev->next = _next; \
+ else \
+ (ABFD)->sections = _next; \
+ if (_next) \
+ _next->prev = _prev; \
+ else \
+ (ABFD)->section_last = _prev; \
+ } \
+ while (0)
+ #define bfd_section_list_append(ABFD, S) \
+ do \
+ { \
+ asection *_s = S; \
+ bfd *_abfd = ABFD; \
+ _s->next = NULL; \
+ if (_abfd->section_last) \
+ { \
+ _s->prev = _abfd->section_last; \
+ _abfd->section_last->next = _s; \
+ } \
+ else \
+ { \
+ _s->prev = NULL; \
+ _abfd->sections = _s; \
+ } \
+ _abfd->section_last = _s; \
+ } \
+ while (0)
+ #define bfd_section_list_prepend(ABFD, S) \
+ do \
+ { \
+ asection *_s = S; \
+ bfd *_abfd = ABFD; \
+ _s->prev = NULL; \
+ if (_abfd->sections) \
+ { \
+ _s->next = _abfd->sections; \
+ _abfd->sections->prev = _s; \
+ } \
+ else \
+ { \
+ _s->next = NULL; \
+ _abfd->section_last = _s; \
+ } \
+ _abfd->sections = _s; \
+ } \
+ while (0)
+ #define bfd_section_list_insert_after(ABFD, A, S) \
+ do \
+ { \
+ asection *_a = A; \
+ asection *_s = S; \
+ asection *_next = _a->next; \
+ _s->next = _next; \
+ _s->prev = _a; \
+ _a->next = _s; \
+ if (_next) \
+ _next->prev = _s; \
+ else \
+ (ABFD)->section_last = _s; \
+ } \
+ while (0)
+ #define bfd_section_list_insert_before(ABFD, B, S) \
+ do \
+ { \
+ asection *_b = B; \
+ asection *_s = S; \
+ asection *_prev = _b->prev; \
+ _s->prev = _prev; \
+ _s->next = _b; \
+ _b->prev = _s; \
+ if (_prev) \
+ _prev->next = _s; \
+ else \
+ (ABFD)->sections = _s; \
+ } \
+ while (0)
+ #define bfd_section_removed_from_list(ABFD, S) \
+ ((S)->next == NULL ? (ABFD)->section_last != (S) : (S)->next->prev != (S))
+
+ #define BFD_FAKE_SECTION(SEC, FLAGS, SYM, NAME, IDX) \
+ /* name, id, index, next, prev, flags, user_set_vma, */ \
+ { NAME, IDX, 0, NULL, NULL, FLAGS, 0, \
+ \
+ /* linker_mark, linker_has_input, gc_mark, */ \
+ 0, 0, 1, \
+ \
+ /* segment_mark, sec_info_type, use_rela_p, has_tls_reloc, */ \
+ 0, 0, 0, 0, \
+ \
+ /* has_tls_get_addr_call, has_gp_reloc, need_finalize_relax, */ \
+ 0, 0, 0, \
+ \
+ /* reloc_done, vma, lma, size, rawsize, relax, relax_count, */ \
+ 0, 0, 0, 0, 0, 0, 0, \
+ \
+ /* output_offset, output_section, alignment_power, */ \
+ 0, (struct bfd_section *) &SEC, 0, \
+ \
+ /* relocation, orelocation, reloc_count, filepos, rel_filepos, */ \
+ NULL, NULL, 0, 0, 0, \
+ \
+ /* line_filepos, userdata, contents, lineno, lineno_count, */ \
+ 0, NULL, NULL, NULL, 0, \
+ \
+ /* entsize, kept_section, moving_line_filepos, */ \
+ 0, NULL, 0, \
+ \
+ /* target_index, used_by_bfd, constructor_chain, owner, */ \
+ 0, NULL, NULL, NULL, \
+ \
+ /* symbol, symbol_ptr_ptr, */ \
+ (struct bfd_symbol *) SYM, &SEC.symbol, \
+ \
+ /* map_head, map_tail */ \
+ { NULL }, { NULL } \
+ }
+
+
+File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections
+
+2.6.5 Section prototypes
+------------------------
+
+These are the functions exported by the section handling part of BFD.
+
+2.6.5.1 `bfd_section_list_clear'
+................................
+
+*Synopsis*
+ void bfd_section_list_clear (bfd *);
+ *Description*
+Clears the section list, and also resets the section count and hash
+table entries.
+
+2.6.5.2 `bfd_get_section_by_name'
+.................................
+
+*Synopsis*
+ asection *bfd_get_section_by_name (bfd *abfd, const char *name);
+ *Description*
+Run through ABFD and return the one of the `asection's whose name
+matches NAME, otherwise `NULL'. *Note Sections::, for more information.
+
+ This should only be used in special cases; the normal way to process
+all sections of a given name is to use `bfd_map_over_sections' and
+`strcmp' on the name (or better yet, base it on the section flags or
+something else) for each section.
+
+2.6.5.3 `bfd_get_section_by_name_if'
+....................................
+
+*Synopsis*
+ asection *bfd_get_section_by_name_if
+ (bfd *abfd,
+ const char *name,
+ bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj),
+ void *obj);
+ *Description*
+Call the provided function FUNC for each section attached to the BFD
+ABFD whose name matches NAME, passing OBJ as an argument. The function
+will be called as if by
+
+ func (abfd, the_section, obj);
+
+ It returns the first section for which FUNC returns true, otherwise
+`NULL'.
+
+2.6.5.4 `bfd_get_unique_section_name'
+.....................................
+
+*Synopsis*
+ char *bfd_get_unique_section_name
+ (bfd *abfd, const char *templat, int *count);
+ *Description*
+Invent a section name that is unique in ABFD by tacking a dot and a
+digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then it
+specifies the first number tried as a suffix to generate a unique name.
+The value pointed to by COUNT will be incremented in this case.
+
+2.6.5.5 `bfd_make_section_old_way'
+..................................
+
+*Synopsis*
+ asection *bfd_make_section_old_way (bfd *abfd, const char *name);
+ *Description*
+Create a new empty section called NAME and attach it to the end of the
+chain of sections for the BFD ABFD. An attempt to create a section with
+a name which is already in use returns its pointer without changing the
+section chain.
+
+ It has the funny name since this is the way it used to be before it
+was rewritten....
+
+ Possible errors are:
+ * `bfd_error_invalid_operation' - If output has already started for
+ this BFD.
+
+ * `bfd_error_no_memory' - If memory allocation fails.
+
+2.6.5.6 `bfd_make_section_anyway_with_flags'
+............................................
+
+*Synopsis*
+ asection *bfd_make_section_anyway_with_flags
+ (bfd *abfd, const char *name, flagword flags);
+ *Description*
+Create a new empty section called NAME and attach it to the end of the
+chain of sections for ABFD. Create a new section even if there is
+already a section with that name. Also set the attributes of the new
+section to the value FLAGS.
+
+ Return `NULL' and set `bfd_error' on error; possible errors are:
+ * `bfd_error_invalid_operation' - If output has already started for
+ ABFD.
+
+ * `bfd_error_no_memory' - If memory allocation fails.
+
+2.6.5.7 `bfd_make_section_anyway'
+.................................
+
+*Synopsis*
+ asection *bfd_make_section_anyway (bfd *abfd, const char *name);
+ *Description*
+Create a new empty section called NAME and attach it to the end of the
+chain of sections for ABFD. Create a new section even if there is
+already a section with that name.
+
+ Return `NULL' and set `bfd_error' on error; possible errors are:
+ * `bfd_error_invalid_operation' - If output has already started for
+ ABFD.
+
+ * `bfd_error_no_memory' - If memory allocation fails.
+
+2.6.5.8 `bfd_make_section_with_flags'
+.....................................
+
+*Synopsis*
+ asection *bfd_make_section_with_flags
+ (bfd *, const char *name, flagword flags);
+ *Description*
+Like `bfd_make_section_anyway', but return `NULL' (without calling
+bfd_set_error ()) without changing the section chain if there is
+already a section named NAME. Also set the attributes of the new
+section to the value FLAGS. If there is an error, return `NULL' and set
+`bfd_error'.
+
+2.6.5.9 `bfd_make_section'
+..........................
+
+*Synopsis*
+ asection *bfd_make_section (bfd *, const char *name);
+ *Description*
+Like `bfd_make_section_anyway', but return `NULL' (without calling
+bfd_set_error ()) without changing the section chain if there is
+already a section named NAME. If there is an error, return `NULL' and
+set `bfd_error'.
+
+2.6.5.10 `bfd_set_section_flags'
+................................
+
+*Synopsis*
+ bfd_boolean bfd_set_section_flags
+ (bfd *abfd, asection *sec, flagword flags);
+ *Description*
+Set the attributes of the section SEC in the BFD ABFD to the value
+FLAGS. Return `TRUE' on success, `FALSE' on error. Possible error
+returns are:
+
+ * `bfd_error_invalid_operation' - The section cannot have one or
+ more of the attributes requested. For example, a .bss section in
+ `a.out' may not have the `SEC_HAS_CONTENTS' field set.
+
+2.6.5.11 `bfd_map_over_sections'
+................................
+
+*Synopsis*
+ void bfd_map_over_sections
+ (bfd *abfd,
+ void (*func) (bfd *abfd, asection *sect, void *obj),
+ void *obj);
+ *Description*
+Call the provided function FUNC for each section attached to the BFD
+ABFD, passing OBJ as an argument. The function will be called as if by
+
+ func (abfd, the_section, obj);
+
+ This is the preferred method for iterating over sections; an
+alternative would be to use a loop:
+
+ section *p;
+ for (p = abfd->sections; p != NULL; p = p->next)
+ func (abfd, p, ...)
+
+2.6.5.12 `bfd_sections_find_if'
+...............................
+
+*Synopsis*
+ asection *bfd_sections_find_if
+ (bfd *abfd,
+ bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj),
+ void *obj);
+ *Description*
+Call the provided function OPERATION for each section attached to the
+BFD ABFD, passing OBJ as an argument. The function will be called as if
+by
+
+ operation (abfd, the_section, obj);
+
+ It returns the first section for which OPERATION returns true.
+
+2.6.5.13 `bfd_set_section_size'
+...............................
+
+*Synopsis*
+ bfd_boolean bfd_set_section_size
+ (bfd *abfd, asection *sec, bfd_size_type val);
+ *Description*
+Set SEC to the size VAL. If the operation is ok, then `TRUE' is
+returned, else `FALSE'.
+
+ Possible error returns:
+ * `bfd_error_invalid_operation' - Writing has started to the BFD, so
+ setting the size is invalid.
+
+2.6.5.14 `bfd_set_section_contents'
+...................................
+
+*Synopsis*
+ bfd_boolean bfd_set_section_contents
+ (bfd *abfd, asection *section, const void *data,
+ file_ptr offset, bfd_size_type count);
+ *Description*
+Sets the contents of the section SECTION in BFD ABFD to the data
+starting in memory at DATA. The data is written to the output section
+starting at offset OFFSET for COUNT octets.
+
+ Normally `TRUE' is returned, else `FALSE'. Possible error returns
+are:
+ * `bfd_error_no_contents' - The output section does not have the
+ `SEC_HAS_CONTENTS' attribute, so nothing can be written to it.
+
+ * and some more too
+ This routine is front end to the back end function
+`_bfd_set_section_contents'.
+
+2.6.5.15 `bfd_get_section_contents'
+...................................
+
+*Synopsis*
+ bfd_boolean bfd_get_section_contents
+ (bfd *abfd, asection *section, void *location, file_ptr offset,
+ bfd_size_type count);
+ *Description*
+Read data from SECTION in BFD ABFD into memory starting at LOCATION.
+The data is read at an offset of OFFSET from the start of the input
+section, and is read for COUNT bytes.
+
+ If the contents of a constructor with the `SEC_CONSTRUCTOR' flag set
+are requested or if the section does not have the `SEC_HAS_CONTENTS'
+flag set, then the LOCATION is filled with zeroes. If no errors occur,
+`TRUE' is returned, else `FALSE'.
+
+2.6.5.16 `bfd_malloc_and_get_section'
+.....................................
+
+*Synopsis*
+ bfd_boolean bfd_malloc_and_get_section
+ (bfd *abfd, asection *section, bfd_byte **buf);
+ *Description*
+Read all data from SECTION in BFD ABFD into a buffer, *BUF, malloc'd by
+this function.
+
+2.6.5.17 `bfd_copy_private_section_data'
+........................................
+
+*Synopsis*
+ bfd_boolean bfd_copy_private_section_data
+ (bfd *ibfd, asection *isec, bfd *obfd, asection *osec);
+ *Description*
+Copy private section information from ISEC in the BFD IBFD to the
+section OSEC in the BFD OBFD. Return `TRUE' on success, `FALSE' on
+error. Possible error returns are:
+
+ * `bfd_error_no_memory' - Not enough memory exists to create private
+ data for OSEC.
+
+ #define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
+ BFD_SEND (obfd, _bfd_copy_private_section_data, \
+ (ibfd, isection, obfd, osection))
+
+2.6.5.18 `bfd_generic_is_group_section'
+.......................................
+
+*Synopsis*
+ bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec);
+ *Description*
+Returns TRUE if SEC is a member of a group.
+
+2.6.5.19 `bfd_generic_discard_group'
+....................................
+
+*Synopsis*
+ bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group);
+ *Description*
+Remove all members of GROUP from the output.
+
+
+File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end
+
+2.7 Symbols
+===========
+
+BFD tries to maintain as much symbol information as it can when it
+moves information from file to file. BFD passes information to
+applications though the `asymbol' structure. When the application
+requests the symbol table, BFD reads the table in the native form and
+translates parts of it into the internal format. To maintain more than
+the information passed to applications, some targets keep some
+information "behind the scenes" in a structure only the particular back
+end knows about. For example, the coff back end keeps the original
+symbol table structure as well as the canonical structure when a BFD is
+read in. On output, the coff back end can reconstruct the output symbol
+table so that no information is lost, even information unique to coff
+which BFD doesn't know or understand. If a coff symbol table were read,
+but were written through an a.out back end, all the coff specific
+information would be lost. The symbol table of a BFD is not necessarily
+read in until a canonicalize request is made. Then the BFD back end
+fills in a table provided by the application with pointers to the
+canonical information. To output symbols, the application provides BFD
+with a table of pointers to pointers to `asymbol's. This allows
+applications like the linker to output a symbol as it was read, since
+the "behind the scenes" information will be still available.
+
+* Menu:
+
+* Reading Symbols::
+* Writing Symbols::
+* Mini Symbols::
+* typedef asymbol::
+* symbol handling functions::
+
+
+File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols
+
+2.7.1 Reading symbols
+---------------------
+
+There are two stages to reading a symbol table from a BFD: allocating
+storage, and the actual reading process. This is an excerpt from an
+application which reads the symbol table:
+
+ long storage_needed;
+ asymbol **symbol_table;
+ long number_of_symbols;
+ long i;
+
+ storage_needed = bfd_get_symtab_upper_bound (abfd);
+
+ if (storage_needed < 0)
+ FAIL
+
+ if (storage_needed == 0)
+ return;
+
+ symbol_table = xmalloc (storage_needed);
+ ...
+ number_of_symbols =
+ bfd_canonicalize_symtab (abfd, symbol_table);
+
+ if (number_of_symbols < 0)
+ FAIL
+
+ for (i = 0; i < number_of_symbols; i++)
+ process_symbol (symbol_table[i]);
+
+ All storage for the symbols themselves is in an objalloc connected
+to the BFD; it is freed when the BFD is closed.
+
+
+File: bfd.info, Node: Writing Symbols, Next: Mini Symbols, Prev: Reading Symbols, Up: Symbols
+
+2.7.2 Writing symbols
+---------------------
+
+Writing of a symbol table is automatic when a BFD open for writing is
+closed. The application attaches a vector of pointers to pointers to
+symbols to the BFD being written, and fills in the symbol count. The
+close and cleanup code reads through the table provided and performs
+all the necessary operations. The BFD output code must always be
+provided with an "owned" symbol: one which has come from another BFD,
+or one which has been created using `bfd_make_empty_symbol'. Here is an
+example showing the creation of a symbol table with only one element:
+
+ #include "bfd.h"
+ int main (void)
+ {
+ bfd *abfd;
+ asymbol *ptrs[2];
+ asymbol *new;
+
+ abfd = bfd_openw ("foo","a.out-sunos-big");
+ bfd_set_format (abfd, bfd_object);
+ new = bfd_make_empty_symbol (abfd);
+ new->name = "dummy_symbol";
+ new->section = bfd_make_section_old_way (abfd, ".text");
+ new->flags = BSF_GLOBAL;
+ new->value = 0x12345;
+
+ ptrs[0] = new;
+ ptrs[1] = 0;
+
+ bfd_set_symtab (abfd, ptrs, 1);
+ bfd_close (abfd);
+ return 0;
+ }
+
+ ./makesym
+ nm foo
+ 00012345 A dummy_symbol
+
+ Many formats cannot represent arbitrary symbol information; for
+instance, the `a.out' object format does not allow an arbitrary number
+of sections. A symbol pointing to a section which is not one of
+`.text', `.data' or `.bss' cannot be described.
+
+
+File: bfd.info, Node: Mini Symbols, Next: typedef asymbol, Prev: Writing Symbols, Up: Symbols
+
+2.7.3 Mini Symbols
+------------------
+
+Mini symbols provide read-only access to the symbol table. They use
+less memory space, but require more time to access. They can be useful
+for tools like nm or objdump, which may have to handle symbol tables of
+extremely large executables.
+
+ The `bfd_read_minisymbols' function will read the symbols into
+memory in an internal form. It will return a `void *' pointer to a
+block of memory, a symbol count, and the size of each symbol. The
+pointer is allocated using `malloc', and should be freed by the caller
+when it is no longer needed.
+
+ The function `bfd_minisymbol_to_symbol' will take a pointer to a
+minisymbol, and a pointer to a structure returned by
+`bfd_make_empty_symbol', and return a `asymbol' structure. The return
+value may or may not be the same as the value from
+`bfd_make_empty_symbol' which was passed in.
+
+
+File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Mini Symbols, Up: Symbols
+
+2.7.4 typedef asymbol
+---------------------
+
+An `asymbol' has the form:
+
+
+ typedef struct bfd_symbol
+ {
+ /* 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 (1 << 0)
+
+ /* The symbol has global scope; initialized data in `C'. The
+ value is the offset into the section of the data. */
+ #define BSF_GLOBAL (1 << 1)
+
+ /* 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_COMMON', `BSF_UNDEFINED' or
+ `BSF_GLOBAL'. */
+
+ /* The symbol is a debugging record. The value has an arbitrary
+ meaning, unless BSF_DEBUGGING_RELOC is also set. */
+ #define BSF_DEBUGGING (1 << 2)
+
+ /* The symbol denotes a function entry point. Used in ELF,
+ perhaps others someday. */
+ #define BSF_FUNCTION (1 << 3)
+
+ /* Used by the linker. */
+ #define BSF_KEEP (1 << 5)
+ #define BSF_KEEP_G (1 << 6)
+
+ /* A weak global symbol, overridable without warnings by
+ a regular global symbol of the same name. */
+ #define BSF_WEAK (1 << 7)
+
+ /* This symbol was created to point to a section, e.g. ELF's
+ STT_SECTION symbols. */
+ #define BSF_SECTION_SYM (1 << 8)
+
+ /* The symbol used to be a common symbol, but now it is
+ allocated. */
+ #define BSF_OLD_COMMON (1 << 9)
+
+ /* 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 (1 << 10)
+
+ /* Signal that the symbol is the label of constructor section. */
+ #define BSF_CONSTRUCTOR (1 << 11)
+
+ /* Signal that the symbol is a warning symbol. The name is a
+ warning. The name of the next symbol is the one to warn about;
+ if a reference is made to a symbol with the same name as the next
+ symbol, a warning is issued by the linker. */
+ #define BSF_WARNING (1 << 12)
+
+ /* Signal that the symbol is indirect. This symbol is an indirect
+ pointer to the symbol with the same name as the next symbol. */
+ #define BSF_INDIRECT (1 << 13)
+
+ /* BSF_FILE marks symbols that contain a file name. This is used
+ for ELF STT_FILE symbols. */
+ #define BSF_FILE (1 << 14)
+
+ /* Symbol is from dynamic linking information. */
+ #define BSF_DYNAMIC (1 << 15)
+
+ /* The symbol denotes a data object. Used in ELF, and perhaps
+ others someday. */
+ #define BSF_OBJECT (1 << 16)
+
+ /* This symbol is a debugging symbol. The value is the offset
+ into the section of the data. BSF_DEBUGGING should be set
+ as well. */
+ #define BSF_DEBUGGING_RELOC (1 << 17)
+
+ /* This symbol is thread local. Used in ELF. */
+ #define BSF_THREAD_LOCAL (1 << 18)
+
+ /* This symbol represents a complex relocation expression,
+ with the expression tree serialized in the symbol name. */
+ #define BSF_RELC (1 << 19)
+
+ /* This symbol represents a signed complex relocation expression,
+ with the expression tree serialized in the symbol name. */
+ #define BSF_SRELC (1 << 20)
+
+ /* This symbol was created by bfd_get_synthetic_symtab. */
+ #define BSF_SYNTHETIC (1 << 21)
+
+ /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT.
+ The dynamic linker will compute the value of this symbol by
+ calling the function that it points to. BSF_FUNCTION must
+ also be also set. */
+ #define BSF_GNU_INDIRECT_FUNCTION (1 << 22)
+ /* This symbol is a globally unique data object. The dynamic linker
+ will make sure that in the entire process there is just one symbol
+ with this name and type in use. BSF_OBJECT must also be set. */
+ #define BSF_GNU_UNIQUE (1 << 23)
+
+ 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 bfd_section *section;
+
+ /* Back end special data. */
+ union
+ {
+ void *p;
+ bfd_vma i;
+ }
+ udata;
+ }
+ asymbol;
+
+
+File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols
+
+2.7.5 Symbol handling functions
+-------------------------------
+
+2.7.5.1 `bfd_get_symtab_upper_bound'
+....................................
+
+*Description*
+Return the number of bytes required to store a vector of pointers to
+`asymbols' for all the symbols in the BFD ABFD, including a terminal
+NULL pointer. If there are no symbols in the BFD, then return 0. If an
+error occurs, return -1.
+ #define bfd_get_symtab_upper_bound(abfd) \
+ BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
+
+2.7.5.2 `bfd_is_local_label'
+............................
+
+*Synopsis*
+ bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym);
+ *Description*
+Return TRUE if the given symbol SYM in the BFD ABFD is a compiler
+generated local label, else return FALSE.
+
+2.7.5.3 `bfd_is_local_label_name'
+.................................
+
+*Synopsis*
+ bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name);
+ *Description*
+Return TRUE if a symbol with the name NAME in the BFD ABFD is a
+compiler generated local label, else return FALSE. This just checks
+whether the name has the form of a local label.
+ #define bfd_is_local_label_name(abfd, name) \
+ BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
+
+2.7.5.4 `bfd_is_target_special_symbol'
+......................................
+
+*Synopsis*
+ bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym);
+ *Description*
+Return TRUE iff a symbol SYM in the BFD ABFD is something special to
+the particular target represented by the BFD. Such symbols should
+normally not be mentioned to the user.
+ #define bfd_is_target_special_symbol(abfd, sym) \
+ BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym))
+
+2.7.5.5 `bfd_canonicalize_symtab'
+.................................
+
+*Description*
+Read the symbols from the BFD ABFD, and fills in the vector LOCATION
+with pointers to the symbols and a trailing NULL. Return the actual
+number of symbol pointers, not including the NULL.
+ #define bfd_canonicalize_symtab(abfd, location) \
+ BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location))
+
+2.7.5.6 `bfd_set_symtab'
+........................
+
+*Synopsis*
+ bfd_boolean bfd_set_symtab
+ (bfd *abfd, asymbol **location, unsigned int count);
+ *Description*
+Arrange that when the output BFD ABFD is closed, the table LOCATION of
+COUNT pointers to symbols will be written.
+
+2.7.5.7 `bfd_print_symbol_vandf'
+................................
+
+*Synopsis*
+ void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol);
+ *Description*
+Print the value and flags of the SYMBOL supplied to the stream FILE.
+
+2.7.5.8 `bfd_make_empty_symbol'
+...............................
+
+*Description*
+Create a new `asymbol' structure for the BFD ABFD and return a pointer
+to it.
+
+ This routine is necessary because 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))
+
+2.7.5.9 `_bfd_generic_make_empty_symbol'
+........................................
+
+*Synopsis*
+ asymbol *_bfd_generic_make_empty_symbol (bfd *);
+ *Description*
+Create a new `asymbol' structure for the BFD ABFD and return a pointer
+to it. Used by core file routines, binary back-end and anywhere else
+where no private info is needed.
+
+2.7.5.10 `bfd_make_debug_symbol'
+................................
+
+*Description*
+Create a new `asymbol' structure for the BFD ABFD, 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))
+
+2.7.5.11 `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);
+
+2.7.5.12 `bfd_is_undefined_symclass'
+....................................
+
+*Description*
+Returns non-zero if the class symbol returned by bfd_decode_symclass
+represents an undefined symbol. Returns zero otherwise.
+
+ *Synopsis*
+ bfd_boolean bfd_is_undefined_symclass (int symclass);
+
+2.7.5.13 `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);
+
+2.7.5.14 `bfd_copy_private_symbol_data'
+.......................................
+
+*Synopsis*
+ bfd_boolean bfd_copy_private_symbol_data
+ (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);
+ *Description*
+Copy private symbol information from ISYM in the BFD IBFD to the symbol
+OSYM in the BFD OBFD. Return `TRUE' on success, `FALSE' on error.
+Possible error returns are:
+
+ * `bfd_error_no_memory' - Not enough memory exists to create private
+ data for OSEC.
+
+ #define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
+ BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
+ (ibfd, isymbol, obfd, osymbol))
+
+
+File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end
+
+2.8 Archives
+============
+
+*Description*
+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
+that are considered its contents. These BFDs can be manipulated 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; they will be handled correctly when
+the archive is closed.
+
+ Use `bfd_openr_next_archived_file' to step through the contents of
+an archive opened for input. You don't have to 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 `bfd_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; SunOS 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 case due to restrictions 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.
+
+ Archives are supported in BFD in `archive.c'.
+
+2.8.1 Archive functions
+-----------------------
+
+2.8.1.1 `bfd_get_next_mapent'
+.............................
+
+*Synopsis*
+ symindex bfd_get_next_mapent
+ (bfd *abfd, symindex previous, carsym **sym);
+ *Description*
+Step through archive ABFD's symbol table (if it has one). Successively
+update 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've already got the last one.
+
+ A `carsym' is a canonical archive symbol. The only user-visible
+element is its name, a null-terminated string.
+
+2.8.1.2 `bfd_set_archive_head'
+..............................
+
+*Synopsis*
+ bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head);
+ *Description*
+Set the head of the chain of BFDs contained in the archive OUTPUT to
+NEW_HEAD.
+
+2.8.1.3 `bfd_openr_next_archived_file'
+......................................
+
+*Synopsis*
+ bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous);
+ *Description*
+Provided a BFD, ARCHIVE, containing an archive and NULL, open an input
+BFD on the first contained element and returns that. Subsequent calls
+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: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end
+
+2.9 File formats
+================
+
+A format is a BFD concept of high level file contents type. 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.
+
+2.9.1 File format functions
+---------------------------
+
+2.9.1.1 `bfd_check_format'
+..........................
+
+*Synopsis*
+ bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
+ *Description*
+Verify if the file attached to the BFD ABFD is compatible with the
+format FORMAT (i.e., 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 is checked. If the target has
+not been set, or has been set to `default', then all the known target
+backends is 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:
+
+ * `bfd_error_invalid_operation' - if `format' is not one of
+ `bfd_object', `bfd_archive' or `bfd_core'.
+
+ * `bfd_error_system_call' - if an error occured during a read - even
+ some file mismatches can cause bfd_error_system_calls.
+
+ * `file_not_recognised' - none of the backends recognised the file
+ format.
+
+ * `bfd_error_file_ambiguously_recognized' - more than one backend
+ recognised the file format.
+
+2.9.1.2 `bfd_check_format_matches'
+..................................
+
+*Synopsis*
+ bfd_boolean bfd_check_format_matches
+ (bfd *abfd, bfd_format format, char ***matching);
+ *Description*
+Like `bfd_check_format', except when it returns FALSE with `bfd_errno'
+set to `bfd_error_file_ambiguously_recognized'. In that case, if
+MATCHING is not NULL, it will be filled in with a NULL-terminated list
+of the names of the formats that matched, allocated with `malloc'.
+Then the user may choose a format and try again.
+
+ When done with the list that MATCHING points to, the caller should
+free it.
+
+2.9.1.3 `bfd_set_format'
+........................
+
+*Synopsis*
+ bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
+ *Description*
+This function sets the file format of the BFD ABFD to the format
+FORMAT. If the target set in the BFD does not support the format
+requested, the format is invalid, or the BFD is not open for writing,
+then an error occurs.
+
+2.9.1.4 `bfd_format_string'
+...........................
+
+*Synopsis*
+ const char *bfd_format_string (bfd_format format);
+ *Description*
+Return a pointer to a const string `invalid', `object', `archive',
+`core', or `unknown', depending upon the value of FORMAT.
+
+
+File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end
+
+2.10 Relocations
+================
+
+BFD maintains relocations in much the same way it maintains symbols:
+they are left alone until required, then read in en-masse and
+translated into an internal form. A common routine
+`bfd_perform_relocation' acts upon the canonical form to do the fixup.
+
+ Relocations are maintained on a per section basis, while symbols are
+maintained on a per BFD basis.
+
+ All that a back end has to do to fit the BFD interface is to create
+a `struct reloc_cache_entry' for each relocation in a particular
+section, and fill in the right bits of the structures.
+
+* Menu:
+
+* typedef arelent::
+* howto manager::
+
+
+File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations
+
+2.10.1 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,
+
+ /* Unsupported relocation size requested. */
+ bfd_reloc_notsupported,
+
+ /* Unused. */
+ 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. If this type is returned, the error_message argument
+ to bfd_perform_relocation will be set. */
+ bfd_reloc_dangerous
+ }
+ bfd_reloc_status_type;
+
+
+ typedef struct reloc_cache_entry
+ {
+ /* A pointer into the canonical table of pointers. */
+ struct bfd_symbol **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. */
+ reloc_howto_type *howto;
+
+ }
+ arelent;
+ *Description*
+Here is a description of each of the fields within an `arelent':
+
+ * `sym_ptr_ptr'
+ The symbol table pointer points to a pointer to the symbol
+associated with the relocation request. It is the pointer into the
+table returned by the back end's `canonicalize_symtab' action. *Note
+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 in odd
+sized lumps. The designers of the a.out format chose to not use the
+data within the section for storing part of the offset; all the offset
+is kept within the reloc. Anything 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 contain a pointer to `foo', and the offsets 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 structure which contains information on what to do with
+all of 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.
+
+2.10.1.1 `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 value overflows when considered as a signed
+ number one bit larger than the field. ie. A bitfield of N bits
+ is allowed to represent -2**n to 2**n-1. */
+ complain_overflow_bitfield,
+
+ /* Complain if the value overflows when considered as a signed
+ number. */
+ complain_overflow_signed,
+
+ /* Complain if the value overflows when considered as an
+ unsigned number. */
+ complain_overflow_unsigned
+ };
+
+2.10.1.2 `reloc_howto_type'
+...........................
+
+The `reloc_howto_type' is a structure which contains all the
+information that libbfd needs to know to tie up a back end's data.
+
+ struct bfd_symbol; /* Forward declaration. */
+
+ struct reloc_howto_struct
+ {
+ /* The type field has mainly a documentary use - the back end can
+ do what it wants with it, though normally the back end's
+ external idea of what a reloc number is stored
+ in this field. For example, a PC relative word relocation
+ in a coff environment has 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. To get the number of bytes operated
+ on by a type of relocation, use bfd_get_reloc_size. */
+ 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. */
+ bfd_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 accommodated (e.g., i960 callj
+ instructions). */
+ bfd_reloc_status_type (*special_function)
+ (bfd *, arelent *, struct bfd_symbol *, void *, asection *,
+ bfd *, char **);
+
+ /* The textual name of the relocation type. */
+ char *name;
+
+ /* Some formats record a relocation addend in the section contents
+ rather than with the relocation. For ELF formats this is the
+ distinction between USE_REL and USE_RELA (though the code checks
+ for USE_REL == 1/0). The value of this field is TRUE if the
+ addend is recorded with the section contents; when performing a
+ partial link (ld -r) the section contents (the data) will be
+ modified. The value of this field is FALSE if addends are
+ recorded with the relocation (in arelent.addend); when performing
+ a partial link the relocation will be modified.
+ All relocations for all ELF USE_RELA targets should set this field
+ to FALSE (values of TRUE should be looked on with suspicion).
+ However, the converse is not true: not all relocations of all ELF
+ USE_REL targets set this field to TRUE. Why this is so is peculiar
+ to each particular target. For relocs that aren't used in partial
+ links (e.g. GOT stuff) it doesn't matter what this is set to. */
+ bfd_boolean partial_inplace;
+
+ /* src_mask selects the part of the instruction (or data) to be used
+ in the relocation sum. If the target relocations don't have an
+ addend in the reloc, eg. ELF USE_REL, src_mask will normally equal
+ dst_mask to extract the addend from the section contents. If
+ relocations do have an addend in the reloc, eg. ELF USE_RELA, this
+ field should be zero. Non-zero values for ELF USE_RELA targets are
+ bogus as in those cases the value in the dst_mask part of the
+ section contents should be treated as garbage. */
+ bfd_vma src_mask;
+
+ /* dst_mask selects which parts of the instruction (or data) are
+ replaced with a relocated value. */
+ 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. */
+ bfd_boolean pcrel_offset;
+ };
+
+2.10.1.3 `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*
+This is used to fill in an empty howto entry in an array.
+ #define EMPTY_HOWTO(C) \
+ HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \
+ NULL, FALSE, 0, 0, FALSE)
+
+ *Description*
+Helper routine to turn a symbol into a relocation value.
+ #define HOWTO_PREPARE(relocation, symbol) \
+ { \
+ if (symbol != NULL) \
+ { \
+ if (bfd_is_com_section (symbol->section)) \
+ { \
+ relocation = 0; \
+ } \
+ else \
+ { \
+ relocation = symbol->value; \
+ } \
+ } \
+ }
+
+2.10.1.4 `bfd_get_reloc_size'
+.............................
+
+*Synopsis*
+ unsigned int bfd_get_reloc_size (reloc_howto_type *);
+ *Description*
+For a reloc_howto_type that operates on a fixed number of bytes, this
+returns the number of bytes operated on.
+
+2.10.1.5 `arelent_chain'
+........................
+
+*Description*
+How relocs are tied together in an `asection':
+ typedef struct relent_chain
+ {
+ arelent relent;
+ struct relent_chain *next;
+ }
+ arelent_chain;
+
+2.10.1.6 `bfd_check_overflow'
+.............................
+
+*Synopsis*
+ bfd_reloc_status_type bfd_check_overflow
+ (enum complain_overflow how,
+ unsigned int bitsize,
+ unsigned int rightshift,
+ unsigned int addrsize,
+ bfd_vma relocation);
+ *Description*
+Perform overflow checking on RELOCATION which has BITSIZE significant
+bits and will be shifted right by RIGHTSHIFT bits, on a machine with
+addresses containing ADDRSIZE significant bits. The result is either of
+`bfd_reloc_ok' or `bfd_reloc_overflow'.
+
+2.10.1.7 `bfd_perform_relocation'
+.................................
+
+*Synopsis*
+ bfd_reloc_status_type bfd_perform_relocation
+ (bfd *abfd,
+ arelent *reloc_entry,
+ void *data,
+ asection *input_section,
+ bfd *output_bfd,
+ char **error_message);
+ *Description*
+If 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
+ERROR_MESSAGE argument is set to an error message if this return
+`bfd_reloc_dangerous'.
+
+2.10.1.8 `bfd_install_relocation'
+.................................
+
+*Synopsis*
+ bfd_reloc_status_type bfd_install_relocation
+ (bfd *abfd,
+ arelent *reloc_entry,
+ void *data, bfd_vma data_start,
+ asection *input_section,
+ char **error_message);
+ *Description*
+This looks remarkably like `bfd_perform_relocation', except it does not
+expect that the section contents have been filled in. I.e., it's
+suitable for use when creating, rather than applying a relocation.
+
+ For now, this function should be considered reserved for the
+assembler.
+
+
+File: bfd.info, Node: howto manager, Prev: typedef arelent, Up: Relocations
+
+2.10.2 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.
+
+2.10.2.1 `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.
+
+ Here are the possible values for `enum bfd_reloc_code_real':
+
+ -- : BFD_RELOC_64
+ -- : BFD_RELOC_32
+ -- : BFD_RELOC_26
+ -- : BFD_RELOC_24
+ -- : BFD_RELOC_16
+ -- : BFD_RELOC_14
+ -- : BFD_RELOC_8
+ Basic absolute relocations of N bits.
+
+ -- : BFD_RELOC_64_PCREL
+ -- : BFD_RELOC_32_PCREL
+ -- : BFD_RELOC_24_PCREL
+ -- : BFD_RELOC_16_PCREL
+ -- : BFD_RELOC_12_PCREL
+ -- : BFD_RELOC_8_PCREL
+ PC-relative relocations. Sometimes these are relative to the
+ address of the relocation itself; sometimes they are relative to
+ the start of the section containing the relocation. It depends on
+ the specific target.
+
+ The 24-bit relocation is used in some Intel 960 configurations.
+
+ -- : BFD_RELOC_32_SECREL
+ Section relative relocations. Some targets need this for DWARF2.
+
+ -- : BFD_RELOC_32_GOT_PCREL
+ -- : BFD_RELOC_16_GOT_PCREL
+ -- : BFD_RELOC_8_GOT_PCREL
+ -- : BFD_RELOC_32_GOTOFF
+ -- : BFD_RELOC_16_GOTOFF
+ -- : BFD_RELOC_LO16_GOTOFF
+ -- : BFD_RELOC_HI16_GOTOFF
+ -- : BFD_RELOC_HI16_S_GOTOFF
+ -- : BFD_RELOC_8_GOTOFF
+ -- : BFD_RELOC_64_PLT_PCREL
+ -- : BFD_RELOC_32_PLT_PCREL
+ -- : BFD_RELOC_24_PLT_PCREL
+ -- : BFD_RELOC_16_PLT_PCREL
+ -- : BFD_RELOC_8_PLT_PCREL
+ -- : BFD_RELOC_64_PLTOFF
+ -- : BFD_RELOC_32_PLTOFF
+ -- : BFD_RELOC_16_PLTOFF
+ -- : BFD_RELOC_LO16_PLTOFF
+ -- : BFD_RELOC_HI16_PLTOFF
+ -- : BFD_RELOC_HI16_S_PLTOFF
+ -- : BFD_RELOC_8_PLTOFF
+ For ELF.
+
+ -- : BFD_RELOC_68K_GLOB_DAT
+ -- : BFD_RELOC_68K_JMP_SLOT
+ -- : BFD_RELOC_68K_RELATIVE
+ -- : BFD_RELOC_68K_TLS_GD32
+ -- : BFD_RELOC_68K_TLS_GD16
+ -- : BFD_RELOC_68K_TLS_GD8
+ -- : BFD_RELOC_68K_TLS_LDM32
+ -- : BFD_RELOC_68K_TLS_LDM16
+ -- : BFD_RELOC_68K_TLS_LDM8
+ -- : BFD_RELOC_68K_TLS_LDO32
+ -- : BFD_RELOC_68K_TLS_LDO16
+ -- : BFD_RELOC_68K_TLS_LDO8
+ -- : BFD_RELOC_68K_TLS_IE32
+ -- : BFD_RELOC_68K_TLS_IE16
+ -- : BFD_RELOC_68K_TLS_IE8
+ -- : BFD_RELOC_68K_TLS_LE32
+ -- : BFD_RELOC_68K_TLS_LE16
+ -- : BFD_RELOC_68K_TLS_LE8
+ Relocations used by 68K ELF.
+
+ -- : BFD_RELOC_32_BASEREL
+ -- : BFD_RELOC_16_BASEREL
+ -- : BFD_RELOC_LO16_BASEREL
+ -- : BFD_RELOC_HI16_BASEREL
+ -- : BFD_RELOC_HI16_S_BASEREL
+ -- : BFD_RELOC_8_BASEREL
+ -- : BFD_RELOC_RVA
+ Linkage-table relative.
+
+ -- : BFD_RELOC_8_FFnn
+ Absolute 8-bit relocation, but used to form an address like 0xFFnn.
+
+ -- : BFD_RELOC_32_PCREL_S2
+ -- : BFD_RELOC_16_PCREL_S2
+ -- : BFD_RELOC_23_PCREL_S2
+ These PC-relative relocations are stored as word displacements -
+ i.e., byte displacements shifted right two bits. The 30-bit word
+ displacement (<<32_PCREL_S2>> - 32 bits, shifted 2) is used on the
+ SPARC. (SPARC tools generally refer to this as <<WDISP30>>.) The
+ signed 16-bit displacement is used on the MIPS, and the 23-bit
+ displacement is used on the Alpha.
+
+ -- : BFD_RELOC_HI22
+ -- : BFD_RELOC_LO10
+ High 22 bits and low 10 bits of 32-bit value, placed into lower
+ bits of the target word. These are used on the SPARC.
+
+ -- : BFD_RELOC_GPREL16
+ -- : BFD_RELOC_GPREL32
+ For systems that allocate a Global Pointer register, these are
+ displacements off that register. These relocation types are
+ handled specially, because the value the register will have is
+ decided relatively late.
+
+ -- : BFD_RELOC_I960_CALLJ
+ Reloc types used for i960/b.out.
+
+ -- : BFD_RELOC_NONE
+ -- : 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_UA16
+ -- : BFD_RELOC_SPARC_UA32
+ -- : BFD_RELOC_SPARC_UA64
+ -- : BFD_RELOC_SPARC_GOTDATA_HIX22
+ -- : BFD_RELOC_SPARC_GOTDATA_LOX10
+ -- : BFD_RELOC_SPARC_GOTDATA_OP_HIX22
+ -- : BFD_RELOC_SPARC_GOTDATA_OP_LOX10
+ -- : BFD_RELOC_SPARC_GOTDATA_OP
+ SPARC ELF relocations. There is probably some overlap with other
+ relocation types already defined.
+
+ -- : BFD_RELOC_SPARC_BASE13
+ -- : BFD_RELOC_SPARC_BASE22
+ I think these are specific to SPARC a.out (e.g., Sun 4).
+
+ -- : BFD_RELOC_SPARC_64
+ -- : BFD_RELOC_SPARC_10
+ -- : BFD_RELOC_SPARC_11
+ -- : BFD_RELOC_SPARC_OLO10
+ -- : BFD_RELOC_SPARC_HH22
+ -- : BFD_RELOC_SPARC_HM10
+ -- : BFD_RELOC_SPARC_LM22
+ -- : BFD_RELOC_SPARC_PC_HH22
+ -- : BFD_RELOC_SPARC_PC_HM10
+ -- : BFD_RELOC_SPARC_PC_LM22
+ -- : BFD_RELOC_SPARC_WDISP16
+ -- : BFD_RELOC_SPARC_WDISP19
+ -- : BFD_RELOC_SPARC_7
+ -- : BFD_RELOC_SPARC_6
+ -- : BFD_RELOC_SPARC_5
+ -- : BFD_RELOC_SPARC_DISP64
+ -- : BFD_RELOC_SPARC_PLT32
+ -- : BFD_RELOC_SPARC_PLT64
+ -- : BFD_RELOC_SPARC_HIX22
+ -- : BFD_RELOC_SPARC_LOX10
+ -- : BFD_RELOC_SPARC_H44
+ -- : BFD_RELOC_SPARC_M44
+ -- : BFD_RELOC_SPARC_L44
+ -- : BFD_RELOC_SPARC_REGISTER
+ SPARC64 relocations
+
+ -- : BFD_RELOC_SPARC_REV32
+ SPARC little endian relocation
+
+ -- : BFD_RELOC_SPARC_TLS_GD_HI22
+ -- : BFD_RELOC_SPARC_TLS_GD_LO10
+ -- : BFD_RELOC_SPARC_TLS_GD_ADD
+ -- : BFD_RELOC_SPARC_TLS_GD_CALL
+ -- : BFD_RELOC_SPARC_TLS_LDM_HI22
+ -- : BFD_RELOC_SPARC_TLS_LDM_LO10
+ -- : BFD_RELOC_SPARC_TLS_LDM_ADD
+ -- : BFD_RELOC_SPARC_TLS_LDM_CALL
+ -- : BFD_RELOC_SPARC_TLS_LDO_HIX22
+ -- : BFD_RELOC_SPARC_TLS_LDO_LOX10
+ -- : BFD_RELOC_SPARC_TLS_LDO_ADD
+ -- : BFD_RELOC_SPARC_TLS_IE_HI22
+ -- : BFD_RELOC_SPARC_TLS_IE_LO10
+ -- : BFD_RELOC_SPARC_TLS_IE_LD
+ -- : BFD_RELOC_SPARC_TLS_IE_LDX
+ -- : BFD_RELOC_SPARC_TLS_IE_ADD
+ -- : BFD_RELOC_SPARC_TLS_LE_HIX22
+ -- : BFD_RELOC_SPARC_TLS_LE_LOX10
+ -- : BFD_RELOC_SPARC_TLS_DTPMOD32
+ -- : BFD_RELOC_SPARC_TLS_DTPMOD64
+ -- : BFD_RELOC_SPARC_TLS_DTPOFF32
+ -- : BFD_RELOC_SPARC_TLS_DTPOFF64
+ -- : BFD_RELOC_SPARC_TLS_TPOFF32
+ -- : BFD_RELOC_SPARC_TLS_TPOFF64
+ SPARC TLS relocations
+
+ -- : BFD_RELOC_SPU_IMM7
+ -- : BFD_RELOC_SPU_IMM8
+ -- : BFD_RELOC_SPU_IMM10
+ -- : BFD_RELOC_SPU_IMM10W
+ -- : BFD_RELOC_SPU_IMM16
+ -- : BFD_RELOC_SPU_IMM16W
+ -- : BFD_RELOC_SPU_IMM18
+ -- : BFD_RELOC_SPU_PCREL9a
+ -- : BFD_RELOC_SPU_PCREL9b
+ -- : BFD_RELOC_SPU_PCREL16
+ -- : BFD_RELOC_SPU_LO16
+ -- : BFD_RELOC_SPU_HI16
+ -- : BFD_RELOC_SPU_PPU32
+ -- : BFD_RELOC_SPU_PPU64
+ -- : BFD_RELOC_SPU_ADD_PIC
+ SPU Relocations.
+
+ -- : BFD_RELOC_ALPHA_GPDISP_HI16
+ Alpha ECOFF and ELF relocations. Some of these treat the symbol or
+ "addend" in some special way. For GPDISP_HI16 ("gpdisp")
+ relocations, the symbol is ignored when writing; when reading, it
+ will be the absolute section symbol. The addend is the
+ displacement in bytes of the "lda" instruction from the "ldah"
+ instruction (which is at the address of this reloc).
+
+ -- : BFD_RELOC_ALPHA_GPDISP_LO16
+ For GPDISP_LO16 ("ignore") relocations, the symbol is handled as
+ with GPDISP_HI16 relocs. The addend is ignored when writing the
+ relocations out, and is filled in with the file's GP value on
+ reading, for convenience.
+
+ -- : BFD_RELOC_ALPHA_GPDISP
+ The ELF GPDISP relocation is exactly the same as the GPDISP_HI16
+ relocation except that there is no accompanying GPDISP_LO16
+ relocation.
+
+ -- : BFD_RELOC_ALPHA_LITERAL
+ -- : BFD_RELOC_ALPHA_ELF_LITERAL
+ -- : BFD_RELOC_ALPHA_LITUSE
+ The Alpha LITERAL/LITUSE relocs are produced by a symbol reference;
+ the assembler turns it into a LDQ instruction to load the address
+ of the symbol, and then fills in a register in the real
+ instruction.
+
+ The LITERAL reloc, at the LDQ instruction, refers to the .lita
+ section symbol. The addend is ignored when writing, but is filled
+ in with the file's GP value on reading, for convenience, as with
+ the GPDISP_LO16 reloc.
+
+ The ELF_LITERAL reloc is somewhere between 16_GOTOFF and
+ GPDISP_LO16. It should refer to the symbol to be referenced, as
+ with 16_GOTOFF, but it generates output not based on the position
+ within the .got section, but relative to the GP value chosen for
+ the file during the final link stage.
+
+ The LITUSE reloc, on the instruction using the loaded address,
+ gives information to the linker that it might be able to use to
+ optimize away some literal section references. The symbol is
+ ignored (read as the absolute section symbol), and the "addend"
+ indicates the type of instruction using the register: 1 - "memory"
+ fmt insn 2 - byte-manipulation (byte offset reg) 3 - jsr (target
+ of branch)
+
+ -- : BFD_RELOC_ALPHA_HINT
+ The HINT relocation indicates a value that should be filled into
+ the "hint" field of a jmp/jsr/ret instruction, for possible branch-
+ prediction logic which may be provided on some processors.
+
+ -- : BFD_RELOC_ALPHA_LINKAGE
+ The LINKAGE relocation outputs a linkage pair in the object file,
+ which is filled by the linker.
+
+ -- : BFD_RELOC_ALPHA_CODEADDR
+ The CODEADDR relocation outputs a STO_CA in the object file, which
+ is filled by the linker.
+
+ -- : BFD_RELOC_ALPHA_GPREL_HI16
+ -- : BFD_RELOC_ALPHA_GPREL_LO16
+ The GPREL_HI/LO relocations together form a 32-bit offset from the
+ GP register.
+
+ -- : BFD_RELOC_ALPHA_BRSGP
+ Like BFD_RELOC_23_PCREL_S2, except that the source and target must
+ share a common GP, and the target address is adjusted for
+ STO_ALPHA_STD_GPLOAD.
+
+ -- : BFD_RELOC_ALPHA_NOP
+ The NOP relocation outputs a NOP if the longword displacement
+ between two procedure entry points is < 2^21.
+
+ -- : BFD_RELOC_ALPHA_BSR
+ The BSR relocation outputs a BSR if the longword displacement
+ between two procedure entry points is < 2^21.
+
+ -- : BFD_RELOC_ALPHA_LDA
+ The LDA relocation outputs a LDA if the longword displacement
+ between two procedure entry points is < 2^16.
+
+ -- : BFD_RELOC_ALPHA_BOH
+ The BOH relocation outputs a BSR if the longword displacement
+ between two procedure entry points is < 2^21, or else a hint.
+
+ -- : BFD_RELOC_ALPHA_TLSGD
+ -- : BFD_RELOC_ALPHA_TLSLDM
+ -- : BFD_RELOC_ALPHA_DTPMOD64
+ -- : BFD_RELOC_ALPHA_GOTDTPREL16
+ -- : BFD_RELOC_ALPHA_DTPREL64
+ -- : BFD_RELOC_ALPHA_DTPREL_HI16
+ -- : BFD_RELOC_ALPHA_DTPREL_LO16
+ -- : BFD_RELOC_ALPHA_DTPREL16
+ -- : BFD_RELOC_ALPHA_GOTTPREL16
+ -- : BFD_RELOC_ALPHA_TPREL64
+ -- : BFD_RELOC_ALPHA_TPREL_HI16
+ -- : BFD_RELOC_ALPHA_TPREL_LO16
+ -- : BFD_RELOC_ALPHA_TPREL16
+ Alpha thread-local storage relocations.
+
+ -- : BFD_RELOC_MIPS_JMP
+ Bits 27..2 of the relocation address shifted right 2 bits; simple
+ reloc otherwise.
+
+ -- : BFD_RELOC_MIPS16_JMP
+ The MIPS16 jump instruction.
+
+ -- : BFD_RELOC_MIPS16_GPREL
+ MIPS16 GP relative reloc.
+
+ -- : BFD_RELOC_HI16
+ High 16 bits of 32-bit value; simple reloc.
+
+ -- : BFD_RELOC_HI16_S
+ 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_LO16
+ Low 16 bits.
+
+ -- : BFD_RELOC_HI16_PCREL
+ High 16 bits of 32-bit pc-relative value
+
+ -- : BFD_RELOC_HI16_S_PCREL
+ High 16 bits of 32-bit pc-relative value, adjusted
+
+ -- : BFD_RELOC_LO16_PCREL
+ Low 16 bits of pc-relative value
+
+ -- : BFD_RELOC_MIPS16_GOT16
+ -- : BFD_RELOC_MIPS16_CALL16
+ Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of
+ 16-bit immediate fields
+
+ -- : BFD_RELOC_MIPS16_HI16
+ MIPS16 high 16 bits of 32-bit value.
+
+ -- : BFD_RELOC_MIPS16_HI16_S
+ MIPS16 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_MIPS16_LO16
+ MIPS16 low 16 bits.
+
+ -- : BFD_RELOC_MIPS_LITERAL
+ Relocation against a MIPS literal section.
+
+ -- : BFD_RELOC_MIPS_GOT16
+ -- : BFD_RELOC_MIPS_CALL16
+ -- : BFD_RELOC_MIPS_GOT_HI16
+ -- : BFD_RELOC_MIPS_GOT_LO16
+ -- : BFD_RELOC_MIPS_CALL_HI16
+ -- : BFD_RELOC_MIPS_CALL_LO16
+ -- : BFD_RELOC_MIPS_SUB
+ -- : BFD_RELOC_MIPS_GOT_PAGE
+ -- : BFD_RELOC_MIPS_GOT_OFST
+ -- : BFD_RELOC_MIPS_GOT_DISP
+ -- : BFD_RELOC_MIPS_SHIFT5
+ -- : BFD_RELOC_MIPS_SHIFT6
+ -- : BFD_RELOC_MIPS_INSERT_A
+ -- : BFD_RELOC_MIPS_INSERT_B
+ -- : BFD_RELOC_MIPS_DELETE
+ -- : BFD_RELOC_MIPS_HIGHEST
+ -- : BFD_RELOC_MIPS_HIGHER
+ -- : BFD_RELOC_MIPS_SCN_DISP
+ -- : BFD_RELOC_MIPS_REL16
+ -- : BFD_RELOC_MIPS_RELGOT
+ -- : BFD_RELOC_MIPS_JALR
+ -- : BFD_RELOC_MIPS_TLS_DTPMOD32
+ -- : BFD_RELOC_MIPS_TLS_DTPREL32
+ -- : BFD_RELOC_MIPS_TLS_DTPMOD64
+ -- : BFD_RELOC_MIPS_TLS_DTPREL64
+ -- : BFD_RELOC_MIPS_TLS_GD
+ -- : BFD_RELOC_MIPS_TLS_LDM
+ -- : BFD_RELOC_MIPS_TLS_DTPREL_HI16
+ -- : BFD_RELOC_MIPS_TLS_DTPREL_LO16
+ -- : BFD_RELOC_MIPS_TLS_GOTTPREL
+ -- : BFD_RELOC_MIPS_TLS_TPREL32
+ -- : BFD_RELOC_MIPS_TLS_TPREL64
+ -- : BFD_RELOC_MIPS_TLS_TPREL_HI16
+ -- : BFD_RELOC_MIPS_TLS_TPREL_LO16
+ MIPS ELF relocations.
+
+ -- : BFD_RELOC_MIPS_COPY
+ -- : BFD_RELOC_MIPS_JUMP_SLOT
+ MIPS ELF relocations (VxWorks and PLT extensions).
+
+ -- : BFD_RELOC_MOXIE_10_PCREL
+ Moxie ELF relocations.
+
+ -- : BFD_RELOC_FRV_LABEL16
+ -- : BFD_RELOC_FRV_LABEL24
+ -- : BFD_RELOC_FRV_LO16
+ -- : BFD_RELOC_FRV_HI16
+ -- : BFD_RELOC_FRV_GPREL12
+ -- : BFD_RELOC_FRV_GPRELU12
+ -- : BFD_RELOC_FRV_GPREL32
+ -- : BFD_RELOC_FRV_GPRELHI
+ -- : BFD_RELOC_FRV_GPRELLO
+ -- : BFD_RELOC_FRV_GOT12
+ -- : BFD_RELOC_FRV_GOTHI
+ -- : BFD_RELOC_FRV_GOTLO
+ -- : BFD_RELOC_FRV_FUNCDESC
+ -- : BFD_RELOC_FRV_FUNCDESC_GOT12
+ -- : BFD_RELOC_FRV_FUNCDESC_GOTHI
+ -- : BFD_RELOC_FRV_FUNCDESC_GOTLO
+ -- : BFD_RELOC_FRV_FUNCDESC_VALUE
+ -- : BFD_RELOC_FRV_FUNCDESC_GOTOFF12
+ -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFHI
+ -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFLO
+ -- : BFD_RELOC_FRV_GOTOFF12
+ -- : BFD_RELOC_FRV_GOTOFFHI
+ -- : BFD_RELOC_FRV_GOTOFFLO
+ -- : BFD_RELOC_FRV_GETTLSOFF
+ -- : BFD_RELOC_FRV_TLSDESC_VALUE
+ -- : BFD_RELOC_FRV_GOTTLSDESC12
+ -- : BFD_RELOC_FRV_GOTTLSDESCHI
+ -- : BFD_RELOC_FRV_GOTTLSDESCLO
+ -- : BFD_RELOC_FRV_TLSMOFF12
+ -- : BFD_RELOC_FRV_TLSMOFFHI
+ -- : BFD_RELOC_FRV_TLSMOFFLO
+ -- : BFD_RELOC_FRV_GOTTLSOFF12
+ -- : BFD_RELOC_FRV_GOTTLSOFFHI
+ -- : BFD_RELOC_FRV_GOTTLSOFFLO
+ -- : BFD_RELOC_FRV_TLSOFF
+ -- : BFD_RELOC_FRV_TLSDESC_RELAX
+ -- : BFD_RELOC_FRV_GETTLSOFF_RELAX
+ -- : BFD_RELOC_FRV_TLSOFF_RELAX
+ -- : BFD_RELOC_FRV_TLSMOFF
+ Fujitsu Frv Relocations.
+
+ -- : BFD_RELOC_MN10300_GOTOFF24
+ This is a 24bit GOT-relative reloc for the mn10300.
+
+ -- : BFD_RELOC_MN10300_GOT32
+ This is a 32bit GOT-relative reloc for the mn10300, offset by two
+ bytes in the instruction.
+
+ -- : BFD_RELOC_MN10300_GOT24
+ This is a 24bit GOT-relative reloc for the mn10300, offset by two
+ bytes in the instruction.
+
+ -- : BFD_RELOC_MN10300_GOT16
+ This is a 16bit GOT-relative reloc for the mn10300, offset by two
+ bytes in the instruction.
+
+ -- : BFD_RELOC_MN10300_COPY
+ Copy symbol at runtime.
+
+ -- : BFD_RELOC_MN10300_GLOB_DAT
+ Create GOT entry.
+
+ -- : BFD_RELOC_MN10300_JMP_SLOT
+ Create PLT entry.
+
+ -- : BFD_RELOC_MN10300_RELATIVE
+ Adjust by program base.
+
+ -- : BFD_RELOC_MN10300_SYM_DIFF
+ Together with another reloc targeted at the same location, allows
+ for a value that is the difference of two symbols in the same
+ section.
+
+ -- : BFD_RELOC_MN10300_ALIGN
+ The addend of this reloc is an alignment power that must be
+ honoured at the offset's location, regardless of linker relaxation.
+
+ -- : 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
+ -- : BFD_RELOC_386_TLS_TPOFF
+ -- : BFD_RELOC_386_TLS_IE
+ -- : BFD_RELOC_386_TLS_GOTIE
+ -- : BFD_RELOC_386_TLS_LE
+ -- : BFD_RELOC_386_TLS_GD
+ -- : BFD_RELOC_386_TLS_LDM
+ -- : BFD_RELOC_386_TLS_LDO_32
+ -- : BFD_RELOC_386_TLS_IE_32
+ -- : BFD_RELOC_386_TLS_LE_32
+ -- : BFD_RELOC_386_TLS_DTPMOD32
+ -- : BFD_RELOC_386_TLS_DTPOFF32
+ -- : BFD_RELOC_386_TLS_TPOFF32
+ -- : BFD_RELOC_386_TLS_GOTDESC
+ -- : BFD_RELOC_386_TLS_DESC_CALL
+ -- : BFD_RELOC_386_TLS_DESC
+ -- : BFD_RELOC_386_IRELATIVE
+ i386/elf relocations
+
+ -- : BFD_RELOC_X86_64_GOT32
+ -- : BFD_RELOC_X86_64_PLT32
+ -- : BFD_RELOC_X86_64_COPY
+ -- : BFD_RELOC_X86_64_GLOB_DAT
+ -- : BFD_RELOC_X86_64_JUMP_SLOT
+ -- : BFD_RELOC_X86_64_RELATIVE
+ -- : BFD_RELOC_X86_64_GOTPCREL
+ -- : BFD_RELOC_X86_64_32S
+ -- : BFD_RELOC_X86_64_DTPMOD64
+ -- : BFD_RELOC_X86_64_DTPOFF64
+ -- : BFD_RELOC_X86_64_TPOFF64
+ -- : BFD_RELOC_X86_64_TLSGD
+ -- : BFD_RELOC_X86_64_TLSLD
+ -- : BFD_RELOC_X86_64_DTPOFF32
+ -- : BFD_RELOC_X86_64_GOTTPOFF
+ -- : BFD_RELOC_X86_64_TPOFF32
+ -- : BFD_RELOC_X86_64_GOTOFF64
+ -- : BFD_RELOC_X86_64_GOTPC32
+ -- : BFD_RELOC_X86_64_GOT64
+ -- : BFD_RELOC_X86_64_GOTPCREL64
+ -- : BFD_RELOC_X86_64_GOTPC64
+ -- : BFD_RELOC_X86_64_GOTPLT64
+ -- : BFD_RELOC_X86_64_PLTOFF64
+ -- : BFD_RELOC_X86_64_GOTPC32_TLSDESC
+ -- : BFD_RELOC_X86_64_TLSDESC_CALL
+ -- : BFD_RELOC_X86_64_TLSDESC
+ -- : BFD_RELOC_X86_64_IRELATIVE
+ x86-64/elf relocations
+
+ -- : BFD_RELOC_NS32K_IMM_8
+ -- : BFD_RELOC_NS32K_IMM_16
+ -- : BFD_RELOC_NS32K_IMM_32
+ -- : BFD_RELOC_NS32K_IMM_8_PCREL
+ -- : BFD_RELOC_NS32K_IMM_16_PCREL
+ -- : BFD_RELOC_NS32K_IMM_32_PCREL
+ -- : BFD_RELOC_NS32K_DISP_8
+ -- : BFD_RELOC_NS32K_DISP_16
+ -- : BFD_RELOC_NS32K_DISP_32
+ -- : BFD_RELOC_NS32K_DISP_8_PCREL
+ -- : BFD_RELOC_NS32K_DISP_16_PCREL
+ -- : BFD_RELOC_NS32K_DISP_32_PCREL
+ ns32k relocations
+
+ -- : BFD_RELOC_PDP11_DISP_8_PCREL
+ -- : BFD_RELOC_PDP11_DISP_6_PCREL
+ PDP11 relocations
+
+ -- : BFD_RELOC_PJ_CODE_HI16
+ -- : BFD_RELOC_PJ_CODE_LO16
+ -- : BFD_RELOC_PJ_CODE_DIR16
+ -- : BFD_RELOC_PJ_CODE_DIR32
+ -- : BFD_RELOC_PJ_CODE_REL16
+ -- : BFD_RELOC_PJ_CODE_REL32
+ Picojava relocs. Not all of these appear in object files.
+
+ -- : BFD_RELOC_PPC_B26
+ -- : BFD_RELOC_PPC_BA26
+ -- : BFD_RELOC_PPC_TOC16
+ -- : BFD_RELOC_PPC_B16
+ -- : BFD_RELOC_PPC_B16_BRTAKEN
+ -- : BFD_RELOC_PPC_B16_BRNTAKEN
+ -- : BFD_RELOC_PPC_BA16
+ -- : BFD_RELOC_PPC_BA16_BRTAKEN
+ -- : BFD_RELOC_PPC_BA16_BRNTAKEN
+ -- : BFD_RELOC_PPC_COPY
+ -- : BFD_RELOC_PPC_GLOB_DAT
+ -- : BFD_RELOC_PPC_JMP_SLOT
+ -- : BFD_RELOC_PPC_RELATIVE
+ -- : BFD_RELOC_PPC_LOCAL24PC
+ -- : BFD_RELOC_PPC_EMB_NADDR32
+ -- : BFD_RELOC_PPC_EMB_NADDR16
+ -- : BFD_RELOC_PPC_EMB_NADDR16_LO
+ -- : BFD_RELOC_PPC_EMB_NADDR16_HI
+ -- : BFD_RELOC_PPC_EMB_NADDR16_HA
+ -- : BFD_RELOC_PPC_EMB_SDAI16
+ -- : BFD_RELOC_PPC_EMB_SDA2I16
+ -- : BFD_RELOC_PPC_EMB_SDA2REL
+ -- : BFD_RELOC_PPC_EMB_SDA21
+ -- : BFD_RELOC_PPC_EMB_MRKREF
+ -- : BFD_RELOC_PPC_EMB_RELSEC16
+ -- : BFD_RELOC_PPC_EMB_RELST_LO
+ -- : BFD_RELOC_PPC_EMB_RELST_HI
+ -- : BFD_RELOC_PPC_EMB_RELST_HA
+ -- : BFD_RELOC_PPC_EMB_BIT_FLD
+ -- : BFD_RELOC_PPC_EMB_RELSDA
+ -- : BFD_RELOC_PPC64_HIGHER
+ -- : BFD_RELOC_PPC64_HIGHER_S
+ -- : BFD_RELOC_PPC64_HIGHEST
+ -- : BFD_RELOC_PPC64_HIGHEST_S
+ -- : BFD_RELOC_PPC64_TOC16_LO
+ -- : BFD_RELOC_PPC64_TOC16_HI
+ -- : BFD_RELOC_PPC64_TOC16_HA
+ -- : BFD_RELOC_PPC64_TOC
+ -- : BFD_RELOC_PPC64_PLTGOT16
+ -- : BFD_RELOC_PPC64_PLTGOT16_LO
+ -- : BFD_RELOC_PPC64_PLTGOT16_HI
+ -- : BFD_RELOC_PPC64_PLTGOT16_HA
+ -- : BFD_RELOC_PPC64_ADDR16_DS
+ -- : BFD_RELOC_PPC64_ADDR16_LO_DS
+ -- : BFD_RELOC_PPC64_GOT16_DS
+ -- : BFD_RELOC_PPC64_GOT16_LO_DS
+ -- : BFD_RELOC_PPC64_PLT16_LO_DS
+ -- : BFD_RELOC_PPC64_SECTOFF_DS
+ -- : BFD_RELOC_PPC64_SECTOFF_LO_DS
+ -- : BFD_RELOC_PPC64_TOC16_DS
+ -- : BFD_RELOC_PPC64_TOC16_LO_DS
+ -- : BFD_RELOC_PPC64_PLTGOT16_DS
+ -- : BFD_RELOC_PPC64_PLTGOT16_LO_DS
+ Power(rs6000) and PowerPC relocations.
+
+ -- : BFD_RELOC_PPC_TLS
+ -- : BFD_RELOC_PPC_TLSGD
+ -- : BFD_RELOC_PPC_TLSLD
+ -- : BFD_RELOC_PPC_DTPMOD
+ -- : BFD_RELOC_PPC_TPREL16
+ -- : BFD_RELOC_PPC_TPREL16_LO
+ -- : BFD_RELOC_PPC_TPREL16_HI
+ -- : BFD_RELOC_PPC_TPREL16_HA
+ -- : BFD_RELOC_PPC_TPREL
+ -- : BFD_RELOC_PPC_DTPREL16
+ -- : BFD_RELOC_PPC_DTPREL16_LO
+ -- : BFD_RELOC_PPC_DTPREL16_HI
+ -- : BFD_RELOC_PPC_DTPREL16_HA
+ -- : BFD_RELOC_PPC_DTPREL
+ -- : BFD_RELOC_PPC_GOT_TLSGD16
+ -- : BFD_RELOC_PPC_GOT_TLSGD16_LO
+ -- : BFD_RELOC_PPC_GOT_TLSGD16_HI
+ -- : BFD_RELOC_PPC_GOT_TLSGD16_HA
+ -- : BFD_RELOC_PPC_GOT_TLSLD16
+ -- : BFD_RELOC_PPC_GOT_TLSLD16_LO
+ -- : BFD_RELOC_PPC_GOT_TLSLD16_HI
+ -- : BFD_RELOC_PPC_GOT_TLSLD16_HA
+ -- : BFD_RELOC_PPC_GOT_TPREL16
+ -- : BFD_RELOC_PPC_GOT_TPREL16_LO
+ -- : BFD_RELOC_PPC_GOT_TPREL16_HI
+ -- : BFD_RELOC_PPC_GOT_TPREL16_HA
+ -- : BFD_RELOC_PPC_GOT_DTPREL16
+ -- : BFD_RELOC_PPC_GOT_DTPREL16_LO
+ -- : BFD_RELOC_PPC_GOT_DTPREL16_HI
+ -- : BFD_RELOC_PPC_GOT_DTPREL16_HA
+ -- : BFD_RELOC_PPC64_TPREL16_DS
+ -- : BFD_RELOC_PPC64_TPREL16_LO_DS
+ -- : BFD_RELOC_PPC64_TPREL16_HIGHER
+ -- : BFD_RELOC_PPC64_TPREL16_HIGHERA
+ -- : BFD_RELOC_PPC64_TPREL16_HIGHEST
+ -- : BFD_RELOC_PPC64_TPREL16_HIGHESTA
+ -- : BFD_RELOC_PPC64_DTPREL16_DS
+ -- : BFD_RELOC_PPC64_DTPREL16_LO_DS
+ -- : BFD_RELOC_PPC64_DTPREL16_HIGHER
+ -- : BFD_RELOC_PPC64_DTPREL16_HIGHERA
+ -- : BFD_RELOC_PPC64_DTPREL16_HIGHEST
+ -- : BFD_RELOC_PPC64_DTPREL16_HIGHESTA
+ PowerPC and PowerPC64 thread-local storage relocations.
+
+ -- : BFD_RELOC_I370_D12
+ IBM 370/390 relocations
+
+ -- : BFD_RELOC_CTOR
+ The type of reloc used to build a constructor table - at the moment
+ probably a 32 bit wide absolute relocation, but the target can
+ choose. It generally does map to one of the other relocation
+ types.
+
+ -- : BFD_RELOC_ARM_PCREL_BRANCH
+ ARM 26 bit pc-relative branch. The lowest two bits must be zero
+ and are not stored in the instruction.
+
+ -- : BFD_RELOC_ARM_PCREL_BLX
+ ARM 26 bit pc-relative branch. The lowest bit must be zero and is
+ not stored in the instruction. The 2nd lowest bit comes from a 1
+ bit field in the instruction.
+
+ -- : BFD_RELOC_THUMB_PCREL_BLX
+ Thumb 22 bit pc-relative branch. The lowest bit must be zero and
+ is not stored in the instruction. The 2nd lowest bit comes from a
+ 1 bit field in the instruction.
+
+ -- : BFD_RELOC_ARM_PCREL_CALL
+ ARM 26-bit pc-relative branch for an unconditional BL or BLX
+ instruction.
+
+ -- : BFD_RELOC_ARM_PCREL_JUMP
+ ARM 26-bit pc-relative branch for B or conditional BL instruction.
+
+ -- : BFD_RELOC_THUMB_PCREL_BRANCH7
+ -- : BFD_RELOC_THUMB_PCREL_BRANCH9
+ -- : BFD_RELOC_THUMB_PCREL_BRANCH12
+ -- : BFD_RELOC_THUMB_PCREL_BRANCH20
+ -- : BFD_RELOC_THUMB_PCREL_BRANCH23
+ -- : BFD_RELOC_THUMB_PCREL_BRANCH25
+ Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches. The
+ lowest bit must be zero and is not stored in the instruction.
+ Note that the corresponding ELF R_ARM_THM_JUMPnn constant has an
+ "nn" one smaller in all cases. Note further that BRANCH23
+ corresponds to R_ARM_THM_CALL.
+
+ -- : BFD_RELOC_ARM_OFFSET_IMM
+ 12-bit immediate offset, used in ARM-format ldr and str
+ instructions.
+
+ -- : BFD_RELOC_ARM_THUMB_OFFSET
+ 5-bit immediate offset, used in Thumb-format ldr and str
+ instructions.
+
+ -- : BFD_RELOC_ARM_TARGET1
+ Pc-relative or absolute relocation depending on target. Used for
+ entries in .init_array sections.
+
+ -- : BFD_RELOC_ARM_ROSEGREL32
+ Read-only segment base relative address.
+
+ -- : BFD_RELOC_ARM_SBREL32
+ Data segment base relative address.
+
+ -- : BFD_RELOC_ARM_TARGET2
+ This reloc is used for references to RTTI data from exception
+ handling tables. The actual definition depends on the target. It
+ may be a pc-relative or some form of GOT-indirect relocation.
+
+ -- : BFD_RELOC_ARM_PREL31
+ 31-bit PC relative address.
+
+ -- : BFD_RELOC_ARM_MOVW
+ -- : BFD_RELOC_ARM_MOVT
+ -- : BFD_RELOC_ARM_MOVW_PCREL
+ -- : BFD_RELOC_ARM_MOVT_PCREL
+ -- : BFD_RELOC_ARM_THUMB_MOVW
+ -- : BFD_RELOC_ARM_THUMB_MOVT
+ -- : BFD_RELOC_ARM_THUMB_MOVW_PCREL
+ -- : BFD_RELOC_ARM_THUMB_MOVT_PCREL
+ Low and High halfword relocations for MOVW and MOVT instructions.
+
+ -- : BFD_RELOC_ARM_JUMP_SLOT
+ -- : BFD_RELOC_ARM_GLOB_DAT
+ -- : BFD_RELOC_ARM_GOT32
+ -- : BFD_RELOC_ARM_PLT32
+ -- : BFD_RELOC_ARM_RELATIVE
+ -- : BFD_RELOC_ARM_GOTOFF
+ -- : BFD_RELOC_ARM_GOTPC
+ Relocations for setting up GOTs and PLTs for shared libraries.
+
+ -- : BFD_RELOC_ARM_TLS_GD32
+ -- : BFD_RELOC_ARM_TLS_LDO32
+ -- : BFD_RELOC_ARM_TLS_LDM32
+ -- : BFD_RELOC_ARM_TLS_DTPOFF32
+ -- : BFD_RELOC_ARM_TLS_DTPMOD32
+ -- : BFD_RELOC_ARM_TLS_TPOFF32
+ -- : BFD_RELOC_ARM_TLS_IE32
+ -- : BFD_RELOC_ARM_TLS_LE32
+ ARM thread-local storage relocations.
+
+ -- : BFD_RELOC_ARM_ALU_PC_G0_NC
+ -- : BFD_RELOC_ARM_ALU_PC_G0
+ -- : BFD_RELOC_ARM_ALU_PC_G1_NC
+ -- : BFD_RELOC_ARM_ALU_PC_G1
+ -- : BFD_RELOC_ARM_ALU_PC_G2
+ -- : BFD_RELOC_ARM_LDR_PC_G0
+ -- : BFD_RELOC_ARM_LDR_PC_G1
+ -- : BFD_RELOC_ARM_LDR_PC_G2
+ -- : BFD_RELOC_ARM_LDRS_PC_G0
+ -- : BFD_RELOC_ARM_LDRS_PC_G1
+ -- : BFD_RELOC_ARM_LDRS_PC_G2
+ -- : BFD_RELOC_ARM_LDC_PC_G0
+ -- : BFD_RELOC_ARM_LDC_PC_G1
+ -- : BFD_RELOC_ARM_LDC_PC_G2
+ -- : BFD_RELOC_ARM_ALU_SB_G0_NC
+ -- : BFD_RELOC_ARM_ALU_SB_G0
+ -- : BFD_RELOC_ARM_ALU_SB_G1_NC
+ -- : BFD_RELOC_ARM_ALU_SB_G1
+ -- : BFD_RELOC_ARM_ALU_SB_G2
+ -- : BFD_RELOC_ARM_LDR_SB_G0
+ -- : BFD_RELOC_ARM_LDR_SB_G1
+ -- : BFD_RELOC_ARM_LDR_SB_G2
+ -- : BFD_RELOC_ARM_LDRS_SB_G0
+ -- : BFD_RELOC_ARM_LDRS_SB_G1
+ -- : BFD_RELOC_ARM_LDRS_SB_G2
+ -- : BFD_RELOC_ARM_LDC_SB_G0
+ -- : BFD_RELOC_ARM_LDC_SB_G1
+ -- : BFD_RELOC_ARM_LDC_SB_G2
+ ARM group relocations.
+
+ -- : BFD_RELOC_ARM_V4BX
+ Annotation of BX instructions.
+
+ -- : BFD_RELOC_ARM_IMMEDIATE
+ -- : BFD_RELOC_ARM_ADRL_IMMEDIATE
+ -- : BFD_RELOC_ARM_T32_IMMEDIATE
+ -- : BFD_RELOC_ARM_T32_ADD_IMM
+ -- : BFD_RELOC_ARM_T32_IMM12
+ -- : BFD_RELOC_ARM_T32_ADD_PC12
+ -- : BFD_RELOC_ARM_SHIFT_IMM
+ -- : BFD_RELOC_ARM_SMC
+ -- : BFD_RELOC_ARM_SWI
+ -- : BFD_RELOC_ARM_MULTI
+ -- : BFD_RELOC_ARM_CP_OFF_IMM
+ -- : BFD_RELOC_ARM_CP_OFF_IMM_S2
+ -- : BFD_RELOC_ARM_T32_CP_OFF_IMM
+ -- : BFD_RELOC_ARM_T32_CP_OFF_IMM_S2
+ -- : BFD_RELOC_ARM_ADR_IMM
+ -- : BFD_RELOC_ARM_LDR_IMM
+ -- : BFD_RELOC_ARM_LITERAL
+ -- : BFD_RELOC_ARM_IN_POOL
+ -- : BFD_RELOC_ARM_OFFSET_IMM8
+ -- : BFD_RELOC_ARM_T32_OFFSET_U8
+ -- : BFD_RELOC_ARM_T32_OFFSET_IMM
+ -- : BFD_RELOC_ARM_HWLITERAL
+ -- : BFD_RELOC_ARM_THUMB_ADD
+ -- : BFD_RELOC_ARM_THUMB_IMM
+ -- : BFD_RELOC_ARM_THUMB_SHIFT
+ These relocs are only used within the ARM assembler. They are not
+ (at present) written to any object files.
+
+ -- : BFD_RELOC_SH_PCDISP8BY2
+ -- : BFD_RELOC_SH_PCDISP12BY2
+ -- : BFD_RELOC_SH_IMM3
+ -- : BFD_RELOC_SH_IMM3U
+ -- : BFD_RELOC_SH_DISP12
+ -- : BFD_RELOC_SH_DISP12BY2
+ -- : BFD_RELOC_SH_DISP12BY4
+ -- : BFD_RELOC_SH_DISP12BY8
+ -- : BFD_RELOC_SH_DISP20
+ -- : BFD_RELOC_SH_DISP20BY8
+ -- : BFD_RELOC_SH_IMM4
+ -- : BFD_RELOC_SH_IMM4BY2
+ -- : BFD_RELOC_SH_IMM4BY4
+ -- : BFD_RELOC_SH_IMM8
+ -- : BFD_RELOC_SH_IMM8BY2
+ -- : BFD_RELOC_SH_IMM8BY4
+ -- : BFD_RELOC_SH_PCRELIMM8BY2
+ -- : BFD_RELOC_SH_PCRELIMM8BY4
+ -- : BFD_RELOC_SH_SWITCH16
+ -- : BFD_RELOC_SH_SWITCH32
+ -- : BFD_RELOC_SH_USES
+ -- : BFD_RELOC_SH_COUNT
+ -- : BFD_RELOC_SH_ALIGN
+ -- : BFD_RELOC_SH_CODE
+ -- : BFD_RELOC_SH_DATA
+ -- : BFD_RELOC_SH_LABEL
+ -- : BFD_RELOC_SH_LOOP_START
+ -- : BFD_RELOC_SH_LOOP_END
+ -- : BFD_RELOC_SH_COPY
+ -- : BFD_RELOC_SH_GLOB_DAT
+ -- : BFD_RELOC_SH_JMP_SLOT
+ -- : BFD_RELOC_SH_RELATIVE
+ -- : BFD_RELOC_SH_GOTPC
+ -- : BFD_RELOC_SH_GOT_LOW16
+ -- : BFD_RELOC_SH_GOT_MEDLOW16
+ -- : BFD_RELOC_SH_GOT_MEDHI16
+ -- : BFD_RELOC_SH_GOT_HI16
+ -- : BFD_RELOC_SH_GOTPLT_LOW16
+ -- : BFD_RELOC_SH_GOTPLT_MEDLOW16
+ -- : BFD_RELOC_SH_GOTPLT_MEDHI16
+ -- : BFD_RELOC_SH_GOTPLT_HI16
+ -- : BFD_RELOC_SH_PLT_LOW16
+ -- : BFD_RELOC_SH_PLT_MEDLOW16
+ -- : BFD_RELOC_SH_PLT_MEDHI16
+ -- : BFD_RELOC_SH_PLT_HI16
+ -- : BFD_RELOC_SH_GOTOFF_LOW16
+ -- : BFD_RELOC_SH_GOTOFF_MEDLOW16
+ -- : BFD_RELOC_SH_GOTOFF_MEDHI16
+ -- : BFD_RELOC_SH_GOTOFF_HI16
+ -- : BFD_RELOC_SH_GOTPC_LOW16
+ -- : BFD_RELOC_SH_GOTPC_MEDLOW16
+ -- : BFD_RELOC_SH_GOTPC_MEDHI16
+ -- : BFD_RELOC_SH_GOTPC_HI16
+ -- : BFD_RELOC_SH_COPY64
+ -- : BFD_RELOC_SH_GLOB_DAT64
+ -- : BFD_RELOC_SH_JMP_SLOT64
+ -- : BFD_RELOC_SH_RELATIVE64
+ -- : BFD_RELOC_SH_GOT10BY4
+ -- : BFD_RELOC_SH_GOT10BY8
+ -- : BFD_RELOC_SH_GOTPLT10BY4
+ -- : BFD_RELOC_SH_GOTPLT10BY8
+ -- : BFD_RELOC_SH_GOTPLT32
+ -- : BFD_RELOC_SH_SHMEDIA_CODE
+ -- : BFD_RELOC_SH_IMMU5
+ -- : BFD_RELOC_SH_IMMS6
+ -- : BFD_RELOC_SH_IMMS6BY32
+ -- : BFD_RELOC_SH_IMMU6
+ -- : BFD_RELOC_SH_IMMS10
+ -- : BFD_RELOC_SH_IMMS10BY2
+ -- : BFD_RELOC_SH_IMMS10BY4
+ -- : BFD_RELOC_SH_IMMS10BY8
+ -- : BFD_RELOC_SH_IMMS16
+ -- : BFD_RELOC_SH_IMMU16
+ -- : BFD_RELOC_SH_IMM_LOW16
+ -- : BFD_RELOC_SH_IMM_LOW16_PCREL
+ -- : BFD_RELOC_SH_IMM_MEDLOW16
+ -- : BFD_RELOC_SH_IMM_MEDLOW16_PCREL
+ -- : BFD_RELOC_SH_IMM_MEDHI16
+ -- : BFD_RELOC_SH_IMM_MEDHI16_PCREL
+ -- : BFD_RELOC_SH_IMM_HI16
+ -- : BFD_RELOC_SH_IMM_HI16_PCREL
+ -- : BFD_RELOC_SH_PT_16
+ -- : BFD_RELOC_SH_TLS_GD_32
+ -- : BFD_RELOC_SH_TLS_LD_32
+ -- : BFD_RELOC_SH_TLS_LDO_32
+ -- : BFD_RELOC_SH_TLS_IE_32
+ -- : BFD_RELOC_SH_TLS_LE_32
+ -- : BFD_RELOC_SH_TLS_DTPMOD32
+ -- : BFD_RELOC_SH_TLS_DTPOFF32
+ -- : BFD_RELOC_SH_TLS_TPOFF32
+ Renesas / SuperH SH relocs. Not all of these appear in object
+ files.
+
+ -- : BFD_RELOC_ARC_B22_PCREL
+ ARC Cores relocs. ARC 22 bit pc-relative branch. The lowest two
+ bits must be zero and are not stored in the instruction. The high
+ 20 bits are installed in bits 26 through 7 of the instruction.
+
+ -- : BFD_RELOC_ARC_B26
+ ARC 26 bit absolute branch. The lowest two bits must be zero and
+ are not stored in the instruction. The high 24 bits are installed
+ in bits 23 through 0.
+
+ -- : BFD_RELOC_BFIN_16_IMM
+ ADI Blackfin 16 bit immediate absolute reloc.
+
+ -- : BFD_RELOC_BFIN_16_HIGH
+ ADI Blackfin 16 bit immediate absolute reloc higher 16 bits.
+
+ -- : BFD_RELOC_BFIN_4_PCREL
+ ADI Blackfin 'a' part of LSETUP.
+
+ -- : BFD_RELOC_BFIN_5_PCREL
+ ADI Blackfin.
+
+ -- : BFD_RELOC_BFIN_16_LOW
+ ADI Blackfin 16 bit immediate absolute reloc lower 16 bits.
+
+ -- : BFD_RELOC_BFIN_10_PCREL
+ ADI Blackfin.
+
+ -- : BFD_RELOC_BFIN_11_PCREL
+ ADI Blackfin 'b' part of LSETUP.
+
+ -- : BFD_RELOC_BFIN_12_PCREL_JUMP
+ ADI Blackfin.
+
+ -- : BFD_RELOC_BFIN_12_PCREL_JUMP_S
+ ADI Blackfin Short jump, pcrel.
+
+ -- : BFD_RELOC_BFIN_24_PCREL_CALL_X
+ ADI Blackfin Call.x not implemented.
+
+ -- : BFD_RELOC_BFIN_24_PCREL_JUMP_L
+ ADI Blackfin Long Jump pcrel.
+
+ -- : BFD_RELOC_BFIN_GOT17M4
+ -- : BFD_RELOC_BFIN_GOTHI
+ -- : BFD_RELOC_BFIN_GOTLO
+ -- : BFD_RELOC_BFIN_FUNCDESC
+ -- : BFD_RELOC_BFIN_FUNCDESC_GOT17M4
+ -- : BFD_RELOC_BFIN_FUNCDESC_GOTHI
+ -- : BFD_RELOC_BFIN_FUNCDESC_GOTLO
+ -- : BFD_RELOC_BFIN_FUNCDESC_VALUE
+ -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4
+ -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI
+ -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO
+ -- : BFD_RELOC_BFIN_GOTOFF17M4
+ -- : BFD_RELOC_BFIN_GOTOFFHI
+ -- : BFD_RELOC_BFIN_GOTOFFLO
+ ADI Blackfin FD-PIC relocations.
+
+ -- : BFD_RELOC_BFIN_GOT
+ ADI Blackfin GOT relocation.
+
+ -- : BFD_RELOC_BFIN_PLTPC
+ ADI Blackfin PLTPC relocation.
+
+ -- : BFD_ARELOC_BFIN_PUSH
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_CONST
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_ADD
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_SUB
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_MULT
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_DIV
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_MOD
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_LSHIFT
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_RSHIFT
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_AND
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_OR
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_XOR
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_LAND
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_LOR
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_LEN
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_NEG
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_COMP
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_PAGE
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_HWPAGE
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_ARELOC_BFIN_ADDR
+ ADI Blackfin arithmetic relocation.
+
+ -- : BFD_RELOC_D10V_10_PCREL_R
+ Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2
+ bits assumed to be 0.
+
+ -- : BFD_RELOC_D10V_10_PCREL_L
+ Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2
+ bits assumed to be 0. This is the same as the previous reloc
+ except it is in the left container, i.e., shifted left 15 bits.
+
+ -- : BFD_RELOC_D10V_18
+ This is an 18-bit reloc with the right 2 bits assumed to be 0.
+
+ -- : BFD_RELOC_D10V_18_PCREL
+ This is an 18-bit reloc with the right 2 bits assumed to be 0.
+
+ -- : BFD_RELOC_D30V_6
+ Mitsubishi D30V relocs. This is a 6-bit absolute reloc.
+
+ -- : BFD_RELOC_D30V_9_PCREL
+ This is a 6-bit pc-relative reloc with the right 3 bits assumed to
+ be 0.
+
+ -- : BFD_RELOC_D30V_9_PCREL_R
+ This is a 6-bit pc-relative reloc with the right 3 bits assumed to
+ be 0. Same as the previous reloc but on the right side of the
+ container.
+
+ -- : BFD_RELOC_D30V_15
+ This is a 12-bit absolute reloc with the right 3 bitsassumed to be
+ 0.
+
+ -- : BFD_RELOC_D30V_15_PCREL
+ This is a 12-bit pc-relative reloc with the right 3 bits assumed
+ to be 0.
+
+ -- : BFD_RELOC_D30V_15_PCREL_R
+ This is a 12-bit pc-relative reloc with the right 3 bits assumed
+ to be 0. Same as the previous reloc but on the right side of the
+ container.
+
+ -- : BFD_RELOC_D30V_21
+ This is an 18-bit absolute reloc with the right 3 bits assumed to
+ be 0.
+
+ -- : BFD_RELOC_D30V_21_PCREL
+ This is an 18-bit pc-relative reloc with the right 3 bits assumed
+ to be 0.
+
+ -- : BFD_RELOC_D30V_21_PCREL_R
+ This is an 18-bit pc-relative reloc with the right 3 bits assumed
+ to be 0. Same as the previous reloc but on the right side of the
+ container.
+
+ -- : BFD_RELOC_D30V_32
+ This is a 32-bit absolute reloc.
+
+ -- : BFD_RELOC_D30V_32_PCREL
+ This is a 32-bit pc-relative reloc.
+
+ -- : BFD_RELOC_DLX_HI16_S
+ DLX relocs
+
+ -- : BFD_RELOC_DLX_LO16
+ DLX relocs
+
+ -- : BFD_RELOC_DLX_JMP26
+ DLX relocs
+
+ -- : BFD_RELOC_M32C_HI8
+ -- : BFD_RELOC_M32C_RL_JUMP
+ -- : BFD_RELOC_M32C_RL_1ADDR
+ -- : BFD_RELOC_M32C_RL_2ADDR
+ Renesas M16C/M32C Relocations.
+
+ -- : BFD_RELOC_M32R_24
+ Renesas M32R (formerly Mitsubishi M32R) relocs. This is a 24 bit
+ absolute address.
+
+ -- : BFD_RELOC_M32R_10_PCREL
+ This is a 10-bit pc-relative reloc with the right 2 bits assumed
+ to be 0.
+
+ -- : BFD_RELOC_M32R_18_PCREL
+ This is an 18-bit reloc with the right 2 bits assumed to be 0.
+
+ -- : BFD_RELOC_M32R_26_PCREL
+ This is a 26-bit reloc with the right 2 bits assumed to be 0.
+
+ -- : BFD_RELOC_M32R_HI16_ULO
+ This is a 16-bit reloc containing the high 16 bits of an address
+ used when the lower 16 bits are treated as unsigned.
+
+ -- : BFD_RELOC_M32R_HI16_SLO
+ This is a 16-bit reloc containing the high 16 bits of an address
+ used when the lower 16 bits are treated as signed.
+
+ -- : BFD_RELOC_M32R_LO16
+ This is a 16-bit reloc containing the lower 16 bits of an address.
+
+ -- : BFD_RELOC_M32R_SDA16
+ This is a 16-bit reloc containing the small data area offset for
+ use in add3, load, and store instructions.
+
+ -- : BFD_RELOC_M32R_GOT24
+ -- : BFD_RELOC_M32R_26_PLTREL
+ -- : BFD_RELOC_M32R_COPY
+ -- : BFD_RELOC_M32R_GLOB_DAT
+ -- : BFD_RELOC_M32R_JMP_SLOT
+ -- : BFD_RELOC_M32R_RELATIVE
+ -- : BFD_RELOC_M32R_GOTOFF
+ -- : BFD_RELOC_M32R_GOTOFF_HI_ULO
+ -- : BFD_RELOC_M32R_GOTOFF_HI_SLO
+ -- : BFD_RELOC_M32R_GOTOFF_LO
+ -- : BFD_RELOC_M32R_GOTPC24
+ -- : BFD_RELOC_M32R_GOT16_HI_ULO
+ -- : BFD_RELOC_M32R_GOT16_HI_SLO
+ -- : BFD_RELOC_M32R_GOT16_LO
+ -- : BFD_RELOC_M32R_GOTPC_HI_ULO
+ -- : BFD_RELOC_M32R_GOTPC_HI_SLO
+ -- : BFD_RELOC_M32R_GOTPC_LO
+ For PIC.
+
+ -- : BFD_RELOC_V850_9_PCREL
+ This is a 9-bit reloc
+
+ -- : BFD_RELOC_V850_22_PCREL
+ This is a 22-bit reloc
+
+ -- : BFD_RELOC_V850_SDA_16_16_OFFSET
+ This is a 16 bit offset from the short data area pointer.
+
+ -- : BFD_RELOC_V850_SDA_15_16_OFFSET
+ This is a 16 bit offset (of which only 15 bits are used) from the
+ short data area pointer.
+
+ -- : BFD_RELOC_V850_ZDA_16_16_OFFSET
+ This is a 16 bit offset from the zero data area pointer.
+
+ -- : BFD_RELOC_V850_ZDA_15_16_OFFSET
+ This is a 16 bit offset (of which only 15 bits are used) from the
+ zero data area pointer.
+
+ -- : BFD_RELOC_V850_TDA_6_8_OFFSET
+ This is an 8 bit offset (of which only 6 bits are used) from the
+ tiny data area pointer.
+
+ -- : BFD_RELOC_V850_TDA_7_8_OFFSET
+ This is an 8bit offset (of which only 7 bits are used) from the
+ tiny data area pointer.
+
+ -- : BFD_RELOC_V850_TDA_7_7_OFFSET
+ This is a 7 bit offset from the tiny data area pointer.
+
+ -- : BFD_RELOC_V850_TDA_16_16_OFFSET
+ This is a 16 bit offset from the tiny data area pointer.
+
+ -- : BFD_RELOC_V850_TDA_4_5_OFFSET
+ This is a 5 bit offset (of which only 4 bits are used) from the
+ tiny data area pointer.
+
+ -- : BFD_RELOC_V850_TDA_4_4_OFFSET
+ This is a 4 bit offset from the tiny data area pointer.
+
+ -- : BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET
+ This is a 16 bit offset from the short data area pointer, with the
+ bits placed non-contiguously in the instruction.
+
+ -- : BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET
+ This is a 16 bit offset from the zero data area pointer, with the
+ bits placed non-contiguously in the instruction.
+
+ -- : BFD_RELOC_V850_CALLT_6_7_OFFSET
+ This is a 6 bit offset from the call table base pointer.
+
+ -- : BFD_RELOC_V850_CALLT_16_16_OFFSET
+ This is a 16 bit offset from the call table base pointer.
+
+ -- : BFD_RELOC_V850_LONGCALL
+ Used for relaxing indirect function calls.
+
+ -- : BFD_RELOC_V850_LONGJUMP
+ Used for relaxing indirect jumps.
+
+ -- : BFD_RELOC_V850_ALIGN
+ Used to maintain alignment whilst relaxing.
+
+ -- : BFD_RELOC_V850_LO16_SPLIT_OFFSET
+ This is a variation of BFD_RELOC_LO16 that can be used in v850e
+ ld.bu instructions.
+
+ -- : BFD_RELOC_MN10300_32_PCREL
+ This is a 32bit pcrel reloc for the mn10300, offset by two bytes
+ in the instruction.
+
+ -- : BFD_RELOC_MN10300_16_PCREL
+ This is a 16bit pcrel reloc for the mn10300, offset by two bytes
+ in the instruction.
+
+ -- : BFD_RELOC_TIC30_LDP
+ This is a 8bit DP reloc for the tms320c30, where the most
+ significant 8 bits of a 24 bit word are placed into the least
+ significant 8 bits of the opcode.
+
+ -- : BFD_RELOC_TIC54X_PARTLS7
+ This is a 7bit reloc for the tms320c54x, where the least
+ significant 7 bits of a 16 bit word are placed into the least
+ significant 7 bits of the opcode.
+
+ -- : BFD_RELOC_TIC54X_PARTMS9
+ This is a 9bit DP reloc for the tms320c54x, where the most
+ significant 9 bits of a 16 bit word are placed into the least
+ significant 9 bits of the opcode.
+
+ -- : BFD_RELOC_TIC54X_23
+ This is an extended address 23-bit reloc for the tms320c54x.
+
+ -- : BFD_RELOC_TIC54X_16_OF_23
+ This is a 16-bit reloc for the tms320c54x, where the least
+ significant 16 bits of a 23-bit extended address are placed into
+ the opcode.
+
+ -- : BFD_RELOC_TIC54X_MS7_OF_23
+ This is a reloc for the tms320c54x, where the most significant 7
+ bits of a 23-bit extended address are placed into the opcode.
+
+ -- : BFD_RELOC_FR30_48
+ This is a 48 bit reloc for the FR30 that stores 32 bits.
+
+ -- : BFD_RELOC_FR30_20
+ This is a 32 bit reloc for the FR30 that stores 20 bits split up
+ into two sections.
+
+ -- : BFD_RELOC_FR30_6_IN_4
+ This is a 16 bit reloc for the FR30 that stores a 6 bit word
+ offset in 4 bits.
+
+ -- : BFD_RELOC_FR30_8_IN_8
+ This is a 16 bit reloc for the FR30 that stores an 8 bit byte
+ offset into 8 bits.
+
+ -- : BFD_RELOC_FR30_9_IN_8
+ This is a 16 bit reloc for the FR30 that stores a 9 bit short
+ offset into 8 bits.
+
+ -- : BFD_RELOC_FR30_10_IN_8
+ This is a 16 bit reloc for the FR30 that stores a 10 bit word
+ offset into 8 bits.
+
+ -- : BFD_RELOC_FR30_9_PCREL
+ This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative
+ short offset into 8 bits.
+
+ -- : BFD_RELOC_FR30_12_PCREL
+ This is a 16 bit reloc for the FR30 that stores a 12 bit pc
+ relative short offset into 11 bits.
+
+ -- : BFD_RELOC_MCORE_PCREL_IMM8BY4
+ -- : BFD_RELOC_MCORE_PCREL_IMM11BY2
+ -- : BFD_RELOC_MCORE_PCREL_IMM4BY2
+ -- : BFD_RELOC_MCORE_PCREL_32
+ -- : BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2
+ -- : BFD_RELOC_MCORE_RVA
+ Motorola Mcore relocations.
+
+ -- : BFD_RELOC_MEP_8
+ -- : BFD_RELOC_MEP_16
+ -- : BFD_RELOC_MEP_32
+ -- : BFD_RELOC_MEP_PCREL8A2
+ -- : BFD_RELOC_MEP_PCREL12A2
+ -- : BFD_RELOC_MEP_PCREL17A2
+ -- : BFD_RELOC_MEP_PCREL24A2
+ -- : BFD_RELOC_MEP_PCABS24A2
+ -- : BFD_RELOC_MEP_LOW16
+ -- : BFD_RELOC_MEP_HI16U
+ -- : BFD_RELOC_MEP_HI16S
+ -- : BFD_RELOC_MEP_GPREL
+ -- : BFD_RELOC_MEP_TPREL
+ -- : BFD_RELOC_MEP_TPREL7
+ -- : BFD_RELOC_MEP_TPREL7A2
+ -- : BFD_RELOC_MEP_TPREL7A4
+ -- : BFD_RELOC_MEP_UIMM24
+ -- : BFD_RELOC_MEP_ADDR24A4
+ -- : BFD_RELOC_MEP_GNU_VTINHERIT
+ -- : BFD_RELOC_MEP_GNU_VTENTRY
+ Toshiba Media Processor Relocations.
+
+ -- : BFD_RELOC_MMIX_GETA
+ -- : BFD_RELOC_MMIX_GETA_1
+ -- : BFD_RELOC_MMIX_GETA_2
+ -- : BFD_RELOC_MMIX_GETA_3
+ These are relocations for the GETA instruction.
+
+ -- : BFD_RELOC_MMIX_CBRANCH
+ -- : BFD_RELOC_MMIX_CBRANCH_J
+ -- : BFD_RELOC_MMIX_CBRANCH_1
+ -- : BFD_RELOC_MMIX_CBRANCH_2
+ -- : BFD_RELOC_MMIX_CBRANCH_3
+ These are relocations for a conditional branch instruction.
+
+ -- : BFD_RELOC_MMIX_PUSHJ
+ -- : BFD_RELOC_MMIX_PUSHJ_1
+ -- : BFD_RELOC_MMIX_PUSHJ_2
+ -- : BFD_RELOC_MMIX_PUSHJ_3
+ -- : BFD_RELOC_MMIX_PUSHJ_STUBBABLE
+ These are relocations for the PUSHJ instruction.
+
+ -- : BFD_RELOC_MMIX_JMP
+ -- : BFD_RELOC_MMIX_JMP_1
+ -- : BFD_RELOC_MMIX_JMP_2
+ -- : BFD_RELOC_MMIX_JMP_3
+ These are relocations for the JMP instruction.
+
+ -- : BFD_RELOC_MMIX_ADDR19
+ This is a relocation for a relative address as in a GETA
+ instruction or a branch.
+
+ -- : BFD_RELOC_MMIX_ADDR27
+ This is a relocation for a relative address as in a JMP
+ instruction.
+
+ -- : BFD_RELOC_MMIX_REG_OR_BYTE
+ This is a relocation for an instruction field that may be a general
+ register or a value 0..255.
+
+ -- : BFD_RELOC_MMIX_REG
+ This is a relocation for an instruction field that may be a general
+ register.
+
+ -- : BFD_RELOC_MMIX_BASE_PLUS_OFFSET
+ This is a relocation for two instruction fields holding a register
+ and an offset, the equivalent of the relocation.
+
+ -- : BFD_RELOC_MMIX_LOCAL
+ This relocation is an assertion that the expression is not
+ allocated as a global register. It does not modify contents.
+
+ -- : BFD_RELOC_AVR_7_PCREL
+ This is a 16 bit reloc for the AVR that stores 8 bit pc relative
+ short offset into 7 bits.
+
+ -- : BFD_RELOC_AVR_13_PCREL
+ This is a 16 bit reloc for the AVR that stores 13 bit pc relative
+ short offset into 12 bits.
+
+ -- : BFD_RELOC_AVR_16_PM
+ This is a 16 bit reloc for the AVR that stores 17 bit value
+ (usually program memory address) into 16 bits.
+
+ -- : BFD_RELOC_AVR_LO8_LDI
+ This is a 16 bit reloc for the AVR that stores 8 bit value (usually
+ data memory address) into 8 bit immediate value of LDI insn.
+
+ -- : BFD_RELOC_AVR_HI8_LDI
+ This is a 16 bit reloc for the AVR that stores 8 bit value (high 8
+ bit of data memory address) into 8 bit immediate value of LDI insn.
+
+ -- : BFD_RELOC_AVR_HH8_LDI
+ This is a 16 bit reloc for the AVR that stores 8 bit value (most
+ high 8 bit of program memory address) into 8 bit immediate value
+ of LDI insn.
+
+ -- : BFD_RELOC_AVR_MS8_LDI
+ This is a 16 bit reloc for the AVR that stores 8 bit value (most
+ high 8 bit of 32 bit value) into 8 bit immediate value of LDI insn.
+
+ -- : BFD_RELOC_AVR_LO8_LDI_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (usually data memory address) into 8 bit immediate value of SUBI
+ insn.
+
+ -- : BFD_RELOC_AVR_HI8_LDI_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (high 8 bit of data memory address) into 8 bit immediate value of
+ SUBI insn.
+
+ -- : BFD_RELOC_AVR_HH8_LDI_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (most high 8 bit of program memory address) into 8 bit immediate
+ value of LDI or SUBI insn.
+
+ -- : BFD_RELOC_AVR_MS8_LDI_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (msb of 32 bit value) into 8 bit immediate value of LDI insn.
+
+ -- : BFD_RELOC_AVR_LO8_LDI_PM
+ This is a 16 bit reloc for the AVR that stores 8 bit value (usually
+ command address) into 8 bit immediate value of LDI insn.
+
+ -- : BFD_RELOC_AVR_LO8_LDI_GS
+ This is a 16 bit reloc for the AVR that stores 8 bit value
+ (command address) into 8 bit immediate value of LDI insn. If the
+ address is beyond the 128k boundary, the linker inserts a jump
+ stub for this reloc in the lower 128k.
+
+ -- : BFD_RELOC_AVR_HI8_LDI_PM
+ This is a 16 bit reloc for the AVR that stores 8 bit value (high 8
+ bit of command address) into 8 bit immediate value of LDI insn.
+
+ -- : BFD_RELOC_AVR_HI8_LDI_GS
+ This is a 16 bit reloc for the AVR that stores 8 bit value (high 8
+ bit of command address) into 8 bit immediate value of LDI insn.
+ If the address is beyond the 128k boundary, the linker inserts a
+ jump stub for this reloc below 128k.
+
+ -- : BFD_RELOC_AVR_HH8_LDI_PM
+ This is a 16 bit reloc for the AVR that stores 8 bit value (most
+ high 8 bit of command address) into 8 bit immediate value of LDI
+ insn.
+
+ -- : BFD_RELOC_AVR_LO8_LDI_PM_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (usually command address) into 8 bit immediate value of SUBI insn.
+
+ -- : BFD_RELOC_AVR_HI8_LDI_PM_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (high 8 bit of 16 bit command address) into 8 bit immediate value
+ of SUBI insn.
+
+ -- : BFD_RELOC_AVR_HH8_LDI_PM_NEG
+ This is a 16 bit reloc for the AVR that stores negated 8 bit value
+ (high 6 bit of 22 bit command address) into 8 bit immediate value
+ of SUBI insn.
+
+ -- : BFD_RELOC_AVR_CALL
+ This is a 32 bit reloc for the AVR that stores 23 bit value into
+ 22 bits.
+
+ -- : BFD_RELOC_AVR_LDI
+ This is a 16 bit reloc for the AVR that stores all needed bits for
+ absolute addressing with ldi with overflow check to linktime
+
+ -- : BFD_RELOC_AVR_6
+ This is a 6 bit reloc for the AVR that stores offset for ldd/std
+ instructions
+
+ -- : BFD_RELOC_AVR_6_ADIW
+ This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw
+ instructions
+
+ -- : BFD_RELOC_390_12
+ Direct 12 bit.
+
+ -- : BFD_RELOC_390_GOT12
+ 12 bit GOT offset.
+
+ -- : BFD_RELOC_390_PLT32
+ 32 bit PC relative PLT address.
+
+ -- : BFD_RELOC_390_COPY
+ Copy symbol at runtime.
+
+ -- : BFD_RELOC_390_GLOB_DAT
+ Create GOT entry.
+
+ -- : BFD_RELOC_390_JMP_SLOT
+ Create PLT entry.
+
+ -- : BFD_RELOC_390_RELATIVE
+ Adjust by program base.
+
+ -- : BFD_RELOC_390_GOTPC
+ 32 bit PC relative offset to GOT.
+
+ -- : BFD_RELOC_390_GOT16
+ 16 bit GOT offset.
+
+ -- : BFD_RELOC_390_PC16DBL
+ PC relative 16 bit shifted by 1.
+
+ -- : BFD_RELOC_390_PLT16DBL
+ 16 bit PC rel. PLT shifted by 1.
+
+ -- : BFD_RELOC_390_PC32DBL
+ PC relative 32 bit shifted by 1.
+
+ -- : BFD_RELOC_390_PLT32DBL
+ 32 bit PC rel. PLT shifted by 1.
+
+ -- : BFD_RELOC_390_GOTPCDBL
+ 32 bit PC rel. GOT shifted by 1.
+
+ -- : BFD_RELOC_390_GOT64
+ 64 bit GOT offset.
+
+ -- : BFD_RELOC_390_PLT64
+ 64 bit PC relative PLT address.
+
+ -- : BFD_RELOC_390_GOTENT
+ 32 bit rel. offset to GOT entry.
+
+ -- : BFD_RELOC_390_GOTOFF64
+ 64 bit offset to GOT.
+
+ -- : BFD_RELOC_390_GOTPLT12
+ 12-bit offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_390_GOTPLT16
+ 16-bit offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_390_GOTPLT32
+ 32-bit offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_390_GOTPLT64
+ 64-bit offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_390_GOTPLTENT
+ 32-bit rel. offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_390_PLTOFF16
+ 16-bit rel. offset from the GOT to a PLT entry.
+
+ -- : BFD_RELOC_390_PLTOFF32
+ 32-bit rel. offset from the GOT to a PLT entry.
+
+ -- : BFD_RELOC_390_PLTOFF64
+ 64-bit rel. offset from the GOT to a PLT entry.
+
+ -- : BFD_RELOC_390_TLS_LOAD
+ -- : BFD_RELOC_390_TLS_GDCALL
+ -- : BFD_RELOC_390_TLS_LDCALL
+ -- : BFD_RELOC_390_TLS_GD32
+ -- : BFD_RELOC_390_TLS_GD64
+ -- : BFD_RELOC_390_TLS_GOTIE12
+ -- : BFD_RELOC_390_TLS_GOTIE32
+ -- : BFD_RELOC_390_TLS_GOTIE64
+ -- : BFD_RELOC_390_TLS_LDM32
+ -- : BFD_RELOC_390_TLS_LDM64
+ -- : BFD_RELOC_390_TLS_IE32
+ -- : BFD_RELOC_390_TLS_IE64
+ -- : BFD_RELOC_390_TLS_IEENT
+ -- : BFD_RELOC_390_TLS_LE32
+ -- : BFD_RELOC_390_TLS_LE64
+ -- : BFD_RELOC_390_TLS_LDO32
+ -- : BFD_RELOC_390_TLS_LDO64
+ -- : BFD_RELOC_390_TLS_DTPMOD
+ -- : BFD_RELOC_390_TLS_DTPOFF
+ -- : BFD_RELOC_390_TLS_TPOFF
+ s390 tls relocations.
+
+ -- : BFD_RELOC_390_20
+ -- : BFD_RELOC_390_GOT20
+ -- : BFD_RELOC_390_GOTPLT20
+ -- : BFD_RELOC_390_TLS_GOTIE20
+ Long displacement extension.
+
+ -- : BFD_RELOC_SCORE_GPREL15
+ Score relocations Low 16 bit for load/store
+
+ -- : BFD_RELOC_SCORE_DUMMY2
+ -- : BFD_RELOC_SCORE_JMP
+ This is a 24-bit reloc with the right 1 bit assumed to be 0
+
+ -- : BFD_RELOC_SCORE_BRANCH
+ This is a 19-bit reloc with the right 1 bit assumed to be 0
+
+ -- : BFD_RELOC_SCORE_IMM30
+ This is a 32-bit reloc for 48-bit instructions.
+
+ -- : BFD_RELOC_SCORE_IMM32
+ This is a 32-bit reloc for 48-bit instructions.
+
+ -- : BFD_RELOC_SCORE16_JMP
+ This is a 11-bit reloc with the right 1 bit assumed to be 0
+
+ -- : BFD_RELOC_SCORE16_BRANCH
+ This is a 8-bit reloc with the right 1 bit assumed to be 0
+
+ -- : BFD_RELOC_SCORE_BCMP
+ This is a 9-bit reloc with the right 1 bit assumed to be 0
+
+ -- : BFD_RELOC_SCORE_GOT15
+ -- : BFD_RELOC_SCORE_GOT_LO16
+ -- : BFD_RELOC_SCORE_CALL15
+ -- : BFD_RELOC_SCORE_DUMMY_HI16
+ Undocumented Score relocs
+
+ -- : BFD_RELOC_IP2K_FR9
+ Scenix IP2K - 9-bit register number / data address
+
+ -- : BFD_RELOC_IP2K_BANK
+ Scenix IP2K - 4-bit register/data bank number
+
+ -- : BFD_RELOC_IP2K_ADDR16CJP
+ Scenix IP2K - low 13 bits of instruction word address
+
+ -- : BFD_RELOC_IP2K_PAGE3
+ Scenix IP2K - high 3 bits of instruction word address
+
+ -- : BFD_RELOC_IP2K_LO8DATA
+ -- : BFD_RELOC_IP2K_HI8DATA
+ -- : BFD_RELOC_IP2K_EX8DATA
+ Scenix IP2K - ext/low/high 8 bits of data address
+
+ -- : BFD_RELOC_IP2K_LO8INSN
+ -- : BFD_RELOC_IP2K_HI8INSN
+ Scenix IP2K - low/high 8 bits of instruction word address
+
+ -- : BFD_RELOC_IP2K_PC_SKIP
+ Scenix IP2K - even/odd PC modifier to modify snb pcl.0
+
+ -- : BFD_RELOC_IP2K_TEXT
+ Scenix IP2K - 16 bit word address in text section.
+
+ -- : BFD_RELOC_IP2K_FR_OFFSET
+ Scenix IP2K - 7-bit sp or dp offset
+
+ -- : BFD_RELOC_VPE4KMATH_DATA
+ -- : BFD_RELOC_VPE4KMATH_INSN
+ Scenix VPE4K coprocessor - data/insn-space addressing
+
+ -- : BFD_RELOC_VTABLE_INHERIT
+ -- : BFD_RELOC_VTABLE_ENTRY
+ These two relocations are used by the linker to determine which of
+ the entries in a C++ virtual function table are actually used.
+ When the -gc-sections option is given, the linker will zero out
+ the entries that are not used, so that the code for those
+ functions need not be included in the output.
+
+ VTABLE_INHERIT is a zero-space relocation used to describe to the
+ linker the inheritance tree of a C++ virtual function table. The
+ relocation's symbol should be the parent class' vtable, and the
+ relocation should be located at the child vtable.
+
+ VTABLE_ENTRY is a zero-space relocation that describes the use of a
+ virtual function table entry. The reloc's symbol should refer to
+ the table of the class mentioned in the code. Off of that base,
+ an offset describes the entry that is being used. For Rela hosts,
+ this offset is stored in the reloc's addend. For Rel hosts, we
+ are forced to put this offset in the reloc's section offset.
+
+ -- : BFD_RELOC_IA64_IMM14
+ -- : BFD_RELOC_IA64_IMM22
+ -- : BFD_RELOC_IA64_IMM64
+ -- : BFD_RELOC_IA64_DIR32MSB
+ -- : BFD_RELOC_IA64_DIR32LSB
+ -- : BFD_RELOC_IA64_DIR64MSB
+ -- : BFD_RELOC_IA64_DIR64LSB
+ -- : BFD_RELOC_IA64_GPREL22
+ -- : BFD_RELOC_IA64_GPREL64I
+ -- : BFD_RELOC_IA64_GPREL32MSB
+ -- : BFD_RELOC_IA64_GPREL32LSB
+ -- : BFD_RELOC_IA64_GPREL64MSB
+ -- : BFD_RELOC_IA64_GPREL64LSB
+ -- : BFD_RELOC_IA64_LTOFF22
+ -- : BFD_RELOC_IA64_LTOFF64I
+ -- : BFD_RELOC_IA64_PLTOFF22
+ -- : BFD_RELOC_IA64_PLTOFF64I
+ -- : BFD_RELOC_IA64_PLTOFF64MSB
+ -- : BFD_RELOC_IA64_PLTOFF64LSB
+ -- : BFD_RELOC_IA64_FPTR64I
+ -- : BFD_RELOC_IA64_FPTR32MSB
+ -- : BFD_RELOC_IA64_FPTR32LSB
+ -- : BFD_RELOC_IA64_FPTR64MSB
+ -- : BFD_RELOC_IA64_FPTR64LSB
+ -- : BFD_RELOC_IA64_PCREL21B
+ -- : BFD_RELOC_IA64_PCREL21BI
+ -- : BFD_RELOC_IA64_PCREL21M
+ -- : BFD_RELOC_IA64_PCREL21F
+ -- : BFD_RELOC_IA64_PCREL22
+ -- : BFD_RELOC_IA64_PCREL60B
+ -- : BFD_RELOC_IA64_PCREL64I
+ -- : BFD_RELOC_IA64_PCREL32MSB
+ -- : BFD_RELOC_IA64_PCREL32LSB
+ -- : BFD_RELOC_IA64_PCREL64MSB
+ -- : BFD_RELOC_IA64_PCREL64LSB
+ -- : BFD_RELOC_IA64_LTOFF_FPTR22
+ -- : BFD_RELOC_IA64_LTOFF_FPTR64I
+ -- : BFD_RELOC_IA64_LTOFF_FPTR32MSB
+ -- : BFD_RELOC_IA64_LTOFF_FPTR32LSB
+ -- : BFD_RELOC_IA64_LTOFF_FPTR64MSB
+ -- : BFD_RELOC_IA64_LTOFF_FPTR64LSB
+ -- : BFD_RELOC_IA64_SEGREL32MSB
+ -- : BFD_RELOC_IA64_SEGREL32LSB
+ -- : BFD_RELOC_IA64_SEGREL64MSB
+ -- : BFD_RELOC_IA64_SEGREL64LSB
+ -- : BFD_RELOC_IA64_SECREL32MSB
+ -- : BFD_RELOC_IA64_SECREL32LSB
+ -- : BFD_RELOC_IA64_SECREL64MSB
+ -- : BFD_RELOC_IA64_SECREL64LSB
+ -- : BFD_RELOC_IA64_REL32MSB
+ -- : BFD_RELOC_IA64_REL32LSB
+ -- : BFD_RELOC_IA64_REL64MSB
+ -- : BFD_RELOC_IA64_REL64LSB
+ -- : BFD_RELOC_IA64_LTV32MSB
+ -- : BFD_RELOC_IA64_LTV32LSB
+ -- : BFD_RELOC_IA64_LTV64MSB
+ -- : BFD_RELOC_IA64_LTV64LSB
+ -- : BFD_RELOC_IA64_IPLTMSB
+ -- : BFD_RELOC_IA64_IPLTLSB
+ -- : BFD_RELOC_IA64_COPY
+ -- : BFD_RELOC_IA64_LTOFF22X
+ -- : BFD_RELOC_IA64_LDXMOV
+ -- : BFD_RELOC_IA64_TPREL14
+ -- : BFD_RELOC_IA64_TPREL22
+ -- : BFD_RELOC_IA64_TPREL64I
+ -- : BFD_RELOC_IA64_TPREL64MSB
+ -- : BFD_RELOC_IA64_TPREL64LSB
+ -- : BFD_RELOC_IA64_LTOFF_TPREL22
+ -- : BFD_RELOC_IA64_DTPMOD64MSB
+ -- : BFD_RELOC_IA64_DTPMOD64LSB
+ -- : BFD_RELOC_IA64_LTOFF_DTPMOD22
+ -- : BFD_RELOC_IA64_DTPREL14
+ -- : BFD_RELOC_IA64_DTPREL22
+ -- : BFD_RELOC_IA64_DTPREL64I
+ -- : BFD_RELOC_IA64_DTPREL32MSB
+ -- : BFD_RELOC_IA64_DTPREL32LSB
+ -- : BFD_RELOC_IA64_DTPREL64MSB
+ -- : BFD_RELOC_IA64_DTPREL64LSB
+ -- : BFD_RELOC_IA64_LTOFF_DTPREL22
+ Intel IA64 Relocations.
+
+ -- : BFD_RELOC_M68HC11_HI8
+ Motorola 68HC11 reloc. This is the 8 bit high part of an absolute
+ address.
+
+ -- : BFD_RELOC_M68HC11_LO8
+ Motorola 68HC11 reloc. This is the 8 bit low part of an absolute
+ address.
+
+ -- : BFD_RELOC_M68HC11_3B
+ Motorola 68HC11 reloc. This is the 3 bit of a value.
+
+ -- : BFD_RELOC_M68HC11_RL_JUMP
+ Motorola 68HC11 reloc. This reloc marks the beginning of a
+ jump/call instruction. It is used for linker relaxation to
+ correctly identify beginning of instruction and change some
+ branches to use PC-relative addressing mode.
+
+ -- : BFD_RELOC_M68HC11_RL_GROUP
+ Motorola 68HC11 reloc. This reloc marks a group of several
+ instructions that gcc generates and for which the linker
+ relaxation pass can modify and/or remove some of them.
+
+ -- : BFD_RELOC_M68HC11_LO16
+ Motorola 68HC11 reloc. This is the 16-bit lower part of an
+ address. It is used for 'call' instruction to specify the symbol
+ address without any special transformation (due to memory bank
+ window).
+
+ -- : BFD_RELOC_M68HC11_PAGE
+ Motorola 68HC11 reloc. This is a 8-bit reloc that specifies the
+ page number of an address. It is used by 'call' instruction to
+ specify the page number of the symbol.
+
+ -- : BFD_RELOC_M68HC11_24
+ Motorola 68HC11 reloc. This is a 24-bit reloc that represents the
+ address with a 16-bit value and a 8-bit page number. The symbol
+ address is transformed to follow the 16K memory bank of 68HC12
+ (seen as mapped in the window).
+
+ -- : BFD_RELOC_M68HC12_5B
+ Motorola 68HC12 reloc. This is the 5 bits of a value.
+
+ -- : BFD_RELOC_16C_NUM08
+ -- : BFD_RELOC_16C_NUM08_C
+ -- : BFD_RELOC_16C_NUM16
+ -- : BFD_RELOC_16C_NUM16_C
+ -- : BFD_RELOC_16C_NUM32
+ -- : BFD_RELOC_16C_NUM32_C
+ -- : BFD_RELOC_16C_DISP04
+ -- : BFD_RELOC_16C_DISP04_C
+ -- : BFD_RELOC_16C_DISP08
+ -- : BFD_RELOC_16C_DISP08_C
+ -- : BFD_RELOC_16C_DISP16
+ -- : BFD_RELOC_16C_DISP16_C
+ -- : BFD_RELOC_16C_DISP24
+ -- : BFD_RELOC_16C_DISP24_C
+ -- : BFD_RELOC_16C_DISP24a
+ -- : BFD_RELOC_16C_DISP24a_C
+ -- : BFD_RELOC_16C_REG04
+ -- : BFD_RELOC_16C_REG04_C
+ -- : BFD_RELOC_16C_REG04a
+ -- : BFD_RELOC_16C_REG04a_C
+ -- : BFD_RELOC_16C_REG14
+ -- : BFD_RELOC_16C_REG14_C
+ -- : BFD_RELOC_16C_REG16
+ -- : BFD_RELOC_16C_REG16_C
+ -- : BFD_RELOC_16C_REG20
+ -- : BFD_RELOC_16C_REG20_C
+ -- : BFD_RELOC_16C_ABS20
+ -- : BFD_RELOC_16C_ABS20_C
+ -- : BFD_RELOC_16C_ABS24
+ -- : BFD_RELOC_16C_ABS24_C
+ -- : BFD_RELOC_16C_IMM04
+ -- : BFD_RELOC_16C_IMM04_C
+ -- : BFD_RELOC_16C_IMM16
+ -- : BFD_RELOC_16C_IMM16_C
+ -- : BFD_RELOC_16C_IMM20
+ -- : BFD_RELOC_16C_IMM20_C
+ -- : BFD_RELOC_16C_IMM24
+ -- : BFD_RELOC_16C_IMM24_C
+ -- : BFD_RELOC_16C_IMM32
+ -- : BFD_RELOC_16C_IMM32_C
+ NS CR16C Relocations.
+
+ -- : BFD_RELOC_CR16_NUM8
+ -- : BFD_RELOC_CR16_NUM16
+ -- : BFD_RELOC_CR16_NUM32
+ -- : BFD_RELOC_CR16_NUM32a
+ -- : BFD_RELOC_CR16_REGREL0
+ -- : BFD_RELOC_CR16_REGREL4
+ -- : BFD_RELOC_CR16_REGREL4a
+ -- : BFD_RELOC_CR16_REGREL14
+ -- : BFD_RELOC_CR16_REGREL14a
+ -- : BFD_RELOC_CR16_REGREL16
+ -- : BFD_RELOC_CR16_REGREL20
+ -- : BFD_RELOC_CR16_REGREL20a
+ -- : BFD_RELOC_CR16_ABS20
+ -- : BFD_RELOC_CR16_ABS24
+ -- : BFD_RELOC_CR16_IMM4
+ -- : BFD_RELOC_CR16_IMM8
+ -- : BFD_RELOC_CR16_IMM16
+ -- : BFD_RELOC_CR16_IMM20
+ -- : BFD_RELOC_CR16_IMM24
+ -- : BFD_RELOC_CR16_IMM32
+ -- : BFD_RELOC_CR16_IMM32a
+ -- : BFD_RELOC_CR16_DISP4
+ -- : BFD_RELOC_CR16_DISP8
+ -- : BFD_RELOC_CR16_DISP16
+ -- : BFD_RELOC_CR16_DISP20
+ -- : BFD_RELOC_CR16_DISP24
+ -- : BFD_RELOC_CR16_DISP24a
+ -- : BFD_RELOC_CR16_SWITCH8
+ -- : BFD_RELOC_CR16_SWITCH16
+ -- : BFD_RELOC_CR16_SWITCH32
+ -- : BFD_RELOC_CR16_GOT_REGREL20
+ -- : BFD_RELOC_CR16_GOTC_REGREL20
+ -- : BFD_RELOC_CR16_GLOB_DAT
+ NS CR16 Relocations.
+
+ -- : BFD_RELOC_CRX_REL4
+ -- : BFD_RELOC_CRX_REL8
+ -- : BFD_RELOC_CRX_REL8_CMP
+ -- : BFD_RELOC_CRX_REL16
+ -- : BFD_RELOC_CRX_REL24
+ -- : BFD_RELOC_CRX_REL32
+ -- : BFD_RELOC_CRX_REGREL12
+ -- : BFD_RELOC_CRX_REGREL22
+ -- : BFD_RELOC_CRX_REGREL28
+ -- : BFD_RELOC_CRX_REGREL32
+ -- : BFD_RELOC_CRX_ABS16
+ -- : BFD_RELOC_CRX_ABS32
+ -- : BFD_RELOC_CRX_NUM8
+ -- : BFD_RELOC_CRX_NUM16
+ -- : BFD_RELOC_CRX_NUM32
+ -- : BFD_RELOC_CRX_IMM16
+ -- : BFD_RELOC_CRX_IMM32
+ -- : BFD_RELOC_CRX_SWITCH8
+ -- : BFD_RELOC_CRX_SWITCH16
+ -- : BFD_RELOC_CRX_SWITCH32
+ NS CRX Relocations.
+
+ -- : BFD_RELOC_CRIS_BDISP8
+ -- : BFD_RELOC_CRIS_UNSIGNED_5
+ -- : BFD_RELOC_CRIS_SIGNED_6
+ -- : BFD_RELOC_CRIS_UNSIGNED_6
+ -- : BFD_RELOC_CRIS_SIGNED_8
+ -- : BFD_RELOC_CRIS_UNSIGNED_8
+ -- : BFD_RELOC_CRIS_SIGNED_16
+ -- : BFD_RELOC_CRIS_UNSIGNED_16
+ -- : BFD_RELOC_CRIS_LAPCQ_OFFSET
+ -- : BFD_RELOC_CRIS_UNSIGNED_4
+ These relocs are only used within the CRIS assembler. They are not
+ (at present) written to any object files.
+
+ -- : BFD_RELOC_CRIS_COPY
+ -- : BFD_RELOC_CRIS_GLOB_DAT
+ -- : BFD_RELOC_CRIS_JUMP_SLOT
+ -- : BFD_RELOC_CRIS_RELATIVE
+ Relocs used in ELF shared libraries for CRIS.
+
+ -- : BFD_RELOC_CRIS_32_GOT
+ 32-bit offset to symbol-entry within GOT.
+
+ -- : BFD_RELOC_CRIS_16_GOT
+ 16-bit offset to symbol-entry within GOT.
+
+ -- : BFD_RELOC_CRIS_32_GOTPLT
+ 32-bit offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_CRIS_16_GOTPLT
+ 16-bit offset to symbol-entry within GOT, with PLT handling.
+
+ -- : BFD_RELOC_CRIS_32_GOTREL
+ 32-bit offset to symbol, relative to GOT.
+
+ -- : BFD_RELOC_CRIS_32_PLT_GOTREL
+ 32-bit offset to symbol with PLT entry, relative to GOT.
+
+ -- : BFD_RELOC_CRIS_32_PLT_PCREL
+ 32-bit offset to symbol with PLT entry, relative to this
+ relocation.
+
+ -- : BFD_RELOC_CRIS_32_GOT_GD
+ -- : BFD_RELOC_CRIS_16_GOT_GD
+ -- : BFD_RELOC_CRIS_32_GD
+ -- : BFD_RELOC_CRIS_DTP
+ -- : BFD_RELOC_CRIS_32_DTPREL
+ -- : BFD_RELOC_CRIS_16_DTPREL
+ -- : BFD_RELOC_CRIS_32_GOT_TPREL
+ -- : BFD_RELOC_CRIS_16_GOT_TPREL
+ -- : BFD_RELOC_CRIS_32_TPREL
+ -- : BFD_RELOC_CRIS_16_TPREL
+ -- : BFD_RELOC_CRIS_DTPMOD
+ -- : BFD_RELOC_CRIS_32_IE
+ Relocs used in TLS code for CRIS.
+
+ -- : BFD_RELOC_860_COPY
+ -- : BFD_RELOC_860_GLOB_DAT
+ -- : BFD_RELOC_860_JUMP_SLOT
+ -- : BFD_RELOC_860_RELATIVE
+ -- : BFD_RELOC_860_PC26
+ -- : BFD_RELOC_860_PLT26
+ -- : BFD_RELOC_860_PC16
+ -- : BFD_RELOC_860_LOW0
+ -- : BFD_RELOC_860_SPLIT0
+ -- : BFD_RELOC_860_LOW1
+ -- : BFD_RELOC_860_SPLIT1
+ -- : BFD_RELOC_860_LOW2
+ -- : BFD_RELOC_860_SPLIT2
+ -- : BFD_RELOC_860_LOW3
+ -- : BFD_RELOC_860_LOGOT0
+ -- : BFD_RELOC_860_SPGOT0
+ -- : BFD_RELOC_860_LOGOT1
+ -- : BFD_RELOC_860_SPGOT1
+ -- : BFD_RELOC_860_LOGOTOFF0
+ -- : BFD_RELOC_860_SPGOTOFF0
+ -- : BFD_RELOC_860_LOGOTOFF1
+ -- : BFD_RELOC_860_SPGOTOFF1
+ -- : BFD_RELOC_860_LOGOTOFF2
+ -- : BFD_RELOC_860_LOGOTOFF3
+ -- : BFD_RELOC_860_LOPC
+ -- : BFD_RELOC_860_HIGHADJ
+ -- : BFD_RELOC_860_HAGOT
+ -- : BFD_RELOC_860_HAGOTOFF
+ -- : BFD_RELOC_860_HAPC
+ -- : BFD_RELOC_860_HIGH
+ -- : BFD_RELOC_860_HIGOT
+ -- : BFD_RELOC_860_HIGOTOFF
+ Intel i860 Relocations.
+
+ -- : BFD_RELOC_OPENRISC_ABS_26
+ -- : BFD_RELOC_OPENRISC_REL_26
+ OpenRISC Relocations.
+
+ -- : BFD_RELOC_H8_DIR16A8
+ -- : BFD_RELOC_H8_DIR16R8
+ -- : BFD_RELOC_H8_DIR24A8
+ -- : BFD_RELOC_H8_DIR24R8
+ -- : BFD_RELOC_H8_DIR32A16
+ H8 elf Relocations.
+
+ -- : BFD_RELOC_XSTORMY16_REL_12
+ -- : BFD_RELOC_XSTORMY16_12
+ -- : BFD_RELOC_XSTORMY16_24
+ -- : BFD_RELOC_XSTORMY16_FPTR16
+ Sony Xstormy16 Relocations.
+
+ -- : BFD_RELOC_RELC
+ Self-describing complex relocations.
+
+ -- : BFD_RELOC_XC16X_PAG
+ -- : BFD_RELOC_XC16X_POF
+ -- : BFD_RELOC_XC16X_SEG
+ -- : BFD_RELOC_XC16X_SOF
+ Infineon Relocations.
+
+ -- : BFD_RELOC_VAX_GLOB_DAT
+ -- : BFD_RELOC_VAX_JMP_SLOT
+ -- : BFD_RELOC_VAX_RELATIVE
+ Relocations used by VAX ELF.
+
+ -- : BFD_RELOC_MT_PC16
+ Morpho MT - 16 bit immediate relocation.
+
+ -- : BFD_RELOC_MT_HI16
+ Morpho MT - Hi 16 bits of an address.
+
+ -- : BFD_RELOC_MT_LO16
+ Morpho MT - Low 16 bits of an address.
+
+ -- : BFD_RELOC_MT_GNU_VTINHERIT
+ Morpho MT - Used to tell the linker which vtable entries are used.
+
+ -- : BFD_RELOC_MT_GNU_VTENTRY
+ Morpho MT - Used to tell the linker which vtable entries are used.
+
+ -- : BFD_RELOC_MT_PCINSN8
+ Morpho MT - 8 bit immediate relocation.
+
+ -- : BFD_RELOC_MSP430_10_PCREL
+ -- : BFD_RELOC_MSP430_16_PCREL
+ -- : BFD_RELOC_MSP430_16
+ -- : BFD_RELOC_MSP430_16_PCREL_BYTE
+ -- : BFD_RELOC_MSP430_16_BYTE
+ -- : BFD_RELOC_MSP430_2X_PCREL
+ -- : BFD_RELOC_MSP430_RL_PCREL
+ msp430 specific relocation codes
+
+ -- : BFD_RELOC_IQ2000_OFFSET_16
+ -- : BFD_RELOC_IQ2000_OFFSET_21
+ -- : BFD_RELOC_IQ2000_UHI16
+ IQ2000 Relocations.
+
+ -- : BFD_RELOC_XTENSA_RTLD
+ Special Xtensa relocation used only by PLT entries in ELF shared
+ objects to indicate that the runtime linker should set the value
+ to one of its own internal functions or data structures.
+
+ -- : BFD_RELOC_XTENSA_GLOB_DAT
+ -- : BFD_RELOC_XTENSA_JMP_SLOT
+ -- : BFD_RELOC_XTENSA_RELATIVE
+ Xtensa relocations for ELF shared objects.
+
+ -- : BFD_RELOC_XTENSA_PLT
+ Xtensa relocation used in ELF object files for symbols that may
+ require PLT entries. Otherwise, this is just a generic 32-bit
+ relocation.
+
+ -- : BFD_RELOC_XTENSA_DIFF8
+ -- : BFD_RELOC_XTENSA_DIFF16
+ -- : BFD_RELOC_XTENSA_DIFF32
+ Xtensa relocations to mark the difference of two local symbols.
+ These are only needed to support linker relaxation and can be
+ ignored when not relaxing. The field is set to the value of the
+ difference assuming no relaxation. The relocation encodes the
+ position of the first symbol so the linker can determine whether
+ to adjust the field value.
+
+ -- : BFD_RELOC_XTENSA_SLOT0_OP
+ -- : BFD_RELOC_XTENSA_SLOT1_OP
+ -- : BFD_RELOC_XTENSA_SLOT2_OP
+ -- : BFD_RELOC_XTENSA_SLOT3_OP
+ -- : BFD_RELOC_XTENSA_SLOT4_OP
+ -- : BFD_RELOC_XTENSA_SLOT5_OP
+ -- : BFD_RELOC_XTENSA_SLOT6_OP
+ -- : BFD_RELOC_XTENSA_SLOT7_OP
+ -- : BFD_RELOC_XTENSA_SLOT8_OP
+ -- : BFD_RELOC_XTENSA_SLOT9_OP
+ -- : BFD_RELOC_XTENSA_SLOT10_OP
+ -- : BFD_RELOC_XTENSA_SLOT11_OP
+ -- : BFD_RELOC_XTENSA_SLOT12_OP
+ -- : BFD_RELOC_XTENSA_SLOT13_OP
+ -- : BFD_RELOC_XTENSA_SLOT14_OP
+ Generic Xtensa relocations for instruction operands. Only the slot
+ number is encoded in the relocation. The relocation applies to the
+ last PC-relative immediate operand, or if there are no PC-relative
+ immediates, to the last immediate operand.
+
+ -- : BFD_RELOC_XTENSA_SLOT0_ALT
+ -- : BFD_RELOC_XTENSA_SLOT1_ALT
+ -- : BFD_RELOC_XTENSA_SLOT2_ALT
+ -- : BFD_RELOC_XTENSA_SLOT3_ALT
+ -- : BFD_RELOC_XTENSA_SLOT4_ALT
+ -- : BFD_RELOC_XTENSA_SLOT5_ALT
+ -- : BFD_RELOC_XTENSA_SLOT6_ALT
+ -- : BFD_RELOC_XTENSA_SLOT7_ALT
+ -- : BFD_RELOC_XTENSA_SLOT8_ALT
+ -- : BFD_RELOC_XTENSA_SLOT9_ALT
+ -- : BFD_RELOC_XTENSA_SLOT10_ALT
+ -- : BFD_RELOC_XTENSA_SLOT11_ALT
+ -- : BFD_RELOC_XTENSA_SLOT12_ALT
+ -- : BFD_RELOC_XTENSA_SLOT13_ALT
+ -- : BFD_RELOC_XTENSA_SLOT14_ALT
+ Alternate Xtensa relocations. Only the slot is encoded in the
+ relocation. The meaning of these relocations is opcode-specific.
+
+ -- : BFD_RELOC_XTENSA_OP0
+ -- : BFD_RELOC_XTENSA_OP1
+ -- : BFD_RELOC_XTENSA_OP2
+ Xtensa relocations for backward compatibility. These have all been
+ replaced by BFD_RELOC_XTENSA_SLOT0_OP.
+
+ -- : BFD_RELOC_XTENSA_ASM_EXPAND
+ Xtensa relocation to mark that the assembler expanded the
+ instructions from an original target. The expansion size is
+ encoded in the reloc size.
+
+ -- : BFD_RELOC_XTENSA_ASM_SIMPLIFY
+ Xtensa relocation to mark that the linker should simplify
+ assembler-expanded instructions. This is commonly used internally
+ by the linker after analysis of a BFD_RELOC_XTENSA_ASM_EXPAND.
+
+ -- : BFD_RELOC_XTENSA_TLSDESC_FN
+ -- : BFD_RELOC_XTENSA_TLSDESC_ARG
+ -- : BFD_RELOC_XTENSA_TLS_DTPOFF
+ -- : BFD_RELOC_XTENSA_TLS_TPOFF
+ -- : BFD_RELOC_XTENSA_TLS_FUNC
+ -- : BFD_RELOC_XTENSA_TLS_ARG
+ -- : BFD_RELOC_XTENSA_TLS_CALL
+ Xtensa TLS relocations.
+
+ -- : BFD_RELOC_Z80_DISP8
+ 8 bit signed offset in (ix+d) or (iy+d).
+
+ -- : BFD_RELOC_Z8K_DISP7
+ DJNZ offset.
+
+ -- : BFD_RELOC_Z8K_CALLR
+ CALR offset.
+
+ -- : BFD_RELOC_Z8K_IMM4L
+ 4 bit value.
+
+ -- : BFD_RELOC_LM32_CALL
+ -- : BFD_RELOC_LM32_BRANCH
+ -- : BFD_RELOC_LM32_16_GOT
+ -- : BFD_RELOC_LM32_GOTOFF_HI16
+ -- : BFD_RELOC_LM32_GOTOFF_LO16
+ -- : BFD_RELOC_LM32_COPY
+ -- : BFD_RELOC_LM32_GLOB_DAT
+ -- : BFD_RELOC_LM32_JMP_SLOT
+ -- : BFD_RELOC_LM32_RELATIVE
+ Lattice Mico32 relocations.
+
+ -- : BFD_RELOC_MACH_O_SECTDIFF
+ Difference between two section addreses. Must be followed by a
+ BFD_RELOC_MACH_O_PAIR.
+
+ -- : BFD_RELOC_MACH_O_PAIR
+ Mach-O generic relocations.
+
+ -- : BFD_RELOC_MICROBLAZE_32_LO
+ This is a 32 bit reloc for the microblaze that stores the low 16
+ bits of a value
+
+ -- : BFD_RELOC_MICROBLAZE_32_LO_PCREL
+ This is a 32 bit pc-relative reloc for the microblaze that stores
+ the low 16 bits of a value
+
+ -- : BFD_RELOC_MICROBLAZE_32_ROSDA
+ This is a 32 bit reloc for the microblaze that stores a value
+ relative to the read-only small data area anchor
+
+ -- : BFD_RELOC_MICROBLAZE_32_RWSDA
+ This is a 32 bit reloc for the microblaze that stores a value
+ relative to the read-write small data area anchor
+
+ -- : BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM
+ This is a 32 bit reloc for the microblaze to handle expressions of
+ the form "Symbol Op Symbol"
+
+ -- : BFD_RELOC_MICROBLAZE_64_NONE
+ This is a 64 bit reloc that stores the 32 bit pc relative value in
+ two words (with an imm instruction). No relocation is done here -
+ only used for relaxing
+
+ -- : BFD_RELOC_MICROBLAZE_64_GOTPC
+ This is a 64 bit reloc that stores the 32 bit pc relative value in
+ two words (with an imm instruction). The relocation is
+ PC-relative GOT offset
+
+ -- : BFD_RELOC_MICROBLAZE_64_GOT
+ This is a 64 bit reloc that stores the 32 bit pc relative value in
+ two words (with an imm instruction). The relocation is GOT offset
+
+ -- : BFD_RELOC_MICROBLAZE_64_PLT
+ This is a 64 bit reloc that stores the 32 bit pc relative value in
+ two words (with an imm instruction). The relocation is
+ PC-relative offset into PLT
+
+ -- : BFD_RELOC_MICROBLAZE_64_GOTOFF
+ This is a 64 bit reloc that stores the 32 bit GOT relative value
+ in two words (with an imm instruction). The relocation is
+ relative offset from _GLOBAL_OFFSET_TABLE_
+
+ -- : BFD_RELOC_MICROBLAZE_32_GOTOFF
+ This is a 32 bit reloc that stores the 32 bit GOT relative value
+ in a word. The relocation is relative offset from
+
+ -- : BFD_RELOC_MICROBLAZE_COPY
+ This is used to tell the dynamic linker to copy the value out of
+ the dynamic object into the runtime process image.
+
+
+ typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
+
+2.10.2.2 `bfd_reloc_type_lookup'
+................................
+
+*Synopsis*
+ reloc_howto_type *bfd_reloc_type_lookup
+ (bfd *abfd, bfd_reloc_code_real_type code);
+ reloc_howto_type *bfd_reloc_name_lookup
+ (bfd *abfd, const char *reloc_name);
+ *Description*
+Return a pointer to a howto structure which, when invoked, will perform
+the relocation CODE on data from the architecture noted.
+
+2.10.2.3 `bfd_default_reloc_type_lookup'
+........................................
+
+*Synopsis*
+ reloc_howto_type *bfd_default_reloc_type_lookup
+ (bfd *abfd, bfd_reloc_code_real_type code);
+ *Description*
+Provides a default relocation lookup routine for any architecture.
+
+2.10.2.4 `bfd_get_reloc_code_name'
+..................................
+
+*Synopsis*
+ const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code);
+ *Description*
+Provides a printable name for the supplied relocation code. Useful
+mainly for printing error messages.
+
+2.10.2.5 `bfd_generic_relax_section'
+....................................
+
+*Synopsis*
+ bfd_boolean bfd_generic_relax_section
+ (bfd *abfd,
+ asection *section,
+ struct bfd_link_info *,
+ bfd_boolean *);
+ *Description*
+Provides default handling for relaxing for back ends which don't do
+relaxing.
+
+2.10.2.6 `bfd_generic_gc_sections'
+..................................
+
+*Synopsis*
+ bfd_boolean bfd_generic_gc_sections
+ (bfd *, struct bfd_link_info *);
+ *Description*
+Provides default handling for relaxing for back ends which don't do
+section gc - i.e., does nothing.
+
+2.10.2.7 `bfd_generic_merge_sections'
+.....................................
+
+*Synopsis*
+ bfd_boolean bfd_generic_merge_sections
+ (bfd *, struct bfd_link_info *);
+ *Description*
+Provides default handling for SEC_MERGE section merging for back ends
+which don't have SEC_MERGE support - i.e., does nothing.
+
+2.10.2.8 `bfd_generic_get_relocated_section_contents'
+.....................................................
+
+*Synopsis*
+ bfd_byte *bfd_generic_get_relocated_section_contents
+ (bfd *abfd,
+ struct bfd_link_info *link_info,
+ struct bfd_link_order *link_order,
+ bfd_byte *data,
+ bfd_boolean relocatable,
+ asymbol **symbols);
+ *Description*
+Provides default handling of relocation effort for back ends which
+can't be bothered to do it efficiently.
+
+
+File: bfd.info, Node: Core Files, Next: Targets, Prev: Relocations, Up: BFD front end
+
+2.11 Core files
+===============
+
+2.11.1 Core file functions
+--------------------------
+
+*Description*
+These are functions pertaining to core files.
+
+2.11.1.1 `bfd_core_file_failing_command'
+........................................
+
+*Synopsis*
+ const char *bfd_core_file_failing_command (bfd *abfd);
+ *Description*
+Return a read-only string explaining which program was running when it
+failed and produced the core file ABFD.
+
+2.11.1.2 `bfd_core_file_failing_signal'
+.......................................
+
+*Synopsis*
+ int bfd_core_file_failing_signal (bfd *abfd);
+ *Description*
+Returns the signal number which caused the core dump which generated
+the file the BFD ABFD is attached to.
+
+2.11.1.3 `core_file_matches_executable_p'
+.........................................
+
+*Synopsis*
+ bfd_boolean core_file_matches_executable_p
+ (bfd *core_bfd, bfd *exec_bfd);
+ *Description*
+Return `TRUE' if the core file attached to CORE_BFD was generated by a
+run of the executable file attached to EXEC_BFD, `FALSE' otherwise.
+
+2.11.1.4 `generic_core_file_matches_executable_p'
+.................................................
+
+*Synopsis*
+ bfd_boolean generic_core_file_matches_executable_p
+ (bfd *core_bfd, bfd *exec_bfd);
+ *Description*
+Return TRUE if the core file attached to CORE_BFD was generated by a
+run of the executable file attached to EXEC_BFD. The match is based on
+executable basenames only.
+
+ Note: When not able to determine the core file failing command or
+the executable name, we still return TRUE even though we're not sure
+that core file and executable match. This is to avoid generating a
+false warning in situations where we really don't know whether they
+match or not.
+
+
+File: bfd.info, Node: Targets, Next: Architectures, Prev: Core Files, Up: BFD front end
+
+2.12 Targets
+============
+
+*Description*
+Each port of BFD to a different machine requires 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:
+
+ * Create a BFD by calling the internal routine `_bfd_new_bfd', then
+ call `bfd_find_target' with the target string supplied to
+ `bfd_openr' and the new BFD pointer.
+
+ * If a null target string was provided to `bfd_find_target', look up
+ the environment variable `GNUTARGET' and use that as the target
+ string.
+
+ * If the target string is still `NULL', or the target string is
+ `default', then use the first item in the target vector as the
+ target type, and set `target_defaulted' in the BFD to cause
+ `bfd_check_format' to loop through all the targets. *Note
+ bfd_target::. *Note Formats::.
+
+ * Otherwise, inspect the elements in the target vector one by one,
+ until a match on target name is found. When found, use it.
+
+ * Otherwise return the error `bfd_error_invalid_target' 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. `bfd_check_format' returns `TRUE' when the caller
+guesses right.
+
+* Menu:
+
+* bfd_target::
+
+
+File: bfd.info, Node: bfd_target, Prev: Targets, Up: Targets
+
+2.12.1 bfd_target
+-----------------
+
+*Description*
+This structure contains everything that BFD knows about a target. It
+includes things like its byte order, name, and which routines to call
+to do various operations.
+
+ Every BFD points to a target structure with its `xvec' member.
+
+ The macros below 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)
+
+ #ifdef DEBUG_BFD_SEND
+ #undef BFD_SEND
+ #define BFD_SEND(bfd, message, arglist) \
+ (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
+ ((*((bfd)->xvec->message)) arglist) : \
+ (bfd_assert (__FILE__,__LINE__), NULL))
+ #endif
+ For operations which index on the BFD format:
+ #define BFD_SEND_FMT(bfd, message, arglist) \
+ (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist)
+
+ #ifdef DEBUG_BFD_SEND
+ #undef BFD_SEND_FMT
+ #define BFD_SEND_FMT(bfd, message, arglist) \
+ (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
+ (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \
+ (bfd_assert (__FILE__,__LINE__), NULL))
+ #endif
+ This is the structure 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!
+ enum bfd_flavour
+ {
+ bfd_target_unknown_flavour,
+ bfd_target_aout_flavour,
+ bfd_target_coff_flavour,
+ bfd_target_ecoff_flavour,
+ bfd_target_xcoff_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_verilog_flavour,
+ bfd_target_ihex_flavour,
+ bfd_target_som_flavour,
+ bfd_target_os9k_flavour,
+ bfd_target_versados_flavour,
+ bfd_target_msdos_flavour,
+ bfd_target_ovax_flavour,
+ bfd_target_evax_flavour,
+ bfd_target_mmo_flavour,
+ bfd_target_mach_o_flavour,
+ bfd_target_pef_flavour,
+ bfd_target_pef_xlib_flavour,
+ bfd_target_sym_flavour
+ };
+
+ enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN };
+
+ /* Forward declaration. */
+ typedef struct bfd_link_info _bfd_link_info;
+
+ typedef struct bfd_target
+ {
+ /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */
+ char *name;
+
+ /* The "flavour" of a back end is a general indication about
+ the contents of a file. */
+ enum bfd_flavour flavour;
+
+ /* The order of bytes within the data area of a file. */
+ enum bfd_endian byteorder;
+
+ /* The order of bytes within the header parts of a file. */
+ enum bfd_endian header_byteorder;
+
+ /* A mask of all the flags which an executable may have set -
+ from the set `BFD_NO_FLAGS', `HAS_RELOC', ...`D_PAGED'. */
+ flagword object_flags;
+
+ /* 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 file names within an archive header. */
+ char ar_pad_char;
+
+ /* The maximum number of characters in an archive header. */
+ unsigned short ar_max_namelen;
+
+ /* Entries for byte swapping for data. These are different from the
+ other entry points, since they don't take a BFD as the first argument.
+ Certain other handlers could do the same. */
+ bfd_uint64_t (*bfd_getx64) (const void *);
+ bfd_int64_t (*bfd_getx_signed_64) (const void *);
+ void (*bfd_putx64) (bfd_uint64_t, void *);
+ bfd_vma (*bfd_getx32) (const void *);
+ bfd_signed_vma (*bfd_getx_signed_32) (const void *);
+ void (*bfd_putx32) (bfd_vma, void *);
+ bfd_vma (*bfd_getx16) (const void *);
+ bfd_signed_vma (*bfd_getx_signed_16) (const void *);
+ void (*bfd_putx16) (bfd_vma, void *);
+
+ /* Byte swapping for the headers. */
+ bfd_uint64_t (*bfd_h_getx64) (const void *);
+ bfd_int64_t (*bfd_h_getx_signed_64) (const void *);
+ void (*bfd_h_putx64) (bfd_uint64_t, void *);
+ bfd_vma (*bfd_h_getx32) (const void *);
+ bfd_signed_vma (*bfd_h_getx_signed_32) (const void *);
+ void (*bfd_h_putx32) (bfd_vma, void *);
+ bfd_vma (*bfd_h_getx16) (const void *);
+ bfd_signed_vma (*bfd_h_getx_signed_16) (const void *);
+ void (*bfd_h_putx16) (bfd_vma, void *);
+
+ /* 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 a `bfd_target *' or zero. */
+ const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *);
+
+ /* Set the format of a file being written. */
+ bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *);
+
+ /* Write cached information into a file being written, at `bfd_close'. */
+ bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *);
+ The general target vector. These vectors are initialized using the
+BFD_JUMP_TABLE macros.
+
+ /* Generic entry points. */
+ #define BFD_JUMP_TABLE_GENERIC(NAME) \
+ NAME##_close_and_cleanup, \
+ NAME##_bfd_free_cached_info, \
+ NAME##_new_section_hook, \
+ NAME##_get_section_contents, \
+ NAME##_get_section_contents_in_window
+
+ /* Called when the BFD is being closed to do any necessary cleanup. */
+ bfd_boolean (*_close_and_cleanup) (bfd *);
+ /* Ask the BFD to free all cached information. */
+ bfd_boolean (*_bfd_free_cached_info) (bfd *);
+ /* Called when a new section is created. */
+ bfd_boolean (*_new_section_hook) (bfd *, sec_ptr);
+ /* Read the contents of a section. */
+ bfd_boolean (*_bfd_get_section_contents)
+ (bfd *, sec_ptr, void *, file_ptr, bfd_size_type);
+ bfd_boolean (*_bfd_get_section_contents_in_window)
+ (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type);
+
+ /* Entry points to copy private data. */
+ #define BFD_JUMP_TABLE_COPY(NAME) \
+ NAME##_bfd_copy_private_bfd_data, \
+ NAME##_bfd_merge_private_bfd_data, \
+ _bfd_generic_init_private_section_data, \
+ NAME##_bfd_copy_private_section_data, \
+ NAME##_bfd_copy_private_symbol_data, \
+ NAME##_bfd_copy_private_header_data, \
+ NAME##_bfd_set_private_flags, \
+ NAME##_bfd_print_private_bfd_data
+
+ /* Called to copy BFD general private data from one object file
+ to another. */
+ bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
+ /* Called to merge BFD general private data from one object file
+ to a common output file when linking. */
+ bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
+ /* Called to initialize BFD private section data from one object file
+ to another. */
+ #define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \
+ BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info))
+ bfd_boolean (*_bfd_init_private_section_data)
+ (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *);
+ /* Called to copy BFD private section data from one object file
+ to another. */
+ bfd_boolean (*_bfd_copy_private_section_data)
+ (bfd *, sec_ptr, bfd *, sec_ptr);
+ /* Called to copy BFD private symbol data from one symbol
+ to another. */
+ bfd_boolean (*_bfd_copy_private_symbol_data)
+ (bfd *, asymbol *, bfd *, asymbol *);
+ /* Called to copy BFD private header data from one object file
+ to another. */
+ bfd_boolean (*_bfd_copy_private_header_data)
+ (bfd *, bfd *);
+ /* Called to set private backend flags. */
+ bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
+
+ /* Called to print private BFD data. */
+ bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
+
+ /* Core file entry points. */
+ #define BFD_JUMP_TABLE_CORE(NAME) \
+ NAME##_core_file_failing_command, \
+ NAME##_core_file_failing_signal, \
+ NAME##_core_file_matches_executable_p
+
+ char * (*_core_file_failing_command) (bfd *);
+ int (*_core_file_failing_signal) (bfd *);
+ bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
+
+ /* Archive entry points. */
+ #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
+ NAME##_slurp_armap, \
+ NAME##_slurp_extended_name_table, \
+ NAME##_construct_extended_name_table, \
+ NAME##_truncate_arname, \
+ NAME##_write_armap, \
+ NAME##_read_ar_hdr, \
+ NAME##_openr_next_archived_file, \
+ NAME##_get_elt_at_index, \
+ NAME##_generic_stat_arch_elt, \
+ NAME##_update_armap_timestamp
+
+ bfd_boolean (*_bfd_slurp_armap) (bfd *);
+ bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
+ bfd_boolean (*_bfd_construct_extended_name_table)
+ (bfd *, char **, bfd_size_type *, const char **);
+ void (*_bfd_truncate_arname) (bfd *, const char *, char *);
+ bfd_boolean (*write_armap)
+ (bfd *, unsigned int, struct orl *, unsigned int, int);
+ void * (*_bfd_read_ar_hdr_fn) (bfd *);
+ bfd * (*openr_next_archived_file) (bfd *, bfd *);
+ #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
+ bfd * (*_bfd_get_elt_at_index) (bfd *, symindex);
+ int (*_bfd_stat_arch_elt) (bfd *, struct stat *);
+ bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
+
+ /* Entry points used for symbols. */
+ #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
+ NAME##_get_symtab_upper_bound, \
+ NAME##_canonicalize_symtab, \
+ NAME##_make_empty_symbol, \
+ NAME##_print_symbol, \
+ NAME##_get_symbol_info, \
+ NAME##_bfd_is_local_label_name, \
+ NAME##_bfd_is_target_special_symbol, \
+ NAME##_get_lineno, \
+ NAME##_find_nearest_line, \
+ _bfd_generic_find_line, \
+ NAME##_find_inliner_info, \
+ NAME##_bfd_make_debug_symbol, \
+ NAME##_read_minisymbols, \
+ NAME##_minisymbol_to_symbol
+
+ long (*_bfd_get_symtab_upper_bound) (bfd *);
+ long (*_bfd_canonicalize_symtab)
+ (bfd *, struct bfd_symbol **);
+ struct bfd_symbol *
+ (*_bfd_make_empty_symbol) (bfd *);
+ void (*_bfd_print_symbol)
+ (bfd *, void *, struct bfd_symbol *, 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)
+ (bfd *, struct bfd_symbol *, symbol_info *);
+ #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
+ bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
+ bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *);
+ alent * (*_get_lineno) (bfd *, struct bfd_symbol *);
+ bfd_boolean (*_bfd_find_nearest_line)
+ (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
+ const char **, const char **, unsigned int *);
+ bfd_boolean (*_bfd_find_line)
+ (bfd *, struct bfd_symbol **, struct bfd_symbol *,
+ const char **, unsigned int *);
+ bfd_boolean (*_bfd_find_inliner_info)
+ (bfd *, const char **, const char **, unsigned int *);
+ /* 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)
+ (bfd *, void *, unsigned long size);
+ #define bfd_read_minisymbols(b, d, m, s) \
+ BFD_SEND (b, _read_minisymbols, (b, d, m, s))
+ long (*_read_minisymbols)
+ (bfd *, bfd_boolean, void **, unsigned int *);
+ #define bfd_minisymbol_to_symbol(b, d, m, f) \
+ BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
+ asymbol * (*_minisymbol_to_symbol)
+ (bfd *, bfd_boolean, const void *, asymbol *);
+
+ /* Routines for relocs. */
+ #define BFD_JUMP_TABLE_RELOCS(NAME) \
+ NAME##_get_reloc_upper_bound, \
+ NAME##_canonicalize_reloc, \
+ NAME##_bfd_reloc_type_lookup, \
+ NAME##_bfd_reloc_name_lookup
+
+ long (*_get_reloc_upper_bound) (bfd *, sec_ptr);
+ long (*_bfd_canonicalize_reloc)
+ (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
+ /* See documentation on reloc types. */
+ reloc_howto_type *
+ (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
+ reloc_howto_type *
+ (*reloc_name_lookup) (bfd *, const char *);
+
+
+ /* Routines used when writing an object file. */
+ #define BFD_JUMP_TABLE_WRITE(NAME) \
+ NAME##_set_arch_mach, \
+ NAME##_set_section_contents
+
+ bfd_boolean (*_bfd_set_arch_mach)
+ (bfd *, enum bfd_architecture, unsigned long);
+ bfd_boolean (*_bfd_set_section_contents)
+ (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
+
+ /* Routines used by the linker. */
+ #define BFD_JUMP_TABLE_LINK(NAME) \
+ NAME##_sizeof_headers, \
+ NAME##_bfd_get_relocated_section_contents, \
+ NAME##_bfd_relax_section, \
+ NAME##_bfd_link_hash_table_create, \
+ NAME##_bfd_link_hash_table_free, \
+ NAME##_bfd_link_add_symbols, \
+ NAME##_bfd_link_just_syms, \
+ NAME##_bfd_final_link, \
+ NAME##_bfd_link_split_section, \
+ NAME##_bfd_gc_sections, \
+ NAME##_bfd_merge_sections, \
+ NAME##_bfd_is_group_section, \
+ NAME##_bfd_discard_group, \
+ NAME##_section_already_linked, \
+ NAME##_bfd_define_common_symbol
+
+ int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *);
+ bfd_byte * (*_bfd_get_relocated_section_contents)
+ (bfd *, struct bfd_link_info *, struct bfd_link_order *,
+ bfd_byte *, bfd_boolean, struct bfd_symbol **);
+
+ bfd_boolean (*_bfd_relax_section)
+ (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
+
+ /* Create a hash table for the linker. Different backends store
+ different information in this table. */
+ struct bfd_link_hash_table *
+ (*_bfd_link_hash_table_create) (bfd *);
+
+ /* Release the memory associated with the linker hash table. */
+ void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
+
+ /* Add symbols from this object file into the hash table. */
+ bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
+
+ /* Indicate that we are only retrieving symbol values from this section. */
+ void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
+
+ /* Do a link based on the link_order structures attached to each
+ section of the BFD. */
+ bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
+
+ /* Should this section be split up into smaller pieces during linking. */
+ bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
+
+ /* Remove sections that are not referenced from the output. */
+ bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
+
+ /* Attempt to merge SEC_MERGE sections. */
+ bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
+
+ /* Is this section a member of a group? */
+ bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *);
+
+ /* Discard members of a group. */
+ bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
+
+ /* Check if SEC has been already linked during a reloceatable or
+ final link. */
+ void (*_section_already_linked) (bfd *, struct bfd_section *,
+ struct bfd_link_info *);
+
+ /* Define a common symbol. */
+ bfd_boolean (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *,
+ struct bfd_link_hash_entry *);
+
+ /* Routines to handle dynamic symbols and relocs. */
+ #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
+ NAME##_get_dynamic_symtab_upper_bound, \
+ NAME##_canonicalize_dynamic_symtab, \
+ NAME##_get_synthetic_symtab, \
+ NAME##_get_dynamic_reloc_upper_bound, \
+ NAME##_canonicalize_dynamic_reloc
+
+ /* Get the amount of memory required to hold the dynamic symbols. */
+ long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
+ /* Read in the dynamic symbols. */
+ long (*_bfd_canonicalize_dynamic_symtab)
+ (bfd *, struct bfd_symbol **);
+ /* Create synthetized symbols. */
+ long (*_bfd_get_synthetic_symtab)
+ (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **,
+ struct bfd_symbol **);
+ /* Get the amount of memory required to hold the dynamic relocs. */
+ long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
+ /* Read in the dynamic relocs. */
+ long (*_bfd_canonicalize_dynamic_reloc)
+ (bfd *, arelent **, struct bfd_symbol **);
+ A pointer to an alternative bfd_target in case the current one is not
+satisfactory. This can happen when the target cpu supports both big
+and little endian code, and target chosen by the linker has the wrong
+endianness. The function open_output() in ld/ldlang.c uses this field
+to find an alternative output format that is suitable.
+ /* Opposite endian version of this target. */
+ const struct bfd_target * alternative_target;
+
+ /* Data for use by back-end routines, which isn't
+ generic enough to belong in this structure. */
+ const void *backend_data;
+
+ } bfd_target;
+
+2.12.1.1 `bfd_set_default_target'
+.................................
+
+*Synopsis*
+ bfd_boolean bfd_set_default_target (const char *name);
+ *Description*
+Set the default target vector to use when recognizing a BFD. This
+takes the name of the target, which may be a BFD target name or a
+configuration triplet.
+
+2.12.1.2 `bfd_find_target'
+..........................
+
+*Synopsis*
+ const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
+ *Description*
+Return a pointer to the transfer vector for the object target named
+TARGET_NAME. If TARGET_NAME is `NULL', choose the one in the
+environment variable `GNUTARGET'; if that is null or not defined, then
+choose the first entry in the target list. 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 if ABFD isn't `NULL'. This
+causes `bfd_check_format' to loop over all the targets to find the one
+that matches the file being read.
+
+2.12.1.3 `bfd_target_list'
+..........................
+
+*Synopsis*
+ const char ** bfd_target_list (void);
+ *Description*
+Return a freshly malloced NULL-terminated vector of the names of all
+the valid BFD targets. Do not modify the names.
+
+2.12.1.4 `bfd_seach_for_target'
+...............................
+
+*Synopsis*
+ const bfd_target *bfd_search_for_target
+ (int (*search_func) (const bfd_target *, void *),
+ void *);
+ *Description*
+Return a pointer to the first transfer vector in the list of transfer
+vectors maintained by BFD that produces a non-zero result when passed
+to the function SEARCH_FUNC. The parameter DATA is passed, unexamined,
+to the search function.
+
+
+File: bfd.info, Node: Architectures, Next: Opening and Closing, Prev: Targets, Up: BFD front end
+
+2.13 Architectures
+==================
+
+BFD keeps one atom in a BFD describing the architecture of the data
+attached to the BFD: a pointer to a `bfd_arch_info_type'.
+
+ Pointers to structures can be requested independently of a BFD so
+that an architecture's information can be interrogated without access
+to an open BFD.
+
+ The architecture information is provided by each architecture
+package. The set of default architectures is selected by the macro
+`SELECT_ARCHITECTURES'. This is normally set up in the
+`config/TARGET.mt' file of your choice. If the name is not defined,
+then all the architectures supported are included.
+
+ When BFD starts up, all the architectures are called with an
+initialize method. It is up to the architecture back end to insert as
+many items into the list of architectures as it wants to; generally
+this would be one for each machine and one for the default case (an
+item with a machine field of 0).
+
+ BFD's idea of an architecture is implemented in `archures.c'.
+
+2.13.1 bfd_architecture
+-----------------------
+
+*Description*
+This enum gives the object file's CPU architecture, in a global
+sense--i.e., what processor family does it belong to? Another field
+indicates which processor within the family is in use. The machine
+gives a number which distinguishes different versions of the
+architecture, containing, for example, 2 and 3 for Intel i960 KA and
+i960 KB, and 68020 and 68030 for Motorola 68020 and 68030.
+ enum bfd_architecture
+ {
+ bfd_arch_unknown, /* File arch not known. */
+ bfd_arch_obscure, /* Arch known, not one of these. */
+ bfd_arch_m68k, /* Motorola 68xxx */
+ #define bfd_mach_m68000 1
+ #define bfd_mach_m68008 2
+ #define bfd_mach_m68010 3
+ #define bfd_mach_m68020 4
+ #define bfd_mach_m68030 5
+ #define bfd_mach_m68040 6
+ #define bfd_mach_m68060 7
+ #define bfd_mach_cpu32 8
+ #define bfd_mach_fido 9
+ #define bfd_mach_mcf_isa_a_nodiv 10
+ #define bfd_mach_mcf_isa_a 11
+ #define bfd_mach_mcf_isa_a_mac 12
+ #define bfd_mach_mcf_isa_a_emac 13
+ #define bfd_mach_mcf_isa_aplus 14
+ #define bfd_mach_mcf_isa_aplus_mac 15
+ #define bfd_mach_mcf_isa_aplus_emac 16
+ #define bfd_mach_mcf_isa_b_nousp 17
+ #define bfd_mach_mcf_isa_b_nousp_mac 18
+ #define bfd_mach_mcf_isa_b_nousp_emac 19
+ #define bfd_mach_mcf_isa_b 20
+ #define bfd_mach_mcf_isa_b_mac 21
+ #define bfd_mach_mcf_isa_b_emac 22
+ #define bfd_mach_mcf_isa_b_float 23
+ #define bfd_mach_mcf_isa_b_float_mac 24
+ #define bfd_mach_mcf_isa_b_float_emac 25
+ #define bfd_mach_mcf_isa_c 26
+ #define bfd_mach_mcf_isa_c_mac 27
+ #define bfd_mach_mcf_isa_c_emac 28
+ #define bfd_mach_mcf_isa_c_nodiv 29
+ #define bfd_mach_mcf_isa_c_nodiv_mac 30
+ #define bfd_mach_mcf_isa_c_nodiv_emac 31
+ bfd_arch_vax, /* DEC Vax */
+ bfd_arch_i960, /* Intel 960 */
+ /* The order of the following is important.
+ lower number indicates a machine type that
+ only accepts a subset of the instructions
+ available to machines with higher numbers.
+ The exception is the "ca", which is
+ incompatible with all other machines except
+ "core". */
+
+ #define bfd_mach_i960_core 1
+ #define bfd_mach_i960_ka_sa 2
+ #define bfd_mach_i960_kb_sb 3
+ #define bfd_mach_i960_mc 4
+ #define bfd_mach_i960_xa 5
+ #define bfd_mach_i960_ca 6
+ #define bfd_mach_i960_jx 7
+ #define bfd_mach_i960_hx 8
+
+ bfd_arch_or32, /* OpenRISC 32 */
+
+ bfd_arch_sparc, /* SPARC */
+ #define bfd_mach_sparc 1
+ /* The difference between v8plus and v9 is that v9 is a true 64 bit env. */
+ #define bfd_mach_sparc_sparclet 2
+ #define bfd_mach_sparc_sparclite 3
+ #define bfd_mach_sparc_v8plus 4
+ #define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */
+ #define bfd_mach_sparc_sparclite_le 6
+ #define bfd_mach_sparc_v9 7
+ #define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */
+ #define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */
+ #define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */
+ /* Nonzero if MACH has the v9 instruction set. */
+ #define bfd_mach_sparc_v9_p(mach) \
+ ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \
+ && (mach) != bfd_mach_sparc_sparclite_le)
+ /* Nonzero if MACH is a 64 bit sparc architecture. */
+ #define bfd_mach_sparc_64bit_p(mach) \
+ ((mach) >= bfd_mach_sparc_v9 && (mach) != bfd_mach_sparc_v8plusb)
+ bfd_arch_spu, /* PowerPC SPU */
+ #define bfd_mach_spu 256
+ bfd_arch_mips, /* MIPS Rxxxx */
+ #define bfd_mach_mips3000 3000
+ #define bfd_mach_mips3900 3900
+ #define bfd_mach_mips4000 4000
+ #define bfd_mach_mips4010 4010
+ #define bfd_mach_mips4100 4100
+ #define bfd_mach_mips4111 4111
+ #define bfd_mach_mips4120 4120
+ #define bfd_mach_mips4300 4300
+ #define bfd_mach_mips4400 4400
+ #define bfd_mach_mips4600 4600
+ #define bfd_mach_mips4650 4650
+ #define bfd_mach_mips5000 5000
+ #define bfd_mach_mips5400 5400
+ #define bfd_mach_mips5500 5500
+ #define bfd_mach_mips6000 6000
+ #define bfd_mach_mips7000 7000
+ #define bfd_mach_mips8000 8000
+ #define bfd_mach_mips9000 9000
+ #define bfd_mach_mips10000 10000
+ #define bfd_mach_mips12000 12000
+ #define bfd_mach_mips14000 14000
+ #define bfd_mach_mips16000 16000
+ #define bfd_mach_mips16 16
+ #define bfd_mach_mips5 5
+ #define bfd_mach_mips_loongson_2e 3001
+ #define bfd_mach_mips_loongson_2f 3002
+ #define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01 */
+ #define bfd_mach_mips_octeon 6501
+ #define bfd_mach_mips_xlr 887682 /* decimal 'XLR' */
+ #define bfd_mach_mipsisa32 32
+ #define bfd_mach_mipsisa32r2 33
+ #define bfd_mach_mipsisa64 64
+ #define bfd_mach_mipsisa64r2 65
+ bfd_arch_i386, /* Intel 386 */
+ #define bfd_mach_i386_i386 1
+ #define bfd_mach_i386_i8086 2
+ #define bfd_mach_i386_i386_intel_syntax 3
+ #define bfd_mach_x86_64 64
+ #define bfd_mach_x86_64_intel_syntax 65
+ bfd_arch_l1om, /* Intel L1OM */
+ #define bfd_mach_l1om 66
+ #define bfd_mach_l1om_intel_syntax 67
+ bfd_arch_we32k, /* AT&T WE32xxx */
+ bfd_arch_tahoe, /* CCI/Harris Tahoe */
+ bfd_arch_i860, /* Intel 860 */
+ bfd_arch_i370, /* IBM 360/370 Mainframes */
+ bfd_arch_romp, /* IBM ROMP PC/RT */
+ bfd_arch_convex, /* Convex */
+ bfd_arch_m88k, /* Motorola 88xxx */
+ bfd_arch_m98k, /* Motorola 98xxx */
+ bfd_arch_pyramid, /* Pyramid Technology */
+ bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300) */
+ #define bfd_mach_h8300 1
+ #define bfd_mach_h8300h 2
+ #define bfd_mach_h8300s 3
+ #define bfd_mach_h8300hn 4
+ #define bfd_mach_h8300sn 5
+ #define bfd_mach_h8300sx 6
+ #define bfd_mach_h8300sxn 7
+ bfd_arch_pdp11, /* DEC PDP-11 */
+ bfd_arch_plugin,
+ bfd_arch_powerpc, /* PowerPC */
+ #define bfd_mach_ppc 32
+ #define bfd_mach_ppc64 64
+ #define bfd_mach_ppc_403 403
+ #define bfd_mach_ppc_403gc 4030
+ #define bfd_mach_ppc_405 405
+ #define bfd_mach_ppc_505 505
+ #define bfd_mach_ppc_601 601
+ #define bfd_mach_ppc_602 602
+ #define bfd_mach_ppc_603 603
+ #define bfd_mach_ppc_ec603e 6031
+ #define bfd_mach_ppc_604 604
+ #define bfd_mach_ppc_620 620
+ #define bfd_mach_ppc_630 630
+ #define bfd_mach_ppc_750 750
+ #define bfd_mach_ppc_860 860
+ #define bfd_mach_ppc_a35 35
+ #define bfd_mach_ppc_rs64ii 642
+ #define bfd_mach_ppc_rs64iii 643
+ #define bfd_mach_ppc_7400 7400
+ #define bfd_mach_ppc_e500 500
+ #define bfd_mach_ppc_e500mc 5001
+ bfd_arch_rs6000, /* IBM RS/6000 */
+ #define bfd_mach_rs6k 6000
+ #define bfd_mach_rs6k_rs1 6001
+ #define bfd_mach_rs6k_rsc 6003
+ #define bfd_mach_rs6k_rs2 6002
+ bfd_arch_hppa, /* HP PA RISC */
+ #define bfd_mach_hppa10 10
+ #define bfd_mach_hppa11 11
+ #define bfd_mach_hppa20 20
+ #define bfd_mach_hppa20w 25
+ bfd_arch_d10v, /* Mitsubishi D10V */
+ #define bfd_mach_d10v 1
+ #define bfd_mach_d10v_ts2 2
+ #define bfd_mach_d10v_ts3 3
+ bfd_arch_d30v, /* Mitsubishi D30V */
+ bfd_arch_dlx, /* DLX */
+ bfd_arch_m68hc11, /* Motorola 68HC11 */
+ bfd_arch_m68hc12, /* Motorola 68HC12 */
+ #define bfd_mach_m6812_default 0
+ #define bfd_mach_m6812 1
+ #define bfd_mach_m6812s 2
+ bfd_arch_z8k, /* Zilog Z8000 */
+ #define bfd_mach_z8001 1
+ #define bfd_mach_z8002 2
+ bfd_arch_h8500, /* Renesas H8/500 (formerly Hitachi H8/500) */
+ bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH) */
+ #define bfd_mach_sh 1
+ #define bfd_mach_sh2 0x20
+ #define bfd_mach_sh_dsp 0x2d
+ #define bfd_mach_sh2a 0x2a
+ #define bfd_mach_sh2a_nofpu 0x2b
+ #define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1
+ #define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2
+ #define bfd_mach_sh2a_or_sh4 0x2a3
+ #define bfd_mach_sh2a_or_sh3e 0x2a4
+ #define bfd_mach_sh2e 0x2e
+ #define bfd_mach_sh3 0x30
+ #define bfd_mach_sh3_nommu 0x31
+ #define bfd_mach_sh3_dsp 0x3d
+ #define bfd_mach_sh3e 0x3e
+ #define bfd_mach_sh4 0x40
+ #define bfd_mach_sh4_nofpu 0x41
+ #define bfd_mach_sh4_nommu_nofpu 0x42
+ #define bfd_mach_sh4a 0x4a
+ #define bfd_mach_sh4a_nofpu 0x4b
+ #define bfd_mach_sh4al_dsp 0x4d
+ #define bfd_mach_sh5 0x50
+ bfd_arch_alpha, /* Dec Alpha */
+ #define bfd_mach_alpha_ev4 0x10
+ #define bfd_mach_alpha_ev5 0x20
+ #define bfd_mach_alpha_ev6 0x30
+ bfd_arch_arm, /* Advanced Risc Machines ARM. */
+ #define bfd_mach_arm_unknown 0
+ #define bfd_mach_arm_2 1
+ #define bfd_mach_arm_2a 2
+ #define bfd_mach_arm_3 3
+ #define bfd_mach_arm_3M 4
+ #define bfd_mach_arm_4 5
+ #define bfd_mach_arm_4T 6
+ #define bfd_mach_arm_5 7
+ #define bfd_mach_arm_5T 8
+ #define bfd_mach_arm_5TE 9
+ #define bfd_mach_arm_XScale 10
+ #define bfd_mach_arm_ep9312 11
+ #define bfd_mach_arm_iWMMXt 12
+ #define bfd_mach_arm_iWMMXt2 13
+ bfd_arch_ns32k, /* National Semiconductors ns32000 */
+ bfd_arch_w65, /* WDC 65816 */
+ bfd_arch_tic30, /* Texas Instruments TMS320C30 */
+ bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X */
+ #define bfd_mach_tic3x 30
+ #define bfd_mach_tic4x 40
+ bfd_arch_tic54x, /* Texas Instruments TMS320C54X */
+ bfd_arch_tic80, /* TI TMS320c80 (MVP) */
+ bfd_arch_v850, /* NEC V850 */
+ #define bfd_mach_v850 1
+ #define bfd_mach_v850e 'E'
+ #define bfd_mach_v850e1 '1'
+ bfd_arch_arc, /* ARC Cores */
+ #define bfd_mach_arc_5 5
+ #define bfd_mach_arc_6 6
+ #define bfd_mach_arc_7 7
+ #define bfd_mach_arc_8 8
+ bfd_arch_m32c, /* Renesas M16C/M32C. */
+ #define bfd_mach_m16c 0x75
+ #define bfd_mach_m32c 0x78
+ bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D) */
+ #define bfd_mach_m32r 1 /* For backwards compatibility. */
+ #define bfd_mach_m32rx 'x'
+ #define bfd_mach_m32r2 '2'
+ bfd_arch_mn10200, /* Matsushita MN10200 */
+ bfd_arch_mn10300, /* Matsushita MN10300 */
+ #define bfd_mach_mn10300 300
+ #define bfd_mach_am33 330
+ #define bfd_mach_am33_2 332
+ bfd_arch_fr30,
+ #define bfd_mach_fr30 0x46523330
+ bfd_arch_frv,
+ #define bfd_mach_frv 1
+ #define bfd_mach_frvsimple 2
+ #define bfd_mach_fr300 300
+ #define bfd_mach_fr400 400
+ #define bfd_mach_fr450 450
+ #define bfd_mach_frvtomcat 499 /* fr500 prototype */
+ #define bfd_mach_fr500 500
+ #define bfd_mach_fr550 550
+ bfd_arch_moxie, /* The moxie processor */
+ #define bfd_mach_moxie 1
+ bfd_arch_mcore,
+ bfd_arch_mep,
+ #define bfd_mach_mep 1
+ #define bfd_mach_mep_h1 0x6831
+ #define bfd_mach_mep_c5 0x6335
+ bfd_arch_ia64, /* HP/Intel ia64 */
+ #define bfd_mach_ia64_elf64 64
+ #define bfd_mach_ia64_elf32 32
+ bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */
+ #define bfd_mach_ip2022 1
+ #define bfd_mach_ip2022ext 2
+ bfd_arch_iq2000, /* Vitesse IQ2000. */
+ #define bfd_mach_iq2000 1
+ #define bfd_mach_iq10 2
+ bfd_arch_mt,
+ #define bfd_mach_ms1 1
+ #define bfd_mach_mrisc2 2
+ #define bfd_mach_ms2 3
+ bfd_arch_pj,
+ bfd_arch_avr, /* Atmel AVR microcontrollers. */
+ #define bfd_mach_avr1 1
+ #define bfd_mach_avr2 2
+ #define bfd_mach_avr25 25
+ #define bfd_mach_avr3 3
+ #define bfd_mach_avr31 31
+ #define bfd_mach_avr35 35
+ #define bfd_mach_avr4 4
+ #define bfd_mach_avr5 5
+ #define bfd_mach_avr51 51
+ #define bfd_mach_avr6 6
+ bfd_arch_bfin, /* ADI Blackfin */
+ #define bfd_mach_bfin 1
+ bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */
+ #define bfd_mach_cr16 1
+ bfd_arch_cr16c, /* National Semiconductor CompactRISC. */
+ #define bfd_mach_cr16c 1
+ bfd_arch_crx, /* National Semiconductor CRX. */
+ #define bfd_mach_crx 1
+ bfd_arch_cris, /* Axis CRIS */
+ #define bfd_mach_cris_v0_v10 255
+ #define bfd_mach_cris_v32 32
+ #define bfd_mach_cris_v10_v32 1032
+ bfd_arch_s390, /* IBM s390 */
+ #define bfd_mach_s390_31 31
+ #define bfd_mach_s390_64 64
+ bfd_arch_score, /* Sunplus score */
+ #define bfd_mach_score3 3
+ #define bfd_mach_score7 7
+ bfd_arch_openrisc, /* OpenRISC */
+ bfd_arch_mmix, /* Donald Knuth's educational processor. */
+ bfd_arch_xstormy16,
+ #define bfd_mach_xstormy16 1
+ bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */
+ #define bfd_mach_msp11 11
+ #define bfd_mach_msp110 110
+ #define bfd_mach_msp12 12
+ #define bfd_mach_msp13 13
+ #define bfd_mach_msp14 14
+ #define bfd_mach_msp15 15
+ #define bfd_mach_msp16 16
+ #define bfd_mach_msp21 21
+ #define bfd_mach_msp31 31
+ #define bfd_mach_msp32 32
+ #define bfd_mach_msp33 33
+ #define bfd_mach_msp41 41
+ #define bfd_mach_msp42 42
+ #define bfd_mach_msp43 43
+ #define bfd_mach_msp44 44
+ bfd_arch_xc16x, /* Infineon's XC16X Series. */
+ #define bfd_mach_xc16x 1
+ #define bfd_mach_xc16xl 2
+ #define bfd_mach_xc16xs 3
+ bfd_arch_xtensa, /* Tensilica's Xtensa cores. */
+ #define bfd_mach_xtensa 1
+ bfd_arch_maxq, /* Dallas MAXQ 10/20 */
+ #define bfd_mach_maxq10 10
+ #define bfd_mach_maxq20 20
+ bfd_arch_z80,
+ #define bfd_mach_z80strict 1 /* No undocumented opcodes. */
+ #define bfd_mach_z80 3 /* With ixl, ixh, iyl, and iyh. */
+ #define bfd_mach_z80full 7 /* All undocumented instructions. */
+ #define bfd_mach_r800 11 /* R800: successor with multiplication. */
+ bfd_arch_lm32, /* Lattice Mico32 */
+ #define bfd_mach_lm32 1
+ bfd_arch_microblaze,/* Xilinx MicroBlaze. */
+ bfd_arch_last
+ };
+
+2.13.2 bfd_arch_info
+--------------------
+
+*Description*
+This structure contains information on architectures for use within BFD.
+
+ typedef struct bfd_arch_info
+ {
+ int bits_per_word;
+ int bits_per_address;
+ int bits_per_byte;
+ enum bfd_architecture arch;
+ unsigned long mach;
+ const char *arch_name;
+ const char *printable_name;
+ unsigned int section_align_power;
+ /* TRUE if this is the default machine for the architecture.
+ The default arch should be the first entry for an arch so that
+ all the entries for that arch can be accessed via `next'. */
+ bfd_boolean the_default;
+ const struct bfd_arch_info * (*compatible)
+ (const struct bfd_arch_info *a, const struct bfd_arch_info *b);
+
+ bfd_boolean (*scan) (const struct bfd_arch_info *, const char *);
+
+ const struct bfd_arch_info *next;
+ }
+ bfd_arch_info_type;
+
+2.13.2.1 `bfd_printable_name'
+.............................
+
+*Synopsis*
+ const char *bfd_printable_name (bfd *abfd);
+ *Description*
+Return a printable string representing the architecture and machine
+from the pointer to the architecture info structure.
+
+2.13.2.2 `bfd_scan_arch'
+........................
+
+*Synopsis*
+ const bfd_arch_info_type *bfd_scan_arch (const char *string);
+ *Description*
+Figure out if BFD supports any cpu which could be described with the
+name STRING. Return a pointer to an `arch_info' structure if a machine
+is found, otherwise NULL.
+
+2.13.2.3 `bfd_arch_list'
+........................
+
+*Synopsis*
+ const char **bfd_arch_list (void);
+ *Description*
+Return a freshly malloced NULL-terminated vector of the names of all
+the valid BFD architectures. Do not modify the names.
+
+2.13.2.4 `bfd_arch_get_compatible'
+..................................
+
+*Synopsis*
+ const bfd_arch_info_type *bfd_arch_get_compatible
+ (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns);
+ *Description*
+Determine whether two BFDs' architectures and machine types are
+compatible. Calculates the lowest common denominator between the two
+architectures and machine types implied by the BFDs and returns a
+pointer to an `arch_info' structure describing the compatible machine.
+
+2.13.2.5 `bfd_default_arch_struct'
+..................................
+
+*Description*
+The `bfd_default_arch_struct' is an item of `bfd_arch_info_type' which
+has been initialized to a fairly generic state. A BFD starts life by
+pointing to this structure, until the correct back end has determined
+the real architecture of the file.
+ extern const bfd_arch_info_type bfd_default_arch_struct;
+
+2.13.2.6 `bfd_set_arch_info'
+............................
+
+*Synopsis*
+ void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg);
+ *Description*
+Set the architecture info of ABFD to ARG.
+
+2.13.2.7 `bfd_default_set_arch_mach'
+....................................
+
+*Synopsis*
+ bfd_boolean bfd_default_set_arch_mach
+ (bfd *abfd, enum bfd_architecture arch, unsigned long mach);
+ *Description*
+Set the architecture and machine type in BFD ABFD to ARCH and MACH.
+Find the correct pointer to a structure and insert it into the
+`arch_info' pointer.
+
+2.13.2.8 `bfd_get_arch'
+.......................
+
+*Synopsis*
+ enum bfd_architecture bfd_get_arch (bfd *abfd);
+ *Description*
+Return the enumerated type which describes the BFD ABFD's architecture.
+
+2.13.2.9 `bfd_get_mach'
+.......................
+
+*Synopsis*
+ unsigned long bfd_get_mach (bfd *abfd);
+ *Description*
+Return the long type which describes the BFD ABFD's machine.
+
+2.13.2.10 `bfd_arch_bits_per_byte'
+..................................
+
+*Synopsis*
+ unsigned int bfd_arch_bits_per_byte (bfd *abfd);
+ *Description*
+Return the number of bits in one of the BFD ABFD's architecture's bytes.
+
+2.13.2.11 `bfd_arch_bits_per_address'
+.....................................
+
+*Synopsis*
+ unsigned int bfd_arch_bits_per_address (bfd *abfd);
+ *Description*
+Return the number of bits in one of the BFD ABFD's architecture's
+addresses.
+
+2.13.2.12 `bfd_default_compatible'
+..................................
+
+*Synopsis*
+ const bfd_arch_info_type *bfd_default_compatible
+ (const bfd_arch_info_type *a, const bfd_arch_info_type *b);
+ *Description*
+The default function for testing for compatibility.
+
+2.13.2.13 `bfd_default_scan'
+............................
+
+*Synopsis*
+ bfd_boolean bfd_default_scan
+ (const struct bfd_arch_info *info, const char *string);
+ *Description*
+The default function for working out whether this is an architecture
+hit and a machine hit.
+
+2.13.2.14 `bfd_get_arch_info'
+.............................
+
+*Synopsis*
+ const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd);
+ *Description*
+Return the architecture info struct in ABFD.
+
+2.13.2.15 `bfd_lookup_arch'
+...........................
+
+*Synopsis*
+ const bfd_arch_info_type *bfd_lookup_arch
+ (enum bfd_architecture arch, unsigned long machine);
+ *Description*
+Look for the architecture info structure which matches the arguments
+ARCH and MACHINE. A machine of 0 matches the machine/architecture
+structure which marks itself as the default.
+
+2.13.2.16 `bfd_printable_arch_mach'
+...................................
+
+*Synopsis*
+ const char *bfd_printable_arch_mach
+ (enum bfd_architecture arch, unsigned long machine);
+ *Description*
+Return a printable string representing the architecture and machine
+type.
+
+ This routine is depreciated.
+
+2.13.2.17 `bfd_octets_per_byte'
+...............................
+
+*Synopsis*
+ unsigned int bfd_octets_per_byte (bfd *abfd);
+ *Description*
+Return the number of octets (8-bit quantities) per target byte (minimum
+addressable unit). In most cases, this will be one, but some DSP
+targets have 16, 32, or even 48 bits per byte.
+
+2.13.2.18 `bfd_arch_mach_octets_per_byte'
+.........................................
+
+*Synopsis*
+ unsigned int bfd_arch_mach_octets_per_byte
+ (enum bfd_architecture arch, unsigned long machine);
+ *Description*
+See bfd_octets_per_byte.
+
+ This routine is provided for those cases where a bfd * is not
+available
+
+
+File: bfd.info, Node: Opening and Closing, Next: Internal, Prev: Architectures, Up: BFD front end
+
+2.14 Opening and closing BFDs
+=============================
+
+2.14.1 Functions for opening and closing
+----------------------------------------
+
+2.14.1.1 `bfd_fopen'
+....................
+
+*Synopsis*
+ bfd *bfd_fopen (const char *filename, const char *target,
+ const char *mode, int fd);
+ *Description*
+Open the file FILENAME with the target TARGET. Return a pointer to the
+created BFD. If FD is not -1, then `fdopen' is used to open the file;
+otherwise, `fopen' is used. MODE is passed directly to `fopen' or
+`fdopen'.
+
+ Calls `bfd_find_target', so TARGET is interpreted as by that
+function.
+
+ The new BFD is marked as cacheable iff FD is -1.
+
+ If `NULL' is returned then an error has occured. Possible errors
+are `bfd_error_no_memory', `bfd_error_invalid_target' or `system_call'
+error.
+
+2.14.1.2 `bfd_openr'
+....................
+
+*Synopsis*
+ bfd *bfd_openr (const char *filename, const char *target);
+ *Description*
+Open the file FILENAME (using `fopen') with the target TARGET. Return
+a pointer to the created BFD.
+
+ Calls `bfd_find_target', so TARGET is interpreted as by that
+function.
+
+ If `NULL' is returned then an error has occured. Possible errors
+are `bfd_error_no_memory', `bfd_error_invalid_target' or `system_call'
+error.
+
+2.14.1.3 `bfd_fdopenr'
+......................
+
+*Synopsis*
+ bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
+ *Description*
+`bfd_fdopenr' is to `bfd_fopenr' much like `fdopen' is to `fopen'. It
+opens a BFD on a file already described by the FD supplied.
+
+ When the file is later `bfd_close'd, the file descriptor will be
+closed. If the caller desires that this file descriptor be cached by
+BFD (opened as needed, closed as needed to free descriptors for other
+opens), with the supplied FD used as an initial file descriptor (but
+subject to closure at any time), call bfd_set_cacheable(bfd, 1) on the
+returned BFD. The default is to assume no caching; the file descriptor
+will remain open until `bfd_close', and will not be affected by BFD
+operations on other files.
+
+ Possible errors are `bfd_error_no_memory',
+`bfd_error_invalid_target' and `bfd_error_system_call'.
+
+2.14.1.4 `bfd_openstreamr'
+..........................
+
+*Synopsis*
+ bfd *bfd_openstreamr (const char *, const char *, void *);
+ *Description*
+Open a BFD for read access on an existing stdio stream. When the BFD
+is passed to `bfd_close', the stream will be closed.
+
+2.14.1.5 `bfd_openr_iovec'
+..........................
+
+*Synopsis*
+ bfd *bfd_openr_iovec (const char *filename, const char *target,
+ void *(*open) (struct bfd *nbfd,
+ void *open_closure),
+ void *open_closure,
+ file_ptr (*pread) (struct bfd *nbfd,
+ void *stream,
+ void *buf,
+ file_ptr nbytes,
+ file_ptr offset),
+ int (*close) (struct bfd *nbfd,
+ void *stream),
+ int (*stat) (struct bfd *abfd,
+ void *stream,
+ struct stat *sb));
+ *Description*
+Create and return a BFD backed by a read-only STREAM. The STREAM is
+created using OPEN, accessed using PREAD and destroyed using CLOSE.
+
+ Calls `bfd_find_target', so TARGET is interpreted as by that
+function.
+
+ Calls OPEN (which can call `bfd_zalloc' and `bfd_get_filename') to
+obtain the read-only stream backing the BFD. OPEN either succeeds
+returning the non-`NULL' STREAM, or fails returning `NULL' (setting
+`bfd_error').
+
+ Calls PREAD to request NBYTES of data from STREAM starting at OFFSET
+(e.g., via a call to `bfd_read'). PREAD either succeeds returning the
+number of bytes read (which can be less than NBYTES when end-of-file),
+or fails returning -1 (setting `bfd_error').
+
+ Calls CLOSE when the BFD is later closed using `bfd_close'. CLOSE
+either succeeds returning 0, or fails returning -1 (setting
+`bfd_error').
+
+ Calls STAT to fill in a stat structure for bfd_stat, bfd_get_size,
+and bfd_get_mtime calls. STAT returns 0 on success, or returns -1 on
+failure (setting `bfd_error').
+
+ If `bfd_openr_iovec' returns `NULL' then an error has occurred.
+Possible errors are `bfd_error_no_memory', `bfd_error_invalid_target'
+and `bfd_error_system_call'.
+
+2.14.1.6 `bfd_openw'
+....................
+
+*Synopsis*
+ bfd *bfd_openw (const char *filename, const char *target);
+ *Description*
+Create a BFD, associated with file FILENAME, using the file format
+TARGET, and return a pointer to it.
+
+ Possible errors are `bfd_error_system_call', `bfd_error_no_memory',
+`bfd_error_invalid_target'.
+
+2.14.1.7 `bfd_close'
+....................
+
+*Synopsis*
+ bfd_boolean bfd_close (bfd *abfd);
+ *Description*
+Close a BFD. If the BFD was open for writing, then pending operations
+are completed and the file written out and closed. If the created file
+is executable, then `chmod' is called to mark it as such.
+
+ All memory attached to the BFD is released.
+
+ The file descriptor associated with the BFD is closed (even if it
+was passed in to BFD by `bfd_fdopenr').
+
+ *Returns*
+`TRUE' is returned if all is ok, otherwise `FALSE'.
+
+2.14.1.8 `bfd_close_all_done'
+.............................
+
+*Synopsis*
+ bfd_boolean bfd_close_all_done (bfd *);
+ *Description*
+Close a BFD. Differs from `bfd_close' since it does not complete any
+pending operations. This routine would be used if the application had
+just used BFD for swapping and didn't want to use any of the writing
+code.
+
+ If the created file is executable, then `chmod' is called to mark it
+as such.
+
+ All memory attached to the BFD is released.
+
+ *Returns*
+`TRUE' is returned if all is ok, otherwise `FALSE'.
+
+2.14.1.9 `bfd_create'
+.....................
+
+*Synopsis*
+ bfd *bfd_create (const char *filename, bfd *templ);
+ *Description*
+Create a new BFD in the manner of `bfd_openw', but without opening a
+file. The new BFD takes the target from the target used by TEMPLATE.
+The format is always set to `bfd_object'.
+
+2.14.1.10 `bfd_make_writable'
+.............................
+
+*Synopsis*
+ bfd_boolean bfd_make_writable (bfd *abfd);
+ *Description*
+Takes a BFD as created by `bfd_create' and converts it into one like as
+returned by `bfd_openw'. It does this by converting the BFD to
+BFD_IN_MEMORY. It's assumed that you will call `bfd_make_readable' on
+this bfd later.
+
+ *Returns*
+`TRUE' is returned if all is ok, otherwise `FALSE'.
+
+2.14.1.11 `bfd_make_readable'
+.............................
+
+*Synopsis*
+ bfd_boolean bfd_make_readable (bfd *abfd);
+ *Description*
+Takes a BFD as created by `bfd_create' and `bfd_make_writable' and
+converts it into one like as returned by `bfd_openr'. It does this by
+writing the contents out to the memory buffer, then reversing the
+direction.
+
+ *Returns*
+`TRUE' is returned if all is ok, otherwise `FALSE'.
+
+2.14.1.12 `bfd_alloc'
+.....................
+
+*Synopsis*
+ void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
+ *Description*
+Allocate a block of WANTED bytes of memory attached to `abfd' and
+return a pointer to it.
+
+2.14.1.13 `bfd_alloc2'
+......................
+
+*Synopsis*
+ void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
+ *Description*
+Allocate a block of NMEMB elements of SIZE bytes each of memory
+attached to `abfd' and return a pointer to it.
+
+2.14.1.14 `bfd_zalloc'
+......................
+
+*Synopsis*
+ void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
+ *Description*
+Allocate a block of WANTED bytes of zeroed memory attached to `abfd'
+and return a pointer to it.
+
+2.14.1.15 `bfd_zalloc2'
+.......................
+
+*Synopsis*
+ void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
+ *Description*
+Allocate a block of NMEMB elements of SIZE bytes each of zeroed memory
+attached to `abfd' and return a pointer to it.
+
+2.14.1.16 `bfd_calc_gnu_debuglink_crc32'
+........................................
+
+*Synopsis*
+ unsigned long bfd_calc_gnu_debuglink_crc32
+ (unsigned long crc, const unsigned char *buf, bfd_size_type len);
+ *Description*
+Computes a CRC value as used in the .gnu_debuglink section. Advances
+the previously computed CRC value by computing and adding in the crc32
+for LEN bytes of BUF.
+
+ *Returns*
+Return the updated CRC32 value.
+
+2.14.1.17 `get_debug_link_info'
+...............................
+
+*Synopsis*
+ char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
+ *Description*
+fetch the filename and CRC32 value for any separate debuginfo
+associated with ABFD. Return NULL if no such info found, otherwise
+return filename and update CRC32_OUT.
+
+2.14.1.18 `separate_debug_file_exists'
+......................................
+
+*Synopsis*
+ bfd_boolean separate_debug_file_exists
+ (char *name, unsigned long crc32);
+ *Description*
+Checks to see if NAME is a file and if its contents match CRC32.
+
+2.14.1.19 `find_separate_debug_file'
+....................................
+
+*Synopsis*
+ char *find_separate_debug_file (bfd *abfd);
+ *Description*
+Searches ABFD for a reference to separate debugging information, scans
+various locations in the filesystem, including the file tree rooted at
+DEBUG_FILE_DIRECTORY, and returns a filename of such debugging
+information if the file is found and has matching CRC32. Returns NULL
+if no reference to debugging file exists, or file cannot be found.
+
+2.14.1.20 `bfd_follow_gnu_debuglink'
+....................................
+
+*Synopsis*
+ char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
+ *Description*
+Takes a BFD and searches it for a .gnu_debuglink section. If this
+section is found, it examines the section for the name and checksum of
+a '.debug' file containing auxiliary debugging information. It then
+searches the filesystem for this .debug file in some standard
+locations, including the directory tree rooted at DIR, and if found
+returns the full filename.
+
+ If DIR is NULL, it will search a default path configured into libbfd
+at build time. [XXX this feature is not currently implemented].
+
+ *Returns*
+`NULL' on any errors or failure to locate the .debug file, otherwise a
+pointer to a heap-allocated string containing the filename. The caller
+is responsible for freeing this string.
+
+2.14.1.21 `bfd_create_gnu_debuglink_section'
+............................................
+
+*Synopsis*
+ struct bfd_section *bfd_create_gnu_debuglink_section
+ (bfd *abfd, const char *filename);
+ *Description*
+Takes a BFD and adds a .gnu_debuglink section to it. The section is
+sized to be big enough to contain a link to the specified FILENAME.
+
+ *Returns*
+A pointer to the new section is returned if all is ok. Otherwise
+`NULL' is returned and bfd_error is set.
+
+2.14.1.22 `bfd_fill_in_gnu_debuglink_section'
+.............................................
+
+*Synopsis*
+ bfd_boolean bfd_fill_in_gnu_debuglink_section
+ (bfd *abfd, struct bfd_section *sect, const char *filename);
+ *Description*
+Takes a BFD and containing a .gnu_debuglink section SECT and fills in
+the contents of the section to contain a link to the specified
+FILENAME. The filename should be relative to the current directory.
+
+ *Returns*
+`TRUE' is returned if all is ok. Otherwise `FALSE' is returned and
+bfd_error is set.
+
+
+File: bfd.info, Node: Internal, Next: File Caching, Prev: Opening and Closing, Up: BFD front end
+
+2.15 Implementation details
+===========================
+
+2.15.1 Internal functions
+-------------------------
+
+*Description*
+These routines are used within BFD. They are not intended for export,
+but are documented here for completeness.
+
+2.15.1.1 `bfd_write_bigendian_4byte_int'
+........................................
+
+*Synopsis*
+ bfd_boolean bfd_write_bigendian_4byte_int (bfd *, unsigned int);
+ *Description*
+Write a 4 byte integer I to the output BFD ABFD, in big endian order
+regardless of what else is going on. This is useful in archives.
+
+2.15.1.2 `bfd_put_size'
+.......................
+
+2.15.1.3 `bfd_get_size'
+.......................
+
+*Description*
+These macros as used for reading and writing raw data in sections; each
+access (except for bytes) is vectored through the target format of the
+BFD and mangled accordingly. The mangling performs any necessary endian
+translations and removes alignment restrictions. Note that types
+accepted and returned by these macros are identical so they can be
+swapped around in macros--for example, `libaout.h' defines `GET_WORD'
+to either `bfd_get_32' or `bfd_get_64'.
+
+ In the put routines, VAL must be a `bfd_vma'. If we are on a system
+without prototypes, the caller is responsible for making sure that is
+true, with a cast if necessary. We don't cast them in the macro
+definitions because that would prevent `lint' or `gcc -Wall' from
+detecting sins such as passing a pointer. To detect calling these with
+less than a `bfd_vma', use `gcc -Wconversion' on a host with 64 bit
+`bfd_vma''s.
+
+ /* Byte swapping macros for user section data. */
+
+ #define bfd_put_8(abfd, val, ptr) \
+ ((void) (*((unsigned char *) (ptr)) = (val) & 0xff))
+ #define bfd_put_signed_8 \
+ bfd_put_8
+ #define bfd_get_8(abfd, ptr) \
+ (*(unsigned char *) (ptr) & 0xff)
+ #define bfd_get_signed_8(abfd, ptr) \
+ (((*(unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80)
+
+ #define bfd_put_16(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_putx16, ((val),(ptr)))
+ #define bfd_put_signed_16 \
+ bfd_put_16
+ #define bfd_get_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx16, (ptr))
+ #define bfd_get_signed_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx_signed_16, (ptr))
+
+ #define bfd_put_32(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_putx32, ((val),(ptr)))
+ #define bfd_put_signed_32 \
+ bfd_put_32
+ #define bfd_get_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx32, (ptr))
+ #define bfd_get_signed_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx_signed_32, (ptr))
+
+ #define bfd_put_64(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_putx64, ((val), (ptr)))
+ #define bfd_put_signed_64 \
+ bfd_put_64
+ #define bfd_get_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx64, (ptr))
+ #define bfd_get_signed_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx_signed_64, (ptr))
+
+ #define bfd_get(bits, abfd, ptr) \
+ ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr) \
+ : (bits) == 16 ? bfd_get_16 (abfd, ptr) \
+ : (bits) == 32 ? bfd_get_32 (abfd, ptr) \
+ : (bits) == 64 ? bfd_get_64 (abfd, ptr) \
+ : (abort (), (bfd_vma) - 1))
+
+ #define bfd_put(bits, abfd, val, ptr) \
+ ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \
+ : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \
+ : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \
+ : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \
+ : (abort (), (void) 0))
+
+2.15.1.4 `bfd_h_put_size'
+.........................
+
+*Description*
+These macros have the same function as their `bfd_get_x' brethren,
+except that they are used for removing information for the header
+records of object files. Believe it or not, some object files keep
+their header records in big endian order and their data in little
+endian order.
+
+ /* Byte swapping macros for file header data. */
+
+ #define bfd_h_put_8(abfd, val, ptr) \
+ bfd_put_8 (abfd, val, ptr)
+ #define bfd_h_put_signed_8(abfd, val, ptr) \
+ bfd_put_8 (abfd, val, ptr)
+ #define bfd_h_get_8(abfd, ptr) \
+ bfd_get_8 (abfd, ptr)
+ #define bfd_h_get_signed_8(abfd, ptr) \
+ bfd_get_signed_8 (abfd, ptr)
+
+ #define bfd_h_put_16(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_h_putx16, (val, ptr))
+ #define bfd_h_put_signed_16 \
+ bfd_h_put_16
+ #define bfd_h_get_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx16, (ptr))
+ #define bfd_h_get_signed_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr))
+
+ #define bfd_h_put_32(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_h_putx32, (val, ptr))
+ #define bfd_h_put_signed_32 \
+ bfd_h_put_32
+ #define bfd_h_get_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx32, (ptr))
+ #define bfd_h_get_signed_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr))
+
+ #define bfd_h_put_64(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_h_putx64, (val, ptr))
+ #define bfd_h_put_signed_64 \
+ bfd_h_put_64
+ #define bfd_h_get_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx64, (ptr))
+ #define bfd_h_get_signed_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr))
+
+ /* Aliases for the above, which should eventually go away. */
+
+ #define H_PUT_64 bfd_h_put_64
+ #define H_PUT_32 bfd_h_put_32
+ #define H_PUT_16 bfd_h_put_16
+ #define H_PUT_8 bfd_h_put_8
+ #define H_PUT_S64 bfd_h_put_signed_64
+ #define H_PUT_S32 bfd_h_put_signed_32
+ #define H_PUT_S16 bfd_h_put_signed_16
+ #define H_PUT_S8 bfd_h_put_signed_8
+ #define H_GET_64 bfd_h_get_64
+ #define H_GET_32 bfd_h_get_32
+ #define H_GET_16 bfd_h_get_16
+ #define H_GET_8 bfd_h_get_8
+ #define H_GET_S64 bfd_h_get_signed_64
+ #define H_GET_S32 bfd_h_get_signed_32
+ #define H_GET_S16 bfd_h_get_signed_16
+ #define H_GET_S8 bfd_h_get_signed_8
+
+2.15.1.5 `bfd_log2'
+...................
+
+*Synopsis*
+ unsigned int bfd_log2 (bfd_vma x);
+ *Description*
+Return the log base 2 of the value supplied, rounded up. E.g., an X of
+1025 returns 11. A X of 0 returns 0.
+
+
+File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end
+
+2.16 File caching
+=================
+
+The file caching mechanism is embedded within BFD and allows the
+application to open as many BFDs as it wants without regard to the
+underlying operating system's file descriptor limit (often as low as 20
+open files). The module in `cache.c' maintains a least recently used
+list of `BFD_CACHE_MAX_OPEN' files, and exports the name
+`bfd_cache_lookup', which runs around and makes sure that the required
+BFD is open. If not, then it chooses a file to close, closes it and
+opens the one wanted, returning its file handle.
+
+2.16.1 Caching functions
+------------------------
+
+2.16.1.1 `bfd_cache_init'
+.........................
+
+*Synopsis*
+ bfd_boolean bfd_cache_init (bfd *abfd);
+ *Description*
+Add a newly opened BFD to the cache.
+
+2.16.1.2 `bfd_cache_close'
+..........................
+
+*Synopsis*
+ bfd_boolean bfd_cache_close (bfd *abfd);
+ *Description*
+Remove the BFD ABFD from the cache. If the attached file is open, then
+close it too.
+
+ *Returns*
+`FALSE' is returned if closing the file fails, `TRUE' is returned if
+all is well.
+
+2.16.1.3 `bfd_cache_close_all'
+..............................
+
+*Synopsis*
+ bfd_boolean bfd_cache_close_all (void);
+ *Description*
+Remove all BFDs from the cache. If the attached file is open, then
+close it too.
+
+ *Returns*
+`FALSE' is returned if closing one of the file fails, `TRUE' is
+returned if all is well.
+
+2.16.1.4 `bfd_open_file'
+........................
+
+*Synopsis*
+ FILE* bfd_open_file (bfd *abfd);
+ *Description*
+Call the OS to open a file for ABFD. Return the `FILE *' (possibly
+`NULL') that results from this operation. Set up the BFD so that
+future accesses know the file is open. If the `FILE *' returned is
+`NULL', then it won't have been put in the cache, so it won't have to
+be removed from it.
+
+
+File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end
+
+2.17 Linker Functions
+=====================
+
+The linker uses three special entry points in the BFD target vector.
+It is not necessary to write special routines for these entry points
+when creating a new BFD back end, since generic versions are provided.
+However, writing them can speed up linking and make it use
+significantly less runtime memory.
+
+ The first routine creates a hash table used by the other routines.
+The second routine adds the symbols from an object file to the hash
+table. The third routine takes all the object files and links them
+together to create the output file. These routines are designed so
+that the linker proper does not need to know anything about the symbols
+in the object files that it is linking. The linker merely arranges the
+sections as directed by the linker script and lets BFD handle the
+details of symbols and relocs.
+
+ The second routine and third routines are passed a pointer to a
+`struct bfd_link_info' structure (defined in `bfdlink.h') which holds
+information relevant to the link, including the linker hash table
+(which was created by the first routine) and a set of callback
+functions to the linker proper.
+
+ The generic linker routines are in `linker.c', and use the header
+file `genlink.h'. As of this writing, the only back ends which have
+implemented versions of these routines are a.out (in `aoutx.h') and
+ECOFF (in `ecoff.c'). The a.out routines are used as examples
+throughout this section.
+
+* Menu:
+
+* Creating a Linker Hash Table::
+* Adding Symbols to the Hash Table::
+* Performing the Final Link::
+
+
+File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions
+
+2.17.1 Creating a linker hash table
+-----------------------------------
+
+The linker routines must create a hash table, which must be derived
+from `struct bfd_link_hash_table' described in `bfdlink.c'. *Note Hash
+Tables::, for information on how to create a derived hash table. This
+entry point is called using the target vector of the linker output file.
+
+ The `_bfd_link_hash_table_create' entry point must allocate and
+initialize an instance of the desired hash table. If the back end does
+not require any additional information to be stored with the entries in
+the hash table, the entry point may simply create a `struct
+bfd_link_hash_table'. Most likely, however, some additional
+information will be needed.
+
+ For example, with each entry in the hash table the a.out linker
+keeps the index the symbol has in the final output file (this index
+number is used so that when doing a relocatable link the symbol index
+used in the output file can be quickly filled in when copying over a
+reloc). The a.out linker code defines the required structures and
+functions for a hash table derived from `struct bfd_link_hash_table'.
+The a.out linker hash table is created by the function
+`NAME(aout,link_hash_table_create)'; it simply allocates space for the
+hash table, initializes it, and returns a pointer to it.
+
+ When writing the linker routines for a new back end, you will
+generally not know exactly which fields will be required until you have
+finished. You should simply create a new hash table which defines no
+additional fields, and then simply add fields as they become necessary.
+
+
+File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions
+
+2.17.2 Adding symbols to the hash table
+---------------------------------------
+
+The linker proper will call the `_bfd_link_add_symbols' entry point for
+each object file or archive which is to be linked (typically these are
+the files named on the command line, but some may also come from the
+linker script). The entry point is responsible for examining the file.
+For an object file, BFD must add any relevant symbol information to
+the hash table. For an archive, BFD must determine which elements of
+the archive should be used and adding them to the link.
+
+ The a.out version of this entry point is
+`NAME(aout,link_add_symbols)'.
+
+* Menu:
+
+* Differing file formats::
+* Adding symbols from an object file::
+* Adding symbols from an archive::
+
+
+File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table
+
+2.17.2.1 Differing file formats
+...............................
+
+Normally all the files involved in a link will be of the same format,
+but it is also possible to link together different format object files,
+and the back end must support that. The `_bfd_link_add_symbols' entry
+point is called via the target vector of the file to be added. This
+has an important consequence: the function may not assume that the hash
+table is the type created by the corresponding
+`_bfd_link_hash_table_create' vector. All the `_bfd_link_add_symbols'
+function can assume about the hash table is that it is derived from
+`struct bfd_link_hash_table'.
+
+ Sometimes the `_bfd_link_add_symbols' function must store some
+information in the hash table entry to be used by the `_bfd_final_link'
+function. In such a case the output bfd xvec must be checked to make
+sure that the hash table was created by an object file of the same
+format.
+
+ The `_bfd_final_link' routine must be prepared to handle a hash
+entry without any extra information added by the
+`_bfd_link_add_symbols' function. A hash entry without extra
+information will also occur when the linker script directs the linker
+to create a symbol. Note that, regardless of how a hash table entry is
+added, all the fields will be initialized to some sort of null value by
+the hash table entry initialization function.
+
+ See `ecoff_link_add_externals' for an example of how to check the
+output bfd before saving information (in this case, the ECOFF external
+symbol debugging information) in a hash table entry.
+
+
+File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table
+
+2.17.2.2 Adding symbols from an object file
+...........................................
+
+When the `_bfd_link_add_symbols' routine is passed an object file, it
+must add all externally visible symbols in that object file to the hash
+table. The actual work of adding the symbol to the hash table is
+normally handled by the function `_bfd_generic_link_add_one_symbol'.
+The `_bfd_link_add_symbols' routine is responsible for reading all the
+symbols from the object file and passing the correct information to
+`_bfd_generic_link_add_one_symbol'.
+
+ The `_bfd_link_add_symbols' routine should not use
+`bfd_canonicalize_symtab' to read the symbols. The point of providing
+this routine is to avoid the overhead of converting the symbols into
+generic `asymbol' structures.
+
+ `_bfd_generic_link_add_one_symbol' handles the details of combining
+common symbols, warning about multiple definitions, and so forth. It
+takes arguments which describe the symbol to add, notably symbol flags,
+a section, and an offset. The symbol flags include such things as
+`BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object
+file, or something like `bfd_und_section_ptr' for an undefined symbol
+or `bfd_com_section_ptr' for a common symbol.
+
+ If the `_bfd_final_link' routine is also going to need to read the
+symbol information, the `_bfd_link_add_symbols' routine should save it
+somewhere attached to the object file BFD. However, the information
+should only be saved if the `keep_memory' field of the `info' argument
+is TRUE, so that the `-no-keep-memory' linker switch is effective.
+
+ The a.out function which adds symbols from an object file is
+`aout_link_add_object_symbols', and most of the interesting work is in
+`aout_link_add_symbols'. The latter saves pointers to the hash tables
+entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol
+number, so that the `_bfd_final_link' routine does not have to call the
+hash table lookup routine to locate the entry.
+
+
+File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table
+
+2.17.2.3 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.
+
+
+File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions
+
+2.17.3 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 relocatable 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)'.
+
+* Menu:
+
+* Information provided by the linker::
+* Relocating the section contents::
+* Writing the symbol table::
+
+
+File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link
+
+2.17.3.1 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 `map_head.link_order' 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 relocatable object file.
+
+
+File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link
+
+2.17.3.2 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 relocatable 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'.
+
+
+File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link
+
+2.17.3.3 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)'.
+
+2.17.3.4 `bfd_link_split_section'
+.................................
+
+*Synopsis*
+ bfd_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))
+
+2.17.3.5 `bfd_section_already_linked'
+.....................................
+
+*Synopsis*
+ void bfd_section_already_linked (bfd *abfd, asection *sec,
+ struct bfd_link_info *info);
+ *Description*
+Check if SEC has been already linked during a reloceatable or final
+link.
+ #define bfd_section_already_linked(abfd, sec, info) \
+ BFD_SEND (abfd, _section_already_linked, (abfd, sec, info))
+
+2.17.3.6 `bfd_generic_define_common_symbol'
+...........................................
+
+*Synopsis*
+ bfd_boolean bfd_generic_define_common_symbol
+ (bfd *output_bfd, struct bfd_link_info *info,
+ struct bfd_link_hash_entry *h);
+ *Description*
+Convert common symbol H into a defined symbol. Return TRUE on success
+and FALSE on failure.
+ #define bfd_define_common_symbol(output_bfd, info, h) \
+ BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h))
+
+2.17.3.7 `bfd_find_version_for_sym '
+....................................
+
+*Synopsis*
+ struct bfd_elf_version_tree * bfd_find_version_for_sym
+ (struct bfd_elf_version_tree *verdefs,
+ const char *sym_name, bfd_boolean *hide);
+ *Description*
+Search an elf version script tree for symbol versioning info and export
+/ don't-export status for a given symbol. Return non-NULL on success
+and NULL on failure; also sets the output `hide' boolean parameter.
+
+
+File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end
+
+2.18 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'.
+
+* Menu:
+
+* Creating and Freeing a Hash Table::
+* Looking Up or Entering a String::
+* Traversing a Hash Table::
+* Deriving a New Hash Table Type::
+
+
+File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables
+
+2.18.1 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'. *Note 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.
+
+ Use `bfd_hash_set_default_size' to set the default size of hash
+table to use.
+
+
+File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables
+
+2.18.2 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.
+
+
+File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables
+
+2.18.3 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.
+
+
+File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables
+
+2.18.4 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.
+
+* Menu:
+
+* Define the Derived Structures::
+* Write the Derived Creation Routine::
+* Write Other Derived Routines::
+
+
+File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type
+
+2.18.4.1 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'.
+
+
+File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type
+
+2.18.4.2 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 (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 == NULL)
+ {
+ ret = bfd_hash_allocate (table, sizeof (* ret));
+ if (ret == 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'.
+
+
+File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type
+
+2.18.4.3 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.
+
+
+File: bfd.info, Node: BFD back ends, Next: GNU Free Documentation License, Prev: BFD front end, Up: Top
+
+3 BFD back ends
+***************
+
+* Menu:
+
+* What to Put Where::
+* aout :: a.out backends
+* coff :: coff backends
+* elf :: elf backends
+* mmo :: mmo backend
+
+
+File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends
+
+3.1 What to Put Where
+=====================
+
+All of BFD lives in one directory.
+
+
+File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends
+
+3.2 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.
+
+3.2.1 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.
+
+3.2.2 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).
+
+3.2.2.1 `aout_SIZE_swap_exec_header_in'
+.......................................
+
+*Synopsis*
+ void aout_SIZE_swap_exec_header_in,
+ (bfd *abfd,
+ struct external_exec *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.
+
+3.2.2.2 `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.
+
+3.2.2.3 `aout_SIZE_some_aout_object_p'
+......................................
+
+*Synopsis*
+ const bfd_target *aout_SIZE_some_aout_object_p
+ (bfd *abfd,
+ struct internal_exec *execp,
+ const bfd_target *(*callback_to_real_object_p) (bfd *));
+ *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.
+
+3.2.2.4 `aout_SIZE_mkobject'
+............................
+
+*Synopsis*
+ bfd_boolean aout_SIZE_mkobject, (bfd *abfd);
+ *Description*
+Initialize BFD ABFD for use with a.out files.
+
+3.2.2.5 `aout_SIZE_machine_type'
+................................
+
+*Synopsis*
+ enum machine_type aout_SIZE_machine_type
+ (enum bfd_architecture arch,
+ unsigned long machine,
+ bfd_boolean *unknown);
+ *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.
+
+3.2.2.6 `aout_SIZE_set_arch_mach'
+.................................
+
+*Synopsis*
+ bfd_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.
+
+3.2.2.7 `aout_SIZE_new_section_hook'
+....................................
+
+*Synopsis*
+ bfd_boolean aout_SIZE_new_section_hook,
+ (bfd *abfd,
+ asection *newsect);
+ *Description*
+Called by the BFD in response to a `bfd_make_section' request.
+
+
+File: bfd.info, Node: coff, Next: elf, Prev: aout, Up: BFD back ends
+
+3.3 coff backends
+=================
+
+BFD supports a number of different flavours of coff format. The major
+differences between formats are the sizes and alignments of fields in
+structures on disk, and the occasional extra field.
+
+ Coff in all its varieties is implemented with a few common files and
+a number of implementation specific files. For example, The 88k bcs
+coff format is implemented in the file `coff-m88k.c'. This file
+`#include's `coff/m88k.h' which defines the external structure of the
+coff format for the 88k, and `coff/internal.h' which defines the
+internal structure. `coff-m88k.c' also defines the relocations used by
+the 88k format *Note Relocations::.
+
+ The Intel i960 processor version of coff is implemented in
+`coff-i960.c'. This file has the same structure as `coff-m88k.c',
+except that it includes `coff/i960.h' rather than `coff-m88k.h'.
+
+3.3.1 Porting to a new version of coff
+--------------------------------------
+
+The recommended method is to select from the existing implementations
+the version of coff which is most like the one you want to use. For
+example, we'll say that i386 coff is the one you select, and that your
+coff flavour is called foo. Copy `i386coff.c' to `foocoff.c', copy
+`../include/coff/i386.h' to `../include/coff/foo.h', and add the lines
+to `targets.c' and `Makefile.in' so that your new back end is used.
+Alter the shapes of the structures in `../include/coff/foo.h' so that
+they match what you need. You will probably also have to add `#ifdef's
+to the code in `coff/internal.h' and `coffcode.h' if your version of
+coff is too wild.
+
+ You can verify that your new BFD backend works quite simply by
+building `objdump' from the `binutils' directory, and making sure that
+its version of what's going on and your host system's idea (assuming it
+has the pretty standard coff dump utility, usually called `att-dump' or
+just `dump') are the same. Then clean up your code, and send what
+you've done to Cygnus. Then your stuff will be in the next release, and
+you won't have to keep integrating it.
+
+3.3.2 How the coff backend works
+--------------------------------
+
+3.3.2.1 File layout
+...................
+
+The Coff backend is split into generic routines that are applicable to
+any Coff target and routines that are specific to a particular target.
+The target-specific routines are further split into ones which are
+basically the same for all Coff targets except that they use the
+external symbol format or use different values for certain constants.
+
+ The generic routines are in `coffgen.c'. These routines work for
+any Coff target. They use some hooks into the target specific code;
+the hooks are in a `bfd_coff_backend_data' structure, one of which
+exists for each target.
+
+ The essentially similar target-specific routines are in
+`coffcode.h'. This header file includes executable C code. The
+various Coff targets first include the appropriate Coff header file,
+make any special defines that are needed, and then include `coffcode.h'.
+
+ Some of the Coff targets then also have additional routines in the
+target source file itself.
+
+ For example, `coff-i960.c' includes `coff/internal.h' and
+`coff/i960.h'. It then defines a few constants, such as `I960', and
+includes `coffcode.h'. Since the i960 has complex relocation types,
+`coff-i960.c' also includes some code to manipulate the i960 relocs.
+This code is not in `coffcode.h' because it would not be used by any
+other target.
+
+3.3.2.2 Coff long section names
+...............................
+
+In the standard Coff object format, section names are limited to the
+eight bytes available in the `s_name' field of the `SCNHDR' section
+header structure. The format requires the field to be NUL-padded, but
+not necessarily NUL-terminated, so the longest section names permitted
+are a full eight characters.
+
+ The Microsoft PE variants of the Coff object file format add an
+extension to support the use of long section names. This extension is
+defined in section 4 of the Microsoft PE/COFF specification (rev 8.1).
+If a section name is too long to fit into the section header's `s_name'
+field, it is instead placed into the string table, and the `s_name'
+field is filled with a slash ("/") followed by the ASCII decimal
+representation of the offset of the full name relative to the string
+table base.
+
+ Note that this implies that the extension can only be used in object
+files, as executables do not contain a string table. The standard
+specifies that long section names from objects emitted into executable
+images are to be truncated.
+
+ However, as a GNU extension, BFD can generate executable images that
+contain a string table and long section names. This would appear to be
+technically valid, as the standard only says that Coff debugging
+information is deprecated, not forbidden, and in practice it works,
+although some tools that parse PE files expecting the MS standard
+format may become confused; `PEview' is one known example.
+
+ The functionality is supported in BFD by code implemented under the
+control of the macro `COFF_LONG_SECTION_NAMES'. If not defined, the
+format does not support long section names in any way. If defined, it
+is used to initialise a flag, `_bfd_coff_long_section_names', and a
+hook function pointer, `_bfd_coff_set_long_section_names', in the Coff
+backend data structure. The flag controls the generation of long
+section names in output BFDs at runtime; if it is false, as it will be
+by default when generating an executable image, long section names are
+truncated; if true, the long section names extension is employed. The
+hook points to a function that allows the value of the flag to be
+altered at runtime, on formats that support long section names at all;
+on other formats it points to a stub that returns an error indication.
+With input BFDs, the flag is set according to whether any long section
+names are detected while reading the section headers. For a completely
+new BFD, the flag is set to the default for the target format. This
+information can be used by a client of the BFD library when deciding
+what output format to generate, and means that a BFD that is opened for
+read and subsequently converted to a writeable BFD and modified
+in-place will retain whatever format it had on input.
+
+ If `COFF_LONG_SECTION_NAMES' is simply defined (blank), or is
+defined to the value "1", then long section names are enabled by
+default; if it is defined to the value zero, they are disabled by
+default (but still accepted in input BFDs). The header `coffcode.h'
+defines a macro, `COFF_DEFAULT_LONG_SECTION_NAMES', which is used in
+the backends to initialise the backend data structure fields
+appropriately; see the comments for further detail.
+
+3.3.2.3 Bit twiddling
+.....................
+
+Each flavour of coff supported in BFD has its own header file
+describing the external layout of the structures. There is also an
+internal description of the coff layout, in `coff/internal.h'. A major
+function of the coff backend is swapping the bytes and twiddling the
+bits to translate the external form of the structures into the normal
+internal form. This is all performed in the `bfd_swap'_thing_direction
+routines. Some elements are different sizes between different versions
+of coff; it is the duty of the coff version specific include file to
+override the definitions of various packing routines in `coffcode.h'.
+E.g., the size of line number entry in coff is sometimes 16 bits, and
+sometimes 32 bits. `#define'ing `PUT_LNSZ_LNNO' and `GET_LNSZ_LNNO'
+will select the correct one. No doubt, some day someone will find a
+version of coff which has a varying field size not catered to at the
+moment. To port BFD, that person will have to add more `#defines'.
+Three of the bit twiddling routines are exported to `gdb';
+`coff_swap_aux_in', `coff_swap_sym_in' and `coff_swap_lineno_in'. `GDB'
+reads the symbol table on its own, but uses BFD to fix things up. More
+of the bit twiddlers are exported for `gas'; `coff_swap_aux_out',
+`coff_swap_sym_out', `coff_swap_lineno_out', `coff_swap_reloc_out',
+`coff_swap_filehdr_out', `coff_swap_aouthdr_out',
+`coff_swap_scnhdr_out'. `Gas' currently keeps track of all the symbol
+table and reloc drudgery itself, thereby saving the internal BFD
+overhead, but uses BFD to swap things on the way out, making cross
+ports much safer. Doing so also allows BFD (and thus the linker) to
+use the same header files as `gas', which makes one avenue to disaster
+disappear.
+
+3.3.2.4 Symbol reading
+......................
+
+The simple canonical form for symbols used by BFD is not rich enough to
+keep all the information available in a coff symbol table. The back end
+gets around this problem by keeping the original symbol table around,
+"behind the scenes".
+
+ When a symbol table is requested (through a call to
+`bfd_canonicalize_symtab'), a request gets through to
+`coff_get_normalized_symtab'. This reads the symbol table from the coff
+file and swaps all the structures inside into the internal form. It
+also fixes up all the pointers in the table (represented in the file by
+offsets from the first symbol in the table) into physical pointers to
+elements in the new internal table. This involves some work since the
+meanings of fields change depending upon context: a field that is a
+pointer to another structure in the symbol table at one moment may be
+the size in bytes of a structure at the next. Another pass is made
+over the table. All symbols which mark file names (`C_FILE' symbols)
+are modified so that the internal string points to the value in the
+auxent (the real filename) rather than the normal text associated with
+the symbol (`".file"').
+
+ At this time the symbol names are moved around. Coff stores all
+symbols less than nine characters long physically within the symbol
+table; longer strings are kept at the end of the file in the string
+table. This pass moves all strings into memory and replaces them with
+pointers to the strings.
+
+ The symbol table is massaged once again, this time to create the
+canonical table used by the BFD application. Each symbol is inspected
+in turn, and a decision made (using the `sclass' field) about the
+various flags to set in the `asymbol'. *Note Symbols::. The generated
+canonical table shares strings with the hidden internal symbol table.
+
+ Any linenumbers are read from the coff file too, and attached to the
+symbols which own the functions the linenumbers belong to.
+
+3.3.2.5 Symbol writing
+......................
+
+Writing a symbol to a coff file which didn't come from a coff file will
+lose any debugging information. The `asymbol' structure remembers the
+BFD from which the symbol was taken, and on output the back end makes
+sure that the same destination target as source target is present.
+
+ When the symbols have come from a coff file then all the debugging
+information is preserved.
+
+ Symbol tables are provided for writing to the back end in a vector
+of pointers to pointers. This allows applications like the linker to
+accumulate and output large symbol tables without having to do too much
+byte copying.
+
+ This function runs through the provided symbol table and patches
+each symbol marked as a file place holder (`C_FILE') to point to the
+next file place holder in the list. It also marks each `offset' field
+in the list with the offset from the first symbol of the current symbol.
+
+ Another function of this procedure is to turn the canonical value
+form of BFD into the form used by coff. Internally, BFD expects symbol
+values to be offsets from a section base; so a symbol physically at
+0x120, but in a section starting at 0x100, would have the value 0x20.
+Coff expects symbols to contain their final value, so symbols have
+their values changed at this point to reflect their sum with their
+owning section. This transformation uses the `output_section' field of
+the `asymbol''s `asection' *Note Sections::.
+
+ * `coff_mangle_symbols'
+ This routine runs though the provided symbol table and uses the
+offsets generated by the previous pass and the pointers generated when
+the symbol table was read in to create the structured hierarchy
+required by coff. It changes each pointer to a symbol into the index
+into the symbol table of the asymbol.
+
+ * `coff_write_symbols'
+ This routine runs through the symbol table and patches up the
+symbols from their internal form into the coff way, calls the bit
+twiddlers, and writes out the table to the file.
+
+3.3.2.6 `coff_symbol_type'
+..........................
+
+*Description*
+The hidden information for an `asymbol' is described in a
+`combined_entry_type':
+
+
+ typedef struct coff_ptr_struct
+ {
+ /* Remembers the offset from the first symbol in the file for
+ this symbol. Generated by coff_renumber_symbols. */
+ unsigned int offset;
+
+ /* Should the value of this symbol be renumbered. Used for
+ XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */
+ unsigned int fix_value : 1;
+
+ /* Should the tag field of this symbol be renumbered.
+ Created by coff_pointerize_aux. */
+ unsigned int fix_tag : 1;
+
+ /* Should the endidx field of this symbol be renumbered.
+ Created by coff_pointerize_aux. */
+ unsigned int fix_end : 1;
+
+ /* Should the x_csect.x_scnlen field be renumbered.
+ Created by coff_pointerize_aux. */
+ unsigned int fix_scnlen : 1;
+
+ /* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the
+ index into the line number entries. Set by coff_slurp_symbol_table. */
+ unsigned int fix_line : 1;
+
+ /* The container for the symbol structure as read and translated
+ from the file. */
+ union
+ {
+ union internal_auxent auxent;
+ struct internal_syment syment;
+ } u;
+ } combined_entry_type;
+
+
+ /* Each canonical asymbol really looks like this: */
+
+ typedef struct coff_symbol_struct
+ {
+ /* The actual symbol which the rest of BFD works with */
+ asymbol symbol;
+
+ /* A pointer to the hidden information for this symbol */
+ combined_entry_type *native;
+
+ /* A pointer to the linenumber information for this symbol */
+ struct lineno_cache_entry *lineno;
+
+ /* Have the line numbers been relocated yet ? */
+ bfd_boolean done_lineno;
+ } coff_symbol_type;
+
+3.3.2.7 `bfd_coff_backend_data'
+...............................
+
+ /* COFF symbol classifications. */
+
+ enum coff_symbol_classification
+ {
+ /* Global symbol. */
+ COFF_SYMBOL_GLOBAL,
+ /* Common symbol. */
+ COFF_SYMBOL_COMMON,
+ /* Undefined symbol. */
+ COFF_SYMBOL_UNDEFINED,
+ /* Local symbol. */
+ COFF_SYMBOL_LOCAL,
+ /* PE section symbol. */
+ COFF_SYMBOL_PE_SECTION
+ };
+Special entry points for gdb to swap in coff symbol table parts:
+ typedef struct
+ {
+ void (*_bfd_coff_swap_aux_in)
+ (bfd *, void *, int, int, int, int, void *);
+
+ void (*_bfd_coff_swap_sym_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_lineno_in)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_aux_out)
+ (bfd *, void *, int, int, int, int, void *);
+
+ unsigned int (*_bfd_coff_swap_sym_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_lineno_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_reloc_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_filehdr_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_aouthdr_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_scnhdr_out)
+ (bfd *, void *, void *);
+
+ unsigned int _bfd_filhsz;
+ unsigned int _bfd_aoutsz;
+ unsigned int _bfd_scnhsz;
+ unsigned int _bfd_symesz;
+ unsigned int _bfd_auxesz;
+ unsigned int _bfd_relsz;
+ unsigned int _bfd_linesz;
+ unsigned int _bfd_filnmlen;
+ bfd_boolean _bfd_coff_long_filenames;
+
+ bfd_boolean _bfd_coff_long_section_names;
+ bfd_boolean (*_bfd_coff_set_long_section_names)
+ (bfd *, int);
+
+ unsigned int _bfd_coff_default_section_alignment_power;
+ bfd_boolean _bfd_coff_force_symnames_in_strings;
+ unsigned int _bfd_coff_debug_string_prefix_length;
+
+ void (*_bfd_coff_swap_filehdr_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_aouthdr_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_scnhdr_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_reloc_in)
+ (bfd *abfd, void *, void *);
+
+ bfd_boolean (*_bfd_coff_bad_format_hook)
+ (bfd *, void *);
+
+ bfd_boolean (*_bfd_coff_set_arch_mach_hook)
+ (bfd *, void *);
+
+ void * (*_bfd_coff_mkobject_hook)
+ (bfd *, void *, void *);
+
+ bfd_boolean (*_bfd_styp_to_sec_flags_hook)
+ (bfd *, void *, const char *, asection *, flagword *);
+
+ void (*_bfd_set_alignment_hook)
+ (bfd *, asection *, void *);
+
+ bfd_boolean (*_bfd_coff_slurp_symbol_table)
+ (bfd *);
+
+ bfd_boolean (*_bfd_coff_symname_in_debug)
+ (bfd *, struct internal_syment *);
+
+ bfd_boolean (*_bfd_coff_pointerize_aux_hook)
+ (bfd *, combined_entry_type *, combined_entry_type *,
+ unsigned int, combined_entry_type *);
+
+ bfd_boolean (*_bfd_coff_print_aux)
+ (bfd *, FILE *, combined_entry_type *, combined_entry_type *,
+ combined_entry_type *, unsigned int);
+
+ void (*_bfd_coff_reloc16_extra_cases)
+ (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *,
+ bfd_byte *, unsigned int *, unsigned int *);
+
+ int (*_bfd_coff_reloc16_estimate)
+ (bfd *, asection *, arelent *, unsigned int,
+ struct bfd_link_info *);
+
+ enum coff_symbol_classification (*_bfd_coff_classify_symbol)
+ (bfd *, struct internal_syment *);
+
+ bfd_boolean (*_bfd_coff_compute_section_file_positions)
+ (bfd *);
+
+ bfd_boolean (*_bfd_coff_start_final_link)
+ (bfd *, struct bfd_link_info *);
+
+ bfd_boolean (*_bfd_coff_relocate_section)
+ (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *,
+ struct internal_reloc *, struct internal_syment *, asection **);
+
+ reloc_howto_type *(*_bfd_coff_rtype_to_howto)
+ (bfd *, asection *, struct internal_reloc *,
+ struct coff_link_hash_entry *, struct internal_syment *,
+ bfd_vma *);
+
+ bfd_boolean (*_bfd_coff_adjust_symndx)
+ (bfd *, struct bfd_link_info *, bfd *, asection *,
+ struct internal_reloc *, bfd_boolean *);
+
+ bfd_boolean (*_bfd_coff_link_add_one_symbol)
+ (struct bfd_link_info *, bfd *, const char *, flagword,
+ asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean,
+ struct bfd_link_hash_entry **);
+
+ bfd_boolean (*_bfd_coff_link_output_has_begun)
+ (bfd *, struct coff_final_link_info *);
+
+ bfd_boolean (*_bfd_coff_final_link_postscript)
+ (bfd *, struct coff_final_link_info *);
+
+ bfd_boolean (*_bfd_coff_print_pdata)
+ (bfd *, void *);
+
+ } bfd_coff_backend_data;
+
+ #define coff_backend_info(abfd) \
+ ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
+
+ #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
+ ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
+
+ #define bfd_coff_swap_sym_in(a,e,i) \
+ ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
+
+ #define bfd_coff_swap_lineno_in(a,e,i) \
+ ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
+
+ #define bfd_coff_swap_reloc_out(abfd, i, o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
+
+ #define bfd_coff_swap_lineno_out(abfd, i, o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
+
+ #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
+ ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
+
+ #define bfd_coff_swap_sym_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
+
+ #define bfd_coff_swap_scnhdr_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
+
+ #define bfd_coff_swap_filehdr_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
+
+ #define bfd_coff_swap_aouthdr_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
+
+ #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
+ #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
+ #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
+ #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
+ #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
+ #define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz)
+ #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
+ #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
+ #define bfd_coff_long_filenames(abfd) \
+ (coff_backend_info (abfd)->_bfd_coff_long_filenames)
+ #define bfd_coff_long_section_names(abfd) \
+ (coff_backend_info (abfd)->_bfd_coff_long_section_names)
+ #define bfd_coff_set_long_section_names(abfd, enable) \
+ ((coff_backend_info (abfd)->_bfd_coff_set_long_section_names) (abfd, enable))
+ #define bfd_coff_default_section_alignment_power(abfd) \
+ (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
+ #define bfd_coff_swap_filehdr_in(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
+
+ #define bfd_coff_swap_aouthdr_in(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
+
+ #define bfd_coff_swap_scnhdr_in(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
+
+ #define bfd_coff_swap_reloc_in(abfd, i, o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
+
+ #define bfd_coff_bad_format_hook(abfd, filehdr) \
+ ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
+
+ #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
+ ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
+ #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
+ ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\
+ (abfd, filehdr, aouthdr))
+
+ #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\
+ ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
+ (abfd, scnhdr, name, section, flags_ptr))
+
+ #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
+ ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
+
+ #define bfd_coff_slurp_symbol_table(abfd)\
+ ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
+
+ #define bfd_coff_symname_in_debug(abfd, sym)\
+ ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
+
+ #define bfd_coff_force_symnames_in_strings(abfd)\
+ (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings)
+
+ #define bfd_coff_debug_string_prefix_length(abfd)\
+ (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length)
+
+ #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
+ ((coff_backend_info (abfd)->_bfd_coff_print_aux)\
+ (abfd, file, base, symbol, aux, indaux))
+
+ #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\
+ reloc, data, src_ptr, dst_ptr)\
+ ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
+ (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
+
+ #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
+ ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
+ (abfd, section, reloc, shrink, link_info))
+
+ #define bfd_coff_classify_symbol(abfd, sym)\
+ ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
+ (abfd, sym))
+
+ #define bfd_coff_compute_section_file_positions(abfd)\
+ ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
+ (abfd))
+
+ #define bfd_coff_start_final_link(obfd, info)\
+ ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
+ (obfd, info))
+ #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
+ ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
+ (obfd, info, ibfd, o, con, rel, isyms, secs))
+ #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
+ ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
+ (abfd, sec, rel, h, sym, addendp))
+ #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
+ ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
+ (obfd, info, ibfd, sec, rel, adjustedp))
+ #define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\
+ value, string, cp, coll, hashp)\
+ ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
+ (info, abfd, name, flags, section, value, string, cp, coll, hashp))
+
+ #define bfd_coff_link_output_has_begun(a,p) \
+ ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a, p))
+ #define bfd_coff_final_link_postscript(a,p) \
+ ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a, p))
+
+ #define bfd_coff_have_print_pdata(a) \
+ (coff_backend_info (a)->_bfd_coff_print_pdata)
+ #define bfd_coff_print_pdata(a,p) \
+ ((coff_backend_info (a)->_bfd_coff_print_pdata) (a, p))
+
+ /* Macro: Returns true if the bfd is a PE executable as opposed to a
+ PE object file. */
+ #define bfd_pei_p(abfd) \
+ (CONST_STRNEQ ((abfd)->xvec->name, "pei-"))
+
+3.3.2.8 Writing relocations
+...........................
+
+To write relocations, the back end steps though the canonical
+relocation table and create an `internal_reloc'. The symbol index to
+use is removed from the `offset' field in the symbol table supplied.
+The address comes directly from the sum of the section base address and
+the relocation offset; the type is dug directly from the howto field.
+Then the `internal_reloc' is swapped into the shape of an
+`external_reloc' and written out to disk.
+
+3.3.2.9 Reading linenumbers
+...........................
+
+Creating the linenumber table is done by reading in the entire coff
+linenumber table, and creating another table for internal use.
+
+ A coff linenumber table is structured so that each function is
+marked as having a line number of 0. Each line within the function is
+an offset from the first line in the function. The base of the line
+number information for the table is stored in the symbol associated
+with the function.
+
+ Note: The PE format uses line number 0 for a flag indicating a new
+source file.
+
+ The information is copied from the external to the internal table,
+and each symbol which marks a function is marked by pointing its...
+
+ How does this work ?
+
+3.3.2.10 Reading relocations
+............................
+
+Coff relocations are easily transformed into the internal BFD form
+(`arelent').
+
+ Reading a coff relocation table is done in the following stages:
+
+ * Read the entire coff relocation table into memory.
+
+ * Process each relocation in turn; first swap it from the external
+ to the internal form.
+
+ * Turn the symbol referenced in the relocation's symbol index into a
+ pointer into the canonical symbol table. This table is the same
+ as the one returned by a call to `bfd_canonicalize_symtab'. The
+ back end will call that routine and save the result if a
+ canonicalization hasn't been done.
+
+ * The reloc index is turned into a pointer to a howto structure, in
+ a back end specific way. For instance, the 386 and 960 use the
+ `r_type' to directly produce an index into a howto table vector;
+ the 88k subtracts a number from the `r_type' field and creates an
+ addend field.
+
+
+File: bfd.info, Node: elf, Next: mmo, Prev: coff, Up: BFD back ends
+
+3.4 ELF backends
+================
+
+BFD support for ELF formats is being worked on. Currently, the best
+supported back ends are for sparc and i386 (running svr4 or Solaris 2).
+
+ Documentation of the internals of the support code still needs to be
+written. The code is changing quickly enough that we haven't bothered
+yet.
+
+
+File: bfd.info, Node: mmo, Prev: elf, Up: BFD back ends
+
+3.5 mmo backend
+===============
+
+The mmo object format is used exclusively together with Professor
+Donald E. Knuth's educational 64-bit processor MMIX. The simulator
+`mmix' which is available at
+`http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz'
+understands this format. That package also includes a combined
+assembler and linker called `mmixal'. The mmo format has no advantages
+feature-wise compared to e.g. ELF. It is a simple non-relocatable
+object format with no support for archives or debugging information,
+except for symbol value information and line numbers (which is not yet
+implemented in BFD). See
+`http://www-cs-faculty.stanford.edu/~knuth/mmix.html' for more
+information about MMIX. The ELF format is used for intermediate object
+files in the BFD implementation.
+
+* Menu:
+
+* File layout::
+* Symbol-table::
+* mmo section mapping::
+
+
+File: bfd.info, Node: File layout, Next: Symbol-table, Prev: mmo, Up: mmo
+
+3.5.1 File layout
+-----------------
+
+The mmo file contents is not partitioned into named sections as with
+e.g. ELF. Memory areas is formed by specifying the location of the
+data that follows. Only the memory area `0x0000...00' to `0x01ff...ff'
+is executable, so it is used for code (and constants) and the area
+`0x2000...00' to `0x20ff...ff' is used for writable data. *Note mmo
+section mapping::.
+
+ There is provision for specifying "special data" of 65536 different
+types. We use type 80 (decimal), arbitrarily chosen the same as the
+ELF `e_machine' number for MMIX, filling it with section information
+normally found in ELF objects. *Note mmo section mapping::.
+
+ Contents is entered as 32-bit words, xor:ed over previous contents,
+always zero-initialized. A word that starts with the byte `0x98' forms
+a command called a `lopcode', where the next byte distinguished between
+the thirteen lopcodes. The two remaining bytes, called the `Y' and `Z'
+fields, or the `YZ' field (a 16-bit big-endian number), are used for
+various purposes different for each lopcode. As documented in
+`http://www-cs-faculty.stanford.edu/~knuth/mmixal-intro.ps.gz', the
+lopcodes are:
+
+`lop_quote'
+ 0x98000001. The next word is contents, regardless of whether it
+ starts with 0x98 or not.
+
+`lop_loc'
+ 0x9801YYZZ, where `Z' is 1 or 2. This is a location directive,
+ setting the location for the next data to the next 32-bit word
+ (for Z = 1) or 64-bit word (for Z = 2), plus Y * 2^56. Normally
+ `Y' is 0 for the text segment and 2 for the data segment.
+
+`lop_skip'
+ 0x9802YYZZ. Increase the current location by `YZ' bytes.
+
+`lop_fixo'
+ 0x9803YYZZ, where `Z' is 1 or 2. Store the current location as 64
+ bits into the location pointed to by the next 32-bit (Z = 1) or
+ 64-bit (Z = 2) word, plus Y * 2^56.
+
+`lop_fixr'
+ 0x9804YYZZ. `YZ' is stored into the current location plus 2 - 4 *
+ YZ.
+
+`lop_fixrx'
+ 0x980500ZZ. `Z' is 16 or 24. A value `L' derived from the
+ following 32-bit word are used in a manner similar to `YZ' in
+ lop_fixr: it is xor:ed into the current location minus 4 * L. The
+ first byte of the word is 0 or 1. If it is 1, then L = (LOWEST 24
+ BITS OF WORD) - 2^Z, if 0, then L = (LOWEST 24 BITS OF WORD).
+
+`lop_file'
+ 0x9806YYZZ. `Y' is the file number, `Z' is count of 32-bit words.
+ Set the file number to `Y' and the line counter to 0. The next Z
+ * 4 bytes contain the file name, padded with zeros if the count is
+ not a multiple of four. The same `Y' may occur multiple times,
+ but `Z' must be 0 for all but the first occurrence.
+
+`lop_line'
+ 0x9807YYZZ. `YZ' is the line number. Together with lop_file, it
+ forms the source location for the next 32-bit word. Note that for
+ each non-lopcode 32-bit word, line numbers are assumed incremented
+ by one.
+
+`lop_spec'
+ 0x9808YYZZ. `YZ' is the type number. Data until the next lopcode
+ other than lop_quote forms special data of type `YZ'. *Note mmo
+ section mapping::.
+
+ Other types than 80, (or type 80 with a content that does not
+ parse) is stored in sections named `.MMIX.spec_data.N' where N is
+ the `YZ'-type. The flags for such a sections say not to allocate
+ or load the data. The vma is 0. Contents of multiple occurrences
+ of special data N is concatenated to the data of the previous
+ lop_spec Ns. The location in data or code at which the lop_spec
+ occurred is lost.
+
+`lop_pre'
+ 0x980901ZZ. The first lopcode in a file. The `Z' field forms the
+ length of header information in 32-bit words, where the first word
+ tells the time in seconds since `00:00:00 GMT Jan 1 1970'.
+
+`lop_post'
+ 0x980a00ZZ. Z > 32. This lopcode follows after all
+ content-generating lopcodes in a program. The `Z' field denotes
+ the value of `rG' at the beginning of the program. The following
+ 256 - Z big-endian 64-bit words are loaded into global registers
+ `$G' ... `$255'.
+
+`lop_stab'
+ 0x980b0000. The next-to-last lopcode in a program. Must follow
+ immediately after the lop_post lopcode and its data. After this
+ lopcode follows all symbols in a compressed format (*note
+ Symbol-table::).
+
+`lop_end'
+ 0x980cYYZZ. The last lopcode in a program. It must follow the
+ lop_stab lopcode and its data. The `YZ' field contains the number
+ of 32-bit words of symbol table information after the preceding
+ lop_stab lopcode.
+
+ Note that the lopcode "fixups"; `lop_fixr', `lop_fixrx' and
+`lop_fixo' are not generated by BFD, but are handled. They are
+generated by `mmixal'.
+
+ This trivial one-label, one-instruction file:
+
+ :Main TRAP 1,2,3
+
+ can be represented this way in mmo:
+
+ 0x98090101 - lop_pre, one 32-bit word with timestamp.
+ <timestamp>
+ 0x98010002 - lop_loc, text segment, using a 64-bit address.
+ Note that mmixal does not emit this for the file above.
+ 0x00000000 - Address, high 32 bits.
+ 0x00000000 - Address, low 32 bits.
+ 0x98060002 - lop_file, 2 32-bit words for file-name.
+ 0x74657374 - "test"
+ 0x2e730000 - ".s\0\0"
+ 0x98070001 - lop_line, line 1.
+ 0x00010203 - TRAP 1,2,3
+ 0x980a00ff - lop_post, setting $255 to 0.
+ 0x00000000
+ 0x00000000
+ 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
+ 0x203a4040 *Note Symbol-table::.
+ 0x10404020
+ 0x4d206120
+ 0x69016e00
+ 0x81000000
+ 0x980c0005 - lop_end; symbol table contained five 32-bit words.
+
+
+File: bfd.info, Node: Symbol-table, Next: mmo section mapping, Prev: File layout, Up: mmo
+
+3.5.2 Symbol table format
+-------------------------
+
+From mmixal.w (or really, the generated mmixal.tex) in
+`http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz'):
+"Symbols are stored and retrieved by means of a `ternary search trie',
+following ideas of Bentley and Sedgewick. (See ACM-SIAM Symp. on
+Discrete Algorithms `8' (1997), 360-369; R.Sedgewick, `Algorithms in C'
+(Reading, Mass. Addison-Wesley, 1998), `15.4'.) Each trie node stores
+a character, and there are branches to subtries for the cases where a
+given character is less than, equal to, or greater than the character
+in the trie. There also is a pointer to a symbol table entry if a
+symbol ends at the current node."
+
+ So it's a tree encoded as a stream of bytes. The stream of bytes
+acts on a single virtual global symbol, adding and removing characters
+and signalling complete symbol points. Here, we read the stream and
+create symbols at the completion points.
+
+ First, there's a control byte `m'. If any of the listed bits in `m'
+is nonzero, we execute what stands at the right, in the listed order:
+
+ (MMO3_LEFT)
+ 0x40 - Traverse left trie.
+ (Read a new command byte and recurse.)
+
+ (MMO3_SYMBITS)
+ 0x2f - Read the next byte as a character and store it in the
+ current character position; increment character position.
+ Test the bits of `m':
+
+ (MMO3_WCHAR)
+ 0x80 - The character is 16-bit (so read another byte,
+ merge into current character.
+
+ (MMO3_TYPEBITS)
+ 0xf - We have a complete symbol; parse the type, value
+ and serial number and do what should be done
+ with a symbol. The type and length information
+ is in j = (m & 0xf).
+
+ (MMO3_REGQUAL_BITS)
+ j == 0xf: A register variable. The following
+ byte tells which register.
+ j <= 8: An absolute symbol. Read j bytes as the
+ big-endian number the symbol equals.
+ A j = 2 with two zero bytes denotes an
+ unknown symbol.
+ j > 8: As with j <= 8, but add (0x20 << 56)
+ to the value in the following j - 8
+ bytes.
+
+ Then comes the serial number, as a variant of
+ uleb128, but better named ubeb128:
+ Read bytes and shift the previous value left 7
+ (multiply by 128). Add in the new byte, repeat
+ until a byte has bit 7 set. The serial number
+ is the computed value minus 128.
+
+ (MMO3_MIDDLE)
+ 0x20 - Traverse middle trie. (Read a new command byte
+ and recurse.) Decrement character position.
+
+ (MMO3_RIGHT)
+ 0x10 - Traverse right trie. (Read a new command byte and
+ recurse.)
+
+ Let's look again at the `lop_stab' for the trivial file (*note File
+layout::).
+
+ 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
+ 0x203a4040
+ 0x10404020
+ 0x4d206120
+ 0x69016e00
+ 0x81000000
+
+ This forms the trivial trie (note that the path between ":" and "M"
+is redundant):
+
+ 203a ":"
+ 40 /
+ 40 /
+ 10 \
+ 40 /
+ 40 /
+ 204d "M"
+ 2061 "a"
+ 2069 "i"
+ 016e "n" is the last character in a full symbol, and
+ with a value represented in one byte.
+ 00 The value is 0.
+ 81 The serial number is 1.
+
+
+File: bfd.info, Node: mmo section mapping, Prev: Symbol-table, Up: mmo
+
+3.5.3 mmo section mapping
+-------------------------
+
+The implementation in BFD uses special data type 80 (decimal) to
+encapsulate and describe named sections, containing e.g. debug
+information. If needed, any datum in the encapsulation will be quoted
+using lop_quote. First comes a 32-bit word holding the number of
+32-bit words containing the zero-terminated zero-padded segment name.
+After the name there's a 32-bit word holding flags describing the
+section type. Then comes a 64-bit big-endian word with the section
+length (in bytes), then another with the section start address.
+Depending on the type of section, the contents might follow,
+zero-padded to 32-bit boundary. For a loadable section (such as data
+or code), the contents might follow at some later point, not
+necessarily immediately, as a lop_loc with the same start address as in
+the section description, followed by the contents. This in effect
+forms a descriptor that must be emitted before the actual contents.
+Sections described this way must not overlap.
+
+ For areas that don't have such descriptors, synthetic sections are
+formed by BFD. Consecutive contents in the two memory areas
+`0x0000...00' to `0x01ff...ff' and `0x2000...00' to `0x20ff...ff' are
+entered in sections named `.text' and `.data' respectively. If an area
+is not otherwise described, but would together with a neighboring lower
+area be less than `0x40000000' bytes long, it is joined with the lower
+area and the gap is zero-filled. For other cases, a new section is
+formed, named `.MMIX.sec.N'. Here, N is a number, a running count
+through the mmo file, starting at 0.
+
+ A loadable section specified as:
+
+ .section secname,"ax"
+ TETRA 1,2,3,4,-1,-2009
+ BYTE 80
+
+ and linked to address `0x4', is represented by the sequence:
+
+ 0x98080050 - lop_spec 80
+ 0x00000002 - two 32-bit words for the section name
+ 0x7365636e - "secn"
+ 0x616d6500 - "ame\0"
+ 0x00000033 - flags CODE, READONLY, LOAD, ALLOC
+ 0x00000000 - high 32 bits of section length
+ 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits
+ 0x00000000 - high 32 bits of section address
+ 0x00000004 - section address is 4
+ 0x98010002 - 64 bits with address of following data
+ 0x00000000 - high 32 bits of address
+ 0x00000004 - low 32 bits: data starts at address 4
+ 0x00000001 - 1
+ 0x00000002 - 2
+ 0x00000003 - 3
+ 0x00000004 - 4
+ 0xffffffff - -1
+ 0xfffff827 - -2009
+ 0x50000000 - 80 as a byte, padded with zeros.
+
+ Note that the lop_spec wrapping does not include the section
+contents. Compare this to a non-loaded section specified as:
+
+ .section thirdsec
+ TETRA 200001,100002
+ BYTE 38,40
+
+ This, when linked to address `0x200000000000001c', is represented by:
+
+ 0x98080050 - lop_spec 80
+ 0x00000002 - two 32-bit words for the section name
+ 0x7365636e - "thir"
+ 0x616d6500 - "dsec"
+ 0x00000010 - flag READONLY
+ 0x00000000 - high 32 bits of section length
+ 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits
+ 0x20000000 - high 32 bits of address
+ 0x0000001c - low 32 bits of address 0x200000000000001c
+ 0x00030d41 - 200001
+ 0x000186a2 - 100002
+ 0x26280000 - 38, 40 as bytes, padded with zeros
+
+ For the latter example, the section contents must not be loaded in
+memory, and is therefore specified as part of the special data. The
+address is usually unimportant but might provide information for e.g.
+the DWARF 2 debugging format.
+
+
+File: bfd.info, Node: GNU Free Documentation License, Next: BFD Index, Prev: BFD back ends, Up: Top
+
+ Version 1.3, 3 November 2008
+
+ Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+ `http://fsf.org/'
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the
+ author and publisher a way to get credit for their work, while not
+ being considered responsible for modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book.
+ We recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it
+ can be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ "Document", below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as "you". You
+ accept the license if you copy, modify or distribute the work in a
+ way requiring permission under copyright law.
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in
+ the notice that says that the Document is released under this
+ License. If a section does not fit the above definition of
+ Secondary then it is not allowed to be designated as Invariant.
+ The Document may contain zero Invariant Sections. If the Document
+ does not identify any Invariant Sections then there are none.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images
+ composed of pixels) generic paint programs or (for drawings) some
+ widely available drawing editor, and that is suitable for input to
+ text formatters or for automatic translation to a variety of
+ formats suitable for input to text formatters. A copy made in an
+ otherwise Transparent file format whose markup, or absence of
+ markup, has been arranged to thwart or discourage subsequent
+ modification by readers is not Transparent. An image format is
+ not Transparent if used for any substantial amount of text. A
+ copy that is not "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML, PostScript or PDF designed for
+ human modification. Examples of transparent image formats include
+ PNG, XCF and JPG. Opaque formats include proprietary formats that
+ can be read and edited only by proprietary word processors, SGML or
+ XML for which the DTD and/or processing tools are not generally
+ available, and the machine-generated HTML, PostScript or PDF
+ produced by some word processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ The "publisher" means any person or entity that distributes copies
+ of the Document to the public.
+
+ A section "Entitled XYZ" means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ "Acknowledgements", "Dedications", "Endorsements", or "History".)
+ To "Preserve the Title" of such a section when you modify the
+ Document means that it remains a section "Entitled XYZ" according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow
+ the conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the
+ title equally prominent and visible. You may add other material
+ on the covers in addition. Copying with changes limited to the
+ covers, as long as they preserve the title of the Document and
+ satisfy these conditions, can be treated as verbatim copying in
+ other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a
+ machine-readable Transparent copy along with each Opaque copy, or
+ state in or with each Opaque copy a computer-network location from
+ which the general network-using public has access to download
+ using public-standard network protocols a complete Transparent
+ copy of the Document, free of added material. If you use the
+ latter option, you must take reasonably prudent steps, when you
+ begin distribution of Opaque copies in quantity, to ensure that
+ this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you
+ distribute an Opaque copy (directly or through your agents or
+ retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of
+ copies, to give them a chance to provide you with an updated
+ version of the Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with
+ the Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version to
+ whoever possesses a copy of it. In addition, you must do these
+ things in the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of
+ previous versions (which should, if there were any, be listed
+ in the History section of the Document). You may use the
+ same title as a previous version if the original publisher of
+ that version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has fewer than five), unless they release you
+ from this requirement.
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section Entitled "History", Preserve its Title,
+ and add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on
+ the Title Page. If there is no section Entitled "History" in
+ the Document, create one stating the title, year, authors,
+ and publisher of the Document as given on its Title Page,
+ then add an item describing the Modified Version as stated in
+ the previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in
+ the "History" section. You may omit a network location for a
+ work that was published at least four years before the
+ Document itself, or if the original publisher of the version
+ it refers to gives permission.
+
+ K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the
+ section all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section
+ titles.
+
+ M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section to be Entitled
+ "Endorsements" or to conflict in title with any Invariant
+ Section.
+
+ O. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option
+ designate some or all of these sections as invariant. To do this,
+ add their titles to the list of Invariant Sections in the Modified
+ Version's license notice. These titles must be distinct from any
+ other section titles.
+
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end
+ of the list of Cover Texts in the Modified Version. Only one
+ passage of Front-Cover Text and one of Back-Cover Text may be
+ added by (or through arrangements made by) any one entity. If the
+ Document already includes a cover text for the same cover,
+ previously added by you or by arrangement made by the same entity
+ you are acting on behalf of, you may not add another; but you may
+ replace the old one, on explicit permission from the previous
+ publisher that added the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination
+ all of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ "History" in the various original documents, forming one section
+ Entitled "History"; likewise combine any sections Entitled
+ "Acknowledgements", and any sections Entitled "Dedications". You
+ must delete all sections Entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the
+ documents in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow
+ this License in all other respects regarding verbatim copying of
+ that document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of
+ a storage or distribution medium, is called an "aggregate" if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation's users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document's Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense, or distribute it is void,
+ and will automatically terminate your rights under this License.
+
+ However, if you cease all violation of this License, then your
+ license from a particular copyright holder is reinstated (a)
+ provisionally, unless and until the copyright holder explicitly
+ and finally terminates your license, and (b) permanently, if the
+ copyright holder fails to notify you of the violation by some
+ reasonable means prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+ reinstated permanently if the copyright holder notifies you of the
+ violation by some reasonable means, this is the first time you have
+ received notice of violation of this License (for any work) from
+ that copyright holder, and you cure the violation prior to 30 days
+ after your receipt of the notice.
+
+ Termination of your rights under this section does not terminate
+ the licenses of parties who have received copies or rights from
+ you under this License. If your rights have been terminated and
+ not permanently reinstated, receipt of a copy of some or all of
+ the same material does not give you any rights to use it.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ `http://www.gnu.org/copyleft/'.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by the
+ Free Software Foundation. If the Document specifies that a proxy
+ can decide which future versions of this License can be used, that
+ proxy's public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+
+ 11. RELICENSING
+
+ "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+ World Wide Web server that publishes copyrightable works and also
+ provides prominent facilities for anybody to edit those works. A
+ public wiki that anybody can edit is an example of such a server.
+ A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+ site means any set of copyrightable works thus published on the MMC
+ site.
+
+ "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+ license published by Creative Commons Corporation, a not-for-profit
+ corporation with a principal place of business in San Francisco,
+ California, as well as future copyleft versions of that license
+ published by that same organization.
+
+ "Incorporate" means to publish or republish a Document, in whole or
+ in part, as part of another Document.
+
+ An MMC is "eligible for relicensing" if it is licensed under this
+ License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently
+ incorporated in whole or in part into the MMC, (1) had no cover
+ texts or invariant sections, and (2) were thus incorporated prior
+ to November 1, 2008.
+
+ The operator of an MMC Site may republish an MMC contained in the
+ site under CC-BY-SA on the same site at any time before August 1,
+ 2009, provided the MMC is eligible for relicensing.
+
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ being LIST.
+
+ If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+File: bfd.info, Node: BFD Index, Prev: GNU Free Documentation License, Up: Top
+
+BFD Index
+*********
+
+
+* Menu:
+
+* _bfd_final_link_relocate: Relocating the section contents.
+ (line 22)
+* _bfd_generic_link_add_archive_symbols: Adding symbols from an archive.
+ (line 12)
+* _bfd_generic_link_add_one_symbol: Adding symbols from an object file.
+ (line 19)
+* _bfd_generic_make_empty_symbol: symbol handling functions.
+ (line 92)
+* _bfd_link_add_symbols in target vector: Adding Symbols to the Hash Table.
+ (line 6)
+* _bfd_link_final_link in target vector: Performing the Final Link.
+ (line 6)
+* _bfd_link_hash_table_create in target vector: Creating a Linker Hash Table.
+ (line 6)
+* _bfd_relocate_contents: Relocating the section contents.
+ (line 22)
+* aout_SIZE_machine_type: aout. (line 147)
+* aout_SIZE_mkobject: aout. (line 139)
+* aout_SIZE_new_section_hook: aout. (line 177)
+* aout_SIZE_set_arch_mach: aout. (line 164)
+* aout_SIZE_some_aout_object_p: aout. (line 125)
+* aout_SIZE_swap_exec_header_in: aout. (line 101)
+* aout_SIZE_swap_exec_header_out: aout. (line 113)
+* arelent_chain: typedef arelent. (line 339)
+* BFD: Overview. (line 6)
+* BFD canonical format: Canonical format. (line 11)
+* bfd_alloc: Opening and Closing.
+ (line 210)
+* bfd_alloc2: Opening and Closing.
+ (line 219)
+* bfd_alt_mach_code: BFD front end. (line 689)
+* bfd_arch_bits_per_address: Architectures. (line 517)
+* bfd_arch_bits_per_byte: Architectures. (line 509)
+* bfd_arch_get_compatible: Architectures. (line 452)
+* bfd_arch_list: Architectures. (line 443)
+* bfd_arch_mach_octets_per_byte: Architectures. (line 586)
+* BFD_ARELOC_BFIN_ADD: howto manager. (line 1005)
+* BFD_ARELOC_BFIN_ADDR: howto manager. (line 1056)
+* BFD_ARELOC_BFIN_AND: howto manager. (line 1026)
+* BFD_ARELOC_BFIN_COMP: howto manager. (line 1047)
+* BFD_ARELOC_BFIN_CONST: howto manager. (line 1002)
+* BFD_ARELOC_BFIN_DIV: howto manager. (line 1014)
+* BFD_ARELOC_BFIN_HWPAGE: howto manager. (line 1053)
+* BFD_ARELOC_BFIN_LAND: howto manager. (line 1035)
+* BFD_ARELOC_BFIN_LEN: howto manager. (line 1041)
+* BFD_ARELOC_BFIN_LOR: howto manager. (line 1038)
+* BFD_ARELOC_BFIN_LSHIFT: howto manager. (line 1020)
+* BFD_ARELOC_BFIN_MOD: howto manager. (line 1017)
+* BFD_ARELOC_BFIN_MULT: howto manager. (line 1011)
+* BFD_ARELOC_BFIN_NEG: howto manager. (line 1044)
+* BFD_ARELOC_BFIN_OR: howto manager. (line 1029)
+* BFD_ARELOC_BFIN_PAGE: howto manager. (line 1050)
+* BFD_ARELOC_BFIN_PUSH: howto manager. (line 999)
+* BFD_ARELOC_BFIN_RSHIFT: howto manager. (line 1023)
+* BFD_ARELOC_BFIN_SUB: howto manager. (line 1008)
+* BFD_ARELOC_BFIN_XOR: howto manager. (line 1032)
+* bfd_cache_close: File Caching. (line 26)
+* bfd_cache_close_all: File Caching. (line 39)
+* bfd_cache_init: File Caching. (line 18)
+* bfd_calc_gnu_debuglink_crc32: Opening and Closing.
+ (line 246)
+* bfd_canonicalize_reloc: BFD front end. (line 408)
+* bfd_canonicalize_symtab: symbol handling functions.
+ (line 50)
+* bfd_check_format: Formats. (line 21)
+* bfd_check_format_matches: Formats. (line 52)
+* bfd_check_overflow: typedef arelent. (line 351)
+* bfd_close: Opening and Closing.
+ (line 135)
+* bfd_close_all_done: Opening and Closing.
+ (line 153)
+* bfd_coff_backend_data: coff. (line 304)
+* bfd_copy_private_bfd_data: BFD front end. (line 547)
+* bfd_copy_private_header_data: BFD front end. (line 529)
+* bfd_copy_private_section_data: section prototypes. (line 255)
+* bfd_copy_private_symbol_data: symbol handling functions.
+ (line 140)
+* bfd_core_file_failing_command: Core Files. (line 12)
+* bfd_core_file_failing_signal: Core Files. (line 21)
+* bfd_create: Opening and Closing.
+ (line 172)
+* bfd_create_gnu_debuglink_section: Opening and Closing.
+ (line 312)
+* bfd_decode_symclass: symbol handling functions.
+ (line 111)
+* bfd_default_arch_struct: Architectures. (line 464)
+* bfd_default_compatible: Architectures. (line 526)
+* bfd_default_reloc_type_lookup: howto manager. (line 2247)
+* bfd_default_scan: Architectures. (line 535)
+* bfd_default_set_arch_mach: Architectures. (line 482)
+* bfd_demangle: BFD front end. (line 787)
+* bfd_emul_get_commonpagesize: BFD front end. (line 767)
+* bfd_emul_get_maxpagesize: BFD front end. (line 747)
+* bfd_emul_set_commonpagesize: BFD front end. (line 778)
+* bfd_emul_set_maxpagesize: BFD front end. (line 758)
+* bfd_errmsg: BFD front end. (line 333)
+* bfd_fdopenr: Opening and Closing.
+ (line 46)
+* bfd_fill_in_gnu_debuglink_section: Opening and Closing.
+ (line 326)
+* bfd_find_target: bfd_target. (line 445)
+* bfd_find_version_for_sym: Writing the symbol table.
+ (line 80)
+* bfd_follow_gnu_debuglink: Opening and Closing.
+ (line 291)
+* bfd_fopen: Opening and Closing.
+ (line 9)
+* bfd_format_string: Formats. (line 79)
+* bfd_generic_define_common_symbol: Writing the symbol table.
+ (line 67)
+* bfd_generic_discard_group: section prototypes. (line 281)
+* bfd_generic_gc_sections: howto manager. (line 2278)
+* bfd_generic_get_relocated_section_contents: howto manager. (line 2298)
+* bfd_generic_is_group_section: section prototypes. (line 273)
+* bfd_generic_merge_sections: howto manager. (line 2288)
+* bfd_generic_relax_section: howto manager. (line 2265)
+* bfd_get_arch: Architectures. (line 493)
+* bfd_get_arch_info: Architectures. (line 545)
+* bfd_get_arch_size: BFD front end. (line 452)
+* bfd_get_error: BFD front end. (line 314)
+* bfd_get_error_handler: BFD front end. (line 384)
+* bfd_get_gp_size: BFD front end. (line 493)
+* bfd_get_mach: Architectures. (line 501)
+* bfd_get_mtime: BFD front end. (line 831)
+* bfd_get_next_mapent: Archives. (line 52)
+* bfd_get_reloc_code_name: howto manager. (line 2256)
+* bfd_get_reloc_size: typedef arelent. (line 330)
+* bfd_get_reloc_upper_bound: BFD front end. (line 398)
+* bfd_get_section_by_name: section prototypes. (line 17)
+* bfd_get_section_by_name_if: section prototypes. (line 31)
+* bfd_get_section_contents: section prototypes. (line 228)
+* bfd_get_sign_extend_vma: BFD front end. (line 465)
+* bfd_get_size <1>: Internal. (line 25)
+* bfd_get_size: BFD front end. (line 840)
+* bfd_get_symtab_upper_bound: symbol handling functions.
+ (line 6)
+* bfd_get_unique_section_name: section prototypes. (line 50)
+* bfd_h_put_size: Internal. (line 97)
+* bfd_hash_allocate: Creating and Freeing a Hash Table.
+ (line 17)
+* bfd_hash_lookup: Looking Up or Entering a String.
+ (line 6)
+* bfd_hash_newfunc: Creating and Freeing a Hash Table.
+ (line 12)
+* bfd_hash_set_default_size: Creating and Freeing a Hash Table.
+ (line 25)
+* bfd_hash_table_free: Creating and Freeing a Hash Table.
+ (line 21)
+* bfd_hash_table_init: Creating and Freeing a Hash Table.
+ (line 6)
+* bfd_hash_table_init_n: Creating and Freeing a Hash Table.
+ (line 6)
+* bfd_hash_traverse: Traversing a Hash Table.
+ (line 6)
+* bfd_init: Initialization. (line 11)
+* bfd_install_relocation: typedef arelent. (line 392)
+* bfd_is_local_label: symbol handling functions.
+ (line 17)
+* bfd_is_local_label_name: symbol handling functions.
+ (line 26)
+* bfd_is_target_special_symbol: symbol handling functions.
+ (line 38)
+* bfd_is_undefined_symclass: symbol handling functions.
+ (line 120)
+* bfd_link_split_section: Writing the symbol table.
+ (line 44)
+* bfd_log2: Internal. (line 164)
+* bfd_lookup_arch: Architectures. (line 553)
+* bfd_make_debug_symbol: symbol handling functions.
+ (line 102)
+* bfd_make_empty_symbol: symbol handling functions.
+ (line 78)
+* bfd_make_readable: Opening and Closing.
+ (line 196)
+* bfd_make_section: section prototypes. (line 129)
+* bfd_make_section_anyway: section prototypes. (line 100)
+* bfd_make_section_anyway_with_flags: section prototypes. (line 82)
+* bfd_make_section_old_way: section prototypes. (line 62)
+* bfd_make_section_with_flags: section prototypes. (line 116)
+* bfd_make_writable: Opening and Closing.
+ (line 182)
+* bfd_malloc_and_get_section: section prototypes. (line 245)
+* bfd_map_over_sections: section prototypes. (line 155)
+* bfd_merge_private_bfd_data: BFD front end. (line 563)
+* bfd_mmap: BFD front end. (line 869)
+* bfd_octets_per_byte: Architectures. (line 576)
+* bfd_open_file: File Caching. (line 52)
+* bfd_openr: Opening and Closing.
+ (line 30)
+* bfd_openr_iovec: Opening and Closing.
+ (line 76)
+* bfd_openr_next_archived_file: Archives. (line 78)
+* bfd_openstreamr: Opening and Closing.
+ (line 67)
+* bfd_openw: Opening and Closing.
+ (line 123)
+* bfd_perform_relocation: typedef arelent. (line 367)
+* bfd_perror: BFD front end. (line 342)
+* bfd_preserve_finish: BFD front end. (line 737)
+* bfd_preserve_restore: BFD front end. (line 727)
+* bfd_preserve_save: BFD front end. (line 711)
+* bfd_print_symbol_vandf: symbol handling functions.
+ (line 70)
+* bfd_printable_arch_mach: Architectures. (line 564)
+* bfd_printable_name: Architectures. (line 424)
+* bfd_put_size: Internal. (line 22)
+* BFD_RELOC_12_PCREL: howto manager. (line 39)
+* BFD_RELOC_14: howto manager. (line 31)
+* BFD_RELOC_16: howto manager. (line 30)
+* BFD_RELOC_16_BASEREL: howto manager. (line 95)
+* BFD_RELOC_16_GOT_PCREL: howto manager. (line 52)
+* BFD_RELOC_16_GOTOFF: howto manager. (line 55)
+* BFD_RELOC_16_PCREL: howto manager. (line 38)
+* BFD_RELOC_16_PCREL_S2: howto manager. (line 107)
+* BFD_RELOC_16_PLT_PCREL: howto manager. (line 63)
+* BFD_RELOC_16_PLTOFF: howto manager. (line 67)
+* BFD_RELOC_16C_ABS20: howto manager. (line 1838)
+* BFD_RELOC_16C_ABS20_C: howto manager. (line 1839)
+* BFD_RELOC_16C_ABS24: howto manager. (line 1840)
+* BFD_RELOC_16C_ABS24_C: howto manager. (line 1841)
+* BFD_RELOC_16C_DISP04: howto manager. (line 1818)
+* BFD_RELOC_16C_DISP04_C: howto manager. (line 1819)
+* BFD_RELOC_16C_DISP08: howto manager. (line 1820)
+* BFD_RELOC_16C_DISP08_C: howto manager. (line 1821)
+* BFD_RELOC_16C_DISP16: howto manager. (line 1822)
+* BFD_RELOC_16C_DISP16_C: howto manager. (line 1823)
+* BFD_RELOC_16C_DISP24: howto manager. (line 1824)
+* BFD_RELOC_16C_DISP24_C: howto manager. (line 1825)
+* BFD_RELOC_16C_DISP24a: howto manager. (line 1826)
+* BFD_RELOC_16C_DISP24a_C: howto manager. (line 1827)
+* BFD_RELOC_16C_IMM04: howto manager. (line 1842)
+* BFD_RELOC_16C_IMM04_C: howto manager. (line 1843)
+* BFD_RELOC_16C_IMM16: howto manager. (line 1844)
+* BFD_RELOC_16C_IMM16_C: howto manager. (line 1845)
+* BFD_RELOC_16C_IMM20: howto manager. (line 1846)
+* BFD_RELOC_16C_IMM20_C: howto manager. (line 1847)
+* BFD_RELOC_16C_IMM24: howto manager. (line 1848)
+* BFD_RELOC_16C_IMM24_C: howto manager. (line 1849)
+* BFD_RELOC_16C_IMM32: howto manager. (line 1850)
+* BFD_RELOC_16C_IMM32_C: howto manager. (line 1851)
+* BFD_RELOC_16C_NUM08: howto manager. (line 1812)
+* BFD_RELOC_16C_NUM08_C: howto manager. (line 1813)
+* BFD_RELOC_16C_NUM16: howto manager. (line 1814)
+* BFD_RELOC_16C_NUM16_C: howto manager. (line 1815)
+* BFD_RELOC_16C_NUM32: howto manager. (line 1816)
+* BFD_RELOC_16C_NUM32_C: howto manager. (line 1817)
+* BFD_RELOC_16C_REG04: howto manager. (line 1828)
+* BFD_RELOC_16C_REG04_C: howto manager. (line 1829)
+* BFD_RELOC_16C_REG04a: howto manager. (line 1830)
+* BFD_RELOC_16C_REG04a_C: howto manager. (line 1831)
+* BFD_RELOC_16C_REG14: howto manager. (line 1832)
+* BFD_RELOC_16C_REG14_C: howto manager. (line 1833)
+* BFD_RELOC_16C_REG16: howto manager. (line 1834)
+* BFD_RELOC_16C_REG16_C: howto manager. (line 1835)
+* BFD_RELOC_16C_REG20: howto manager. (line 1836)
+* BFD_RELOC_16C_REG20_C: howto manager. (line 1837)
+* BFD_RELOC_23_PCREL_S2: howto manager. (line 108)
+* BFD_RELOC_24: howto manager. (line 29)
+* BFD_RELOC_24_PCREL: howto manager. (line 37)
+* BFD_RELOC_24_PLT_PCREL: howto manager. (line 62)
+* BFD_RELOC_26: howto manager. (line 28)
+* BFD_RELOC_32: howto manager. (line 27)
+* BFD_RELOC_32_BASEREL: howto manager. (line 94)
+* BFD_RELOC_32_GOT_PCREL: howto manager. (line 51)
+* BFD_RELOC_32_GOTOFF: howto manager. (line 54)
+* BFD_RELOC_32_PCREL: howto manager. (line 36)
+* BFD_RELOC_32_PCREL_S2: howto manager. (line 106)
+* BFD_RELOC_32_PLT_PCREL: howto manager. (line 61)
+* BFD_RELOC_32_PLTOFF: howto manager. (line 66)
+* BFD_RELOC_32_SECREL: howto manager. (line 48)
+* BFD_RELOC_386_COPY: howto manager. (line 505)
+* BFD_RELOC_386_GLOB_DAT: howto manager. (line 506)
+* BFD_RELOC_386_GOT32: howto manager. (line 503)
+* BFD_RELOC_386_GOTOFF: howto manager. (line 509)
+* BFD_RELOC_386_GOTPC: howto manager. (line 510)
+* BFD_RELOC_386_IRELATIVE: howto manager. (line 526)
+* BFD_RELOC_386_JUMP_SLOT: howto manager. (line 507)
+* BFD_RELOC_386_PLT32: howto manager. (line 504)
+* BFD_RELOC_386_RELATIVE: howto manager. (line 508)
+* BFD_RELOC_386_TLS_DESC: howto manager. (line 525)
+* BFD_RELOC_386_TLS_DESC_CALL: howto manager. (line 524)
+* BFD_RELOC_386_TLS_DTPMOD32: howto manager. (line 520)
+* BFD_RELOC_386_TLS_DTPOFF32: howto manager. (line 521)
+* BFD_RELOC_386_TLS_GD: howto manager. (line 515)
+* BFD_RELOC_386_TLS_GOTDESC: howto manager. (line 523)
+* BFD_RELOC_386_TLS_GOTIE: howto manager. (line 513)
+* BFD_RELOC_386_TLS_IE: howto manager. (line 512)
+* BFD_RELOC_386_TLS_IE_32: howto manager. (line 518)
+* BFD_RELOC_386_TLS_LDM: howto manager. (line 516)
+* BFD_RELOC_386_TLS_LDO_32: howto manager. (line 517)
+* BFD_RELOC_386_TLS_LE: howto manager. (line 514)
+* BFD_RELOC_386_TLS_LE_32: howto manager. (line 519)
+* BFD_RELOC_386_TLS_TPOFF: howto manager. (line 511)
+* BFD_RELOC_386_TLS_TPOFF32: howto manager. (line 522)
+* BFD_RELOC_390_12: howto manager. (line 1498)
+* BFD_RELOC_390_20: howto manager. (line 1598)
+* BFD_RELOC_390_COPY: howto manager. (line 1507)
+* BFD_RELOC_390_GLOB_DAT: howto manager. (line 1510)
+* BFD_RELOC_390_GOT12: howto manager. (line 1501)
+* BFD_RELOC_390_GOT16: howto manager. (line 1522)
+* BFD_RELOC_390_GOT20: howto manager. (line 1599)
+* BFD_RELOC_390_GOT64: howto manager. (line 1540)
+* BFD_RELOC_390_GOTENT: howto manager. (line 1546)
+* BFD_RELOC_390_GOTOFF64: howto manager. (line 1549)
+* BFD_RELOC_390_GOTPC: howto manager. (line 1519)
+* BFD_RELOC_390_GOTPCDBL: howto manager. (line 1537)
+* BFD_RELOC_390_GOTPLT12: howto manager. (line 1552)
+* BFD_RELOC_390_GOTPLT16: howto manager. (line 1555)
+* BFD_RELOC_390_GOTPLT20: howto manager. (line 1600)
+* BFD_RELOC_390_GOTPLT32: howto manager. (line 1558)
+* BFD_RELOC_390_GOTPLT64: howto manager. (line 1561)
+* BFD_RELOC_390_GOTPLTENT: howto manager. (line 1564)
+* BFD_RELOC_390_JMP_SLOT: howto manager. (line 1513)
+* BFD_RELOC_390_PC16DBL: howto manager. (line 1525)
+* BFD_RELOC_390_PC32DBL: howto manager. (line 1531)
+* BFD_RELOC_390_PLT16DBL: howto manager. (line 1528)
+* BFD_RELOC_390_PLT32: howto manager. (line 1504)
+* BFD_RELOC_390_PLT32DBL: howto manager. (line 1534)
+* BFD_RELOC_390_PLT64: howto manager. (line 1543)
+* BFD_RELOC_390_PLTOFF16: howto manager. (line 1567)
+* BFD_RELOC_390_PLTOFF32: howto manager. (line 1570)
+* BFD_RELOC_390_PLTOFF64: howto manager. (line 1573)
+* BFD_RELOC_390_RELATIVE: howto manager. (line 1516)
+* BFD_RELOC_390_TLS_DTPMOD: howto manager. (line 1593)
+* BFD_RELOC_390_TLS_DTPOFF: howto manager. (line 1594)
+* BFD_RELOC_390_TLS_GD32: howto manager. (line 1579)
+* BFD_RELOC_390_TLS_GD64: howto manager. (line 1580)
+* BFD_RELOC_390_TLS_GDCALL: howto manager. (line 1577)
+* BFD_RELOC_390_TLS_GOTIE12: howto manager. (line 1581)
+* BFD_RELOC_390_TLS_GOTIE20: howto manager. (line 1601)
+* BFD_RELOC_390_TLS_GOTIE32: howto manager. (line 1582)
+* BFD_RELOC_390_TLS_GOTIE64: howto manager. (line 1583)
+* BFD_RELOC_390_TLS_IE32: howto manager. (line 1586)
+* BFD_RELOC_390_TLS_IE64: howto manager. (line 1587)
+* BFD_RELOC_390_TLS_IEENT: howto manager. (line 1588)
+* BFD_RELOC_390_TLS_LDCALL: howto manager. (line 1578)
+* BFD_RELOC_390_TLS_LDM32: howto manager. (line 1584)
+* BFD_RELOC_390_TLS_LDM64: howto manager. (line 1585)
+* BFD_RELOC_390_TLS_LDO32: howto manager. (line 1591)
+* BFD_RELOC_390_TLS_LDO64: howto manager. (line 1592)
+* BFD_RELOC_390_TLS_LE32: howto manager. (line 1589)
+* BFD_RELOC_390_TLS_LE64: howto manager. (line 1590)
+* BFD_RELOC_390_TLS_LOAD: howto manager. (line 1576)
+* BFD_RELOC_390_TLS_TPOFF: howto manager. (line 1595)
+* BFD_RELOC_64: howto manager. (line 26)
+* BFD_RELOC_64_PCREL: howto manager. (line 35)
+* BFD_RELOC_64_PLT_PCREL: howto manager. (line 60)
+* BFD_RELOC_64_PLTOFF: howto manager. (line 65)
+* BFD_RELOC_68K_GLOB_DAT: howto manager. (line 74)
+* BFD_RELOC_68K_JMP_SLOT: howto manager. (line 75)
+* BFD_RELOC_68K_RELATIVE: howto manager. (line 76)
+* BFD_RELOC_68K_TLS_GD16: howto manager. (line 78)
+* BFD_RELOC_68K_TLS_GD32: howto manager. (line 77)
+* BFD_RELOC_68K_TLS_GD8: howto manager. (line 79)
+* BFD_RELOC_68K_TLS_IE16: howto manager. (line 87)
+* BFD_RELOC_68K_TLS_IE32: howto manager. (line 86)
+* BFD_RELOC_68K_TLS_IE8: howto manager. (line 88)
+* BFD_RELOC_68K_TLS_LDM16: howto manager. (line 81)
+* BFD_RELOC_68K_TLS_LDM32: howto manager. (line 80)
+* BFD_RELOC_68K_TLS_LDM8: howto manager. (line 82)
+* BFD_RELOC_68K_TLS_LDO16: howto manager. (line 84)
+* BFD_RELOC_68K_TLS_LDO32: howto manager. (line 83)
+* BFD_RELOC_68K_TLS_LDO8: howto manager. (line 85)
+* BFD_RELOC_68K_TLS_LE16: howto manager. (line 90)
+* BFD_RELOC_68K_TLS_LE32: howto manager. (line 89)
+* BFD_RELOC_68K_TLS_LE8: howto manager. (line 91)
+* BFD_RELOC_8: howto manager. (line 32)
+* BFD_RELOC_860_COPY: howto manager. (line 1966)
+* BFD_RELOC_860_GLOB_DAT: howto manager. (line 1967)
+* BFD_RELOC_860_HAGOT: howto manager. (line 1992)
+* BFD_RELOC_860_HAGOTOFF: howto manager. (line 1993)
+* BFD_RELOC_860_HAPC: howto manager. (line 1994)
+* BFD_RELOC_860_HIGH: howto manager. (line 1995)
+* BFD_RELOC_860_HIGHADJ: howto manager. (line 1991)
+* BFD_RELOC_860_HIGOT: howto manager. (line 1996)
+* BFD_RELOC_860_HIGOTOFF: howto manager. (line 1997)
+* BFD_RELOC_860_JUMP_SLOT: howto manager. (line 1968)
+* BFD_RELOC_860_LOGOT0: howto manager. (line 1980)
+* BFD_RELOC_860_LOGOT1: howto manager. (line 1982)
+* BFD_RELOC_860_LOGOTOFF0: howto manager. (line 1984)
+* BFD_RELOC_860_LOGOTOFF1: howto manager. (line 1986)
+* BFD_RELOC_860_LOGOTOFF2: howto manager. (line 1988)
+* BFD_RELOC_860_LOGOTOFF3: howto manager. (line 1989)
+* BFD_RELOC_860_LOPC: howto manager. (line 1990)
+* BFD_RELOC_860_LOW0: howto manager. (line 1973)
+* BFD_RELOC_860_LOW1: howto manager. (line 1975)
+* BFD_RELOC_860_LOW2: howto manager. (line 1977)
+* BFD_RELOC_860_LOW3: howto manager. (line 1979)
+* BFD_RELOC_860_PC16: howto manager. (line 1972)
+* BFD_RELOC_860_PC26: howto manager. (line 1970)
+* BFD_RELOC_860_PLT26: howto manager. (line 1971)
+* BFD_RELOC_860_RELATIVE: howto manager. (line 1969)
+* BFD_RELOC_860_SPGOT0: howto manager. (line 1981)
+* BFD_RELOC_860_SPGOT1: howto manager. (line 1983)
+* BFD_RELOC_860_SPGOTOFF0: howto manager. (line 1985)
+* BFD_RELOC_860_SPGOTOFF1: howto manager. (line 1987)
+* BFD_RELOC_860_SPLIT0: howto manager. (line 1974)
+* BFD_RELOC_860_SPLIT1: howto manager. (line 1976)
+* BFD_RELOC_860_SPLIT2: howto manager. (line 1978)
+* BFD_RELOC_8_BASEREL: howto manager. (line 99)
+* BFD_RELOC_8_FFnn: howto manager. (line 103)
+* BFD_RELOC_8_GOT_PCREL: howto manager. (line 53)
+* BFD_RELOC_8_GOTOFF: howto manager. (line 59)
+* BFD_RELOC_8_PCREL: howto manager. (line 40)
+* BFD_RELOC_8_PLT_PCREL: howto manager. (line 64)
+* BFD_RELOC_8_PLTOFF: howto manager. (line 71)
+* BFD_RELOC_ALPHA_BOH: howto manager. (line 313)
+* BFD_RELOC_ALPHA_BRSGP: howto manager. (line 296)
+* BFD_RELOC_ALPHA_BSR: howto manager. (line 305)
+* BFD_RELOC_ALPHA_CODEADDR: howto manager. (line 287)
+* BFD_RELOC_ALPHA_DTPMOD64: howto manager. (line 319)
+* BFD_RELOC_ALPHA_DTPREL16: howto manager. (line 324)
+* BFD_RELOC_ALPHA_DTPREL64: howto manager. (line 321)
+* BFD_RELOC_ALPHA_DTPREL_HI16: howto manager. (line 322)
+* BFD_RELOC_ALPHA_DTPREL_LO16: howto manager. (line 323)
+* BFD_RELOC_ALPHA_ELF_LITERAL: howto manager. (line 252)
+* BFD_RELOC_ALPHA_GOTDTPREL16: howto manager. (line 320)
+* BFD_RELOC_ALPHA_GOTTPREL16: howto manager. (line 325)
+* BFD_RELOC_ALPHA_GPDISP: howto manager. (line 246)
+* BFD_RELOC_ALPHA_GPDISP_HI16: howto manager. (line 232)
+* BFD_RELOC_ALPHA_GPDISP_LO16: howto manager. (line 240)
+* BFD_RELOC_ALPHA_GPREL_HI16: howto manager. (line 291)
+* BFD_RELOC_ALPHA_GPREL_LO16: howto manager. (line 292)
+* BFD_RELOC_ALPHA_HINT: howto manager. (line 278)
+* BFD_RELOC_ALPHA_LDA: howto manager. (line 309)
+* BFD_RELOC_ALPHA_LINKAGE: howto manager. (line 283)
+* BFD_RELOC_ALPHA_LITERAL: howto manager. (line 251)
+* BFD_RELOC_ALPHA_LITUSE: howto manager. (line 253)
+* BFD_RELOC_ALPHA_NOP: howto manager. (line 301)
+* BFD_RELOC_ALPHA_TLSGD: howto manager. (line 317)
+* BFD_RELOC_ALPHA_TLSLDM: howto manager. (line 318)
+* BFD_RELOC_ALPHA_TPREL16: howto manager. (line 329)
+* BFD_RELOC_ALPHA_TPREL64: howto manager. (line 326)
+* BFD_RELOC_ALPHA_TPREL_HI16: howto manager. (line 327)
+* BFD_RELOC_ALPHA_TPREL_LO16: howto manager. (line 328)
+* BFD_RELOC_ARC_B22_PCREL: howto manager. (line 934)
+* BFD_RELOC_ARC_B26: howto manager. (line 939)
+* BFD_RELOC_ARM_ADR_IMM: howto manager. (line 827)
+* BFD_RELOC_ARM_ADRL_IMMEDIATE: howto manager. (line 814)
+* BFD_RELOC_ARM_ALU_PC_G0: howto manager. (line 781)
+* BFD_RELOC_ARM_ALU_PC_G0_NC: howto manager. (line 780)
+* BFD_RELOC_ARM_ALU_PC_G1: howto manager. (line 783)
+* BFD_RELOC_ARM_ALU_PC_G1_NC: howto manager. (line 782)
+* BFD_RELOC_ARM_ALU_PC_G2: howto manager. (line 784)
+* BFD_RELOC_ARM_ALU_SB_G0: howto manager. (line 795)
+* BFD_RELOC_ARM_ALU_SB_G0_NC: howto manager. (line 794)
+* BFD_RELOC_ARM_ALU_SB_G1: howto manager. (line 797)
+* BFD_RELOC_ARM_ALU_SB_G1_NC: howto manager. (line 796)
+* BFD_RELOC_ARM_ALU_SB_G2: howto manager. (line 798)
+* BFD_RELOC_ARM_CP_OFF_IMM: howto manager. (line 823)
+* BFD_RELOC_ARM_CP_OFF_IMM_S2: howto manager. (line 824)
+* BFD_RELOC_ARM_GLOB_DAT: howto manager. (line 762)
+* BFD_RELOC_ARM_GOT32: howto manager. (line 763)
+* BFD_RELOC_ARM_GOTOFF: howto manager. (line 766)
+* BFD_RELOC_ARM_GOTPC: howto manager. (line 767)
+* BFD_RELOC_ARM_HWLITERAL: howto manager. (line 834)
+* BFD_RELOC_ARM_IMMEDIATE: howto manager. (line 813)
+* BFD_RELOC_ARM_IN_POOL: howto manager. (line 830)
+* BFD_RELOC_ARM_JUMP_SLOT: howto manager. (line 761)
+* BFD_RELOC_ARM_LDC_PC_G0: howto manager. (line 791)
+* BFD_RELOC_ARM_LDC_PC_G1: howto manager. (line 792)
+* BFD_RELOC_ARM_LDC_PC_G2: howto manager. (line 793)
+* BFD_RELOC_ARM_LDC_SB_G0: howto manager. (line 805)
+* BFD_RELOC_ARM_LDC_SB_G1: howto manager. (line 806)
+* BFD_RELOC_ARM_LDC_SB_G2: howto manager. (line 807)
+* BFD_RELOC_ARM_LDR_IMM: howto manager. (line 828)
+* BFD_RELOC_ARM_LDR_PC_G0: howto manager. (line 785)
+* BFD_RELOC_ARM_LDR_PC_G1: howto manager. (line 786)
+* BFD_RELOC_ARM_LDR_PC_G2: howto manager. (line 787)
+* BFD_RELOC_ARM_LDR_SB_G0: howto manager. (line 799)
+* BFD_RELOC_ARM_LDR_SB_G1: howto manager. (line 800)
+* BFD_RELOC_ARM_LDR_SB_G2: howto manager. (line 801)
+* BFD_RELOC_ARM_LDRS_PC_G0: howto manager. (line 788)
+* BFD_RELOC_ARM_LDRS_PC_G1: howto manager. (line 789)
+* BFD_RELOC_ARM_LDRS_PC_G2: howto manager. (line 790)
+* BFD_RELOC_ARM_LDRS_SB_G0: howto manager. (line 802)
+* BFD_RELOC_ARM_LDRS_SB_G1: howto manager. (line 803)
+* BFD_RELOC_ARM_LDRS_SB_G2: howto manager. (line 804)
+* BFD_RELOC_ARM_LITERAL: howto manager. (line 829)
+* BFD_RELOC_ARM_MOVT: howto manager. (line 752)
+* BFD_RELOC_ARM_MOVT_PCREL: howto manager. (line 754)
+* BFD_RELOC_ARM_MOVW: howto manager. (line 751)
+* BFD_RELOC_ARM_MOVW_PCREL: howto manager. (line 753)
+* BFD_RELOC_ARM_MULTI: howto manager. (line 822)
+* BFD_RELOC_ARM_OFFSET_IMM: howto manager. (line 725)
+* BFD_RELOC_ARM_OFFSET_IMM8: howto manager. (line 831)
+* BFD_RELOC_ARM_PCREL_BLX: howto manager. (line 696)
+* BFD_RELOC_ARM_PCREL_BRANCH: howto manager. (line 692)
+* BFD_RELOC_ARM_PCREL_CALL: howto manager. (line 706)
+* BFD_RELOC_ARM_PCREL_JUMP: howto manager. (line 710)
+* BFD_RELOC_ARM_PLT32: howto manager. (line 764)
+* BFD_RELOC_ARM_PREL31: howto manager. (line 748)
+* BFD_RELOC_ARM_RELATIVE: howto manager. (line 765)
+* BFD_RELOC_ARM_ROSEGREL32: howto manager. (line 737)
+* BFD_RELOC_ARM_SBREL32: howto manager. (line 740)
+* BFD_RELOC_ARM_SHIFT_IMM: howto manager. (line 819)
+* BFD_RELOC_ARM_SMC: howto manager. (line 820)
+* BFD_RELOC_ARM_SWI: howto manager. (line 821)
+* BFD_RELOC_ARM_T32_ADD_IMM: howto manager. (line 816)
+* BFD_RELOC_ARM_T32_ADD_PC12: howto manager. (line 818)
+* BFD_RELOC_ARM_T32_CP_OFF_IMM: howto manager. (line 825)
+* BFD_RELOC_ARM_T32_CP_OFF_IMM_S2: howto manager. (line 826)
+* BFD_RELOC_ARM_T32_IMM12: howto manager. (line 817)
+* BFD_RELOC_ARM_T32_IMMEDIATE: howto manager. (line 815)
+* BFD_RELOC_ARM_T32_OFFSET_IMM: howto manager. (line 833)
+* BFD_RELOC_ARM_T32_OFFSET_U8: howto manager. (line 832)
+* BFD_RELOC_ARM_TARGET1: howto manager. (line 733)
+* BFD_RELOC_ARM_TARGET2: howto manager. (line 743)
+* BFD_RELOC_ARM_THUMB_ADD: howto manager. (line 835)
+* BFD_RELOC_ARM_THUMB_IMM: howto manager. (line 836)
+* BFD_RELOC_ARM_THUMB_MOVT: howto manager. (line 756)
+* BFD_RELOC_ARM_THUMB_MOVT_PCREL: howto manager. (line 758)
+* BFD_RELOC_ARM_THUMB_MOVW: howto manager. (line 755)
+* BFD_RELOC_ARM_THUMB_MOVW_PCREL: howto manager. (line 757)
+* BFD_RELOC_ARM_THUMB_OFFSET: howto manager. (line 729)
+* BFD_RELOC_ARM_THUMB_SHIFT: howto manager. (line 837)
+* BFD_RELOC_ARM_TLS_DTPMOD32: howto manager. (line 774)
+* BFD_RELOC_ARM_TLS_DTPOFF32: howto manager. (line 773)
+* BFD_RELOC_ARM_TLS_GD32: howto manager. (line 770)
+* BFD_RELOC_ARM_TLS_IE32: howto manager. (line 776)
+* BFD_RELOC_ARM_TLS_LDM32: howto manager. (line 772)
+* BFD_RELOC_ARM_TLS_LDO32: howto manager. (line 771)
+* BFD_RELOC_ARM_TLS_LE32: howto manager. (line 777)
+* BFD_RELOC_ARM_TLS_TPOFF32: howto manager. (line 775)
+* BFD_RELOC_ARM_V4BX: howto manager. (line 810)
+* BFD_RELOC_AVR_13_PCREL: howto manager. (line 1399)
+* BFD_RELOC_AVR_16_PM: howto manager. (line 1403)
+* BFD_RELOC_AVR_6: howto manager. (line 1490)
+* BFD_RELOC_AVR_6_ADIW: howto manager. (line 1494)
+* BFD_RELOC_AVR_7_PCREL: howto manager. (line 1395)
+* BFD_RELOC_AVR_CALL: howto manager. (line 1482)
+* BFD_RELOC_AVR_HH8_LDI: howto manager. (line 1415)
+* BFD_RELOC_AVR_HH8_LDI_NEG: howto manager. (line 1434)
+* BFD_RELOC_AVR_HH8_LDI_PM: howto manager. (line 1463)
+* BFD_RELOC_AVR_HH8_LDI_PM_NEG: howto manager. (line 1477)
+* BFD_RELOC_AVR_HI8_LDI: howto manager. (line 1411)
+* BFD_RELOC_AVR_HI8_LDI_GS: howto manager. (line 1457)
+* BFD_RELOC_AVR_HI8_LDI_NEG: howto manager. (line 1429)
+* BFD_RELOC_AVR_HI8_LDI_PM: howto manager. (line 1453)
+* BFD_RELOC_AVR_HI8_LDI_PM_NEG: howto manager. (line 1472)
+* BFD_RELOC_AVR_LDI: howto manager. (line 1486)
+* BFD_RELOC_AVR_LO8_LDI: howto manager. (line 1407)
+* BFD_RELOC_AVR_LO8_LDI_GS: howto manager. (line 1447)
+* BFD_RELOC_AVR_LO8_LDI_NEG: howto manager. (line 1424)
+* BFD_RELOC_AVR_LO8_LDI_PM: howto manager. (line 1443)
+* BFD_RELOC_AVR_LO8_LDI_PM_NEG: howto manager. (line 1468)
+* BFD_RELOC_AVR_MS8_LDI: howto manager. (line 1420)
+* BFD_RELOC_AVR_MS8_LDI_NEG: howto manager. (line 1439)
+* BFD_RELOC_BFIN_10_PCREL: howto manager. (line 959)
+* BFD_RELOC_BFIN_11_PCREL: howto manager. (line 962)
+* BFD_RELOC_BFIN_12_PCREL_JUMP: howto manager. (line 965)
+* BFD_RELOC_BFIN_12_PCREL_JUMP_S: howto manager. (line 968)
+* BFD_RELOC_BFIN_16_HIGH: howto manager. (line 947)
+* BFD_RELOC_BFIN_16_IMM: howto manager. (line 944)
+* BFD_RELOC_BFIN_16_LOW: howto manager. (line 956)
+* BFD_RELOC_BFIN_24_PCREL_CALL_X: howto manager. (line 971)
+* BFD_RELOC_BFIN_24_PCREL_JUMP_L: howto manager. (line 974)
+* BFD_RELOC_BFIN_4_PCREL: howto manager. (line 950)
+* BFD_RELOC_BFIN_5_PCREL: howto manager. (line 953)
+* BFD_RELOC_BFIN_FUNCDESC: howto manager. (line 980)
+* BFD_RELOC_BFIN_FUNCDESC_GOT17M4: howto manager. (line 981)
+* BFD_RELOC_BFIN_FUNCDESC_GOTHI: howto manager. (line 982)
+* BFD_RELOC_BFIN_FUNCDESC_GOTLO: howto manager. (line 983)
+* BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4: howto manager. (line 985)
+* BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI: howto manager. (line 986)
+* BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO: howto manager. (line 987)
+* BFD_RELOC_BFIN_FUNCDESC_VALUE: howto manager. (line 984)
+* BFD_RELOC_BFIN_GOT: howto manager. (line 993)
+* BFD_RELOC_BFIN_GOT17M4: howto manager. (line 977)
+* BFD_RELOC_BFIN_GOTHI: howto manager. (line 978)
+* BFD_RELOC_BFIN_GOTLO: howto manager. (line 979)
+* BFD_RELOC_BFIN_GOTOFF17M4: howto manager. (line 988)
+* BFD_RELOC_BFIN_GOTOFFHI: howto manager. (line 989)
+* BFD_RELOC_BFIN_GOTOFFLO: howto manager. (line 990)
+* BFD_RELOC_BFIN_PLTPC: howto manager. (line 996)
+* bfd_reloc_code_type: howto manager. (line 10)
+* BFD_RELOC_CR16_ABS20: howto manager. (line 1866)
+* BFD_RELOC_CR16_ABS24: howto manager. (line 1867)
+* BFD_RELOC_CR16_DISP16: howto manager. (line 1877)
+* BFD_RELOC_CR16_DISP20: howto manager. (line 1878)
+* BFD_RELOC_CR16_DISP24: howto manager. (line 1879)
+* BFD_RELOC_CR16_DISP24a: howto manager. (line 1880)
+* BFD_RELOC_CR16_DISP4: howto manager. (line 1875)
+* BFD_RELOC_CR16_DISP8: howto manager. (line 1876)
+* BFD_RELOC_CR16_GLOB_DAT: howto manager. (line 1886)
+* BFD_RELOC_CR16_GOT_REGREL20: howto manager. (line 1884)
+* BFD_RELOC_CR16_GOTC_REGREL20: howto manager. (line 1885)
+* BFD_RELOC_CR16_IMM16: howto manager. (line 1870)
+* BFD_RELOC_CR16_IMM20: howto manager. (line 1871)
+* BFD_RELOC_CR16_IMM24: howto manager. (line 1872)
+* BFD_RELOC_CR16_IMM32: howto manager. (line 1873)
+* BFD_RELOC_CR16_IMM32a: howto manager. (line 1874)
+* BFD_RELOC_CR16_IMM4: howto manager. (line 1868)
+* BFD_RELOC_CR16_IMM8: howto manager. (line 1869)
+* BFD_RELOC_CR16_NUM16: howto manager. (line 1855)
+* BFD_RELOC_CR16_NUM32: howto manager. (line 1856)
+* BFD_RELOC_CR16_NUM32a: howto manager. (line 1857)
+* BFD_RELOC_CR16_NUM8: howto manager. (line 1854)
+* BFD_RELOC_CR16_REGREL0: howto manager. (line 1858)
+* BFD_RELOC_CR16_REGREL14: howto manager. (line 1861)
+* BFD_RELOC_CR16_REGREL14a: howto manager. (line 1862)
+* BFD_RELOC_CR16_REGREL16: howto manager. (line 1863)
+* BFD_RELOC_CR16_REGREL20: howto manager. (line 1864)
+* BFD_RELOC_CR16_REGREL20a: howto manager. (line 1865)
+* BFD_RELOC_CR16_REGREL4: howto manager. (line 1859)
+* BFD_RELOC_CR16_REGREL4a: howto manager. (line 1860)
+* BFD_RELOC_CR16_SWITCH16: howto manager. (line 1882)
+* BFD_RELOC_CR16_SWITCH32: howto manager. (line 1883)
+* BFD_RELOC_CR16_SWITCH8: howto manager. (line 1881)
+* BFD_RELOC_CRIS_16_DTPREL: howto manager. (line 1957)
+* BFD_RELOC_CRIS_16_GOT: howto manager. (line 1933)
+* BFD_RELOC_CRIS_16_GOT_GD: howto manager. (line 1953)
+* BFD_RELOC_CRIS_16_GOT_TPREL: howto manager. (line 1959)
+* BFD_RELOC_CRIS_16_GOTPLT: howto manager. (line 1939)
+* BFD_RELOC_CRIS_16_TPREL: howto manager. (line 1961)
+* BFD_RELOC_CRIS_32_DTPREL: howto manager. (line 1956)
+* BFD_RELOC_CRIS_32_GD: howto manager. (line 1954)
+* BFD_RELOC_CRIS_32_GOT: howto manager. (line 1930)
+* BFD_RELOC_CRIS_32_GOT_GD: howto manager. (line 1952)
+* BFD_RELOC_CRIS_32_GOT_TPREL: howto manager. (line 1958)
+* BFD_RELOC_CRIS_32_GOTPLT: howto manager. (line 1936)
+* BFD_RELOC_CRIS_32_GOTREL: howto manager. (line 1942)
+* BFD_RELOC_CRIS_32_IE: howto manager. (line 1963)
+* BFD_RELOC_CRIS_32_PLT_GOTREL: howto manager. (line 1945)
+* BFD_RELOC_CRIS_32_PLT_PCREL: howto manager. (line 1948)
+* BFD_RELOC_CRIS_32_TPREL: howto manager. (line 1960)
+* BFD_RELOC_CRIS_BDISP8: howto manager. (line 1911)
+* BFD_RELOC_CRIS_COPY: howto manager. (line 1924)
+* BFD_RELOC_CRIS_DTP: howto manager. (line 1955)
+* BFD_RELOC_CRIS_DTPMOD: howto manager. (line 1962)
+* BFD_RELOC_CRIS_GLOB_DAT: howto manager. (line 1925)
+* BFD_RELOC_CRIS_JUMP_SLOT: howto manager. (line 1926)
+* BFD_RELOC_CRIS_LAPCQ_OFFSET: howto manager. (line 1919)
+* BFD_RELOC_CRIS_RELATIVE: howto manager. (line 1927)
+* BFD_RELOC_CRIS_SIGNED_16: howto manager. (line 1917)
+* BFD_RELOC_CRIS_SIGNED_6: howto manager. (line 1913)
+* BFD_RELOC_CRIS_SIGNED_8: howto manager. (line 1915)
+* BFD_RELOC_CRIS_UNSIGNED_16: howto manager. (line 1918)
+* BFD_RELOC_CRIS_UNSIGNED_4: howto manager. (line 1920)
+* BFD_RELOC_CRIS_UNSIGNED_5: howto manager. (line 1912)
+* BFD_RELOC_CRIS_UNSIGNED_6: howto manager. (line 1914)
+* BFD_RELOC_CRIS_UNSIGNED_8: howto manager. (line 1916)
+* BFD_RELOC_CRX_ABS16: howto manager. (line 1899)
+* BFD_RELOC_CRX_ABS32: howto manager. (line 1900)
+* BFD_RELOC_CRX_IMM16: howto manager. (line 1904)
+* BFD_RELOC_CRX_IMM32: howto manager. (line 1905)
+* BFD_RELOC_CRX_NUM16: howto manager. (line 1902)
+* BFD_RELOC_CRX_NUM32: howto manager. (line 1903)
+* BFD_RELOC_CRX_NUM8: howto manager. (line 1901)
+* BFD_RELOC_CRX_REGREL12: howto manager. (line 1895)
+* BFD_RELOC_CRX_REGREL22: howto manager. (line 1896)
+* BFD_RELOC_CRX_REGREL28: howto manager. (line 1897)
+* BFD_RELOC_CRX_REGREL32: howto manager. (line 1898)
+* BFD_RELOC_CRX_REL16: howto manager. (line 1892)
+* BFD_RELOC_CRX_REL24: howto manager. (line 1893)
+* BFD_RELOC_CRX_REL32: howto manager. (line 1894)
+* BFD_RELOC_CRX_REL4: howto manager. (line 1889)
+* BFD_RELOC_CRX_REL8: howto manager. (line 1890)
+* BFD_RELOC_CRX_REL8_CMP: howto manager. (line 1891)
+* BFD_RELOC_CRX_SWITCH16: howto manager. (line 1907)
+* BFD_RELOC_CRX_SWITCH32: howto manager. (line 1908)
+* BFD_RELOC_CRX_SWITCH8: howto manager. (line 1906)
+* BFD_RELOC_CTOR: howto manager. (line 686)
+* BFD_RELOC_D10V_10_PCREL_L: howto manager. (line 1063)
+* BFD_RELOC_D10V_10_PCREL_R: howto manager. (line 1059)
+* BFD_RELOC_D10V_18: howto manager. (line 1068)
+* BFD_RELOC_D10V_18_PCREL: howto manager. (line 1071)
+* BFD_RELOC_D30V_15: howto manager. (line 1086)
+* BFD_RELOC_D30V_15_PCREL: howto manager. (line 1090)
+* BFD_RELOC_D30V_15_PCREL_R: howto manager. (line 1094)
+* BFD_RELOC_D30V_21: howto manager. (line 1099)
+* BFD_RELOC_D30V_21_PCREL: howto manager. (line 1103)
+* BFD_RELOC_D30V_21_PCREL_R: howto manager. (line 1107)
+* BFD_RELOC_D30V_32: howto manager. (line 1112)
+* BFD_RELOC_D30V_32_PCREL: howto manager. (line 1115)
+* BFD_RELOC_D30V_6: howto manager. (line 1074)
+* BFD_RELOC_D30V_9_PCREL: howto manager. (line 1077)
+* BFD_RELOC_D30V_9_PCREL_R: howto manager. (line 1081)
+* BFD_RELOC_DLX_HI16_S: howto manager. (line 1118)
+* BFD_RELOC_DLX_JMP26: howto manager. (line 1124)
+* BFD_RELOC_DLX_LO16: howto manager. (line 1121)
+* BFD_RELOC_FR30_10_IN_8: howto manager. (line 1303)
+* BFD_RELOC_FR30_12_PCREL: howto manager. (line 1311)
+* BFD_RELOC_FR30_20: howto manager. (line 1287)
+* BFD_RELOC_FR30_48: howto manager. (line 1284)
+* BFD_RELOC_FR30_6_IN_4: howto manager. (line 1291)
+* BFD_RELOC_FR30_8_IN_8: howto manager. (line 1295)
+* BFD_RELOC_FR30_9_IN_8: howto manager. (line 1299)
+* BFD_RELOC_FR30_9_PCREL: howto manager. (line 1307)
+* BFD_RELOC_FRV_FUNCDESC: howto manager. (line 438)
+* BFD_RELOC_FRV_FUNCDESC_GOT12: howto manager. (line 439)
+* BFD_RELOC_FRV_FUNCDESC_GOTHI: howto manager. (line 440)
+* BFD_RELOC_FRV_FUNCDESC_GOTLO: howto manager. (line 441)
+* BFD_RELOC_FRV_FUNCDESC_GOTOFF12: howto manager. (line 443)
+* BFD_RELOC_FRV_FUNCDESC_GOTOFFHI: howto manager. (line 444)
+* BFD_RELOC_FRV_FUNCDESC_GOTOFFLO: howto manager. (line 445)
+* BFD_RELOC_FRV_FUNCDESC_VALUE: howto manager. (line 442)
+* BFD_RELOC_FRV_GETTLSOFF: howto manager. (line 449)
+* BFD_RELOC_FRV_GETTLSOFF_RELAX: howto manager. (line 462)
+* BFD_RELOC_FRV_GOT12: howto manager. (line 435)
+* BFD_RELOC_FRV_GOTHI: howto manager. (line 436)
+* BFD_RELOC_FRV_GOTLO: howto manager. (line 437)
+* BFD_RELOC_FRV_GOTOFF12: howto manager. (line 446)
+* BFD_RELOC_FRV_GOTOFFHI: howto manager. (line 447)
+* BFD_RELOC_FRV_GOTOFFLO: howto manager. (line 448)
+* BFD_RELOC_FRV_GOTTLSDESC12: howto manager. (line 451)
+* BFD_RELOC_FRV_GOTTLSDESCHI: howto manager. (line 452)
+* BFD_RELOC_FRV_GOTTLSDESCLO: howto manager. (line 453)
+* BFD_RELOC_FRV_GOTTLSOFF12: howto manager. (line 457)
+* BFD_RELOC_FRV_GOTTLSOFFHI: howto manager. (line 458)
+* BFD_RELOC_FRV_GOTTLSOFFLO: howto manager. (line 459)
+* BFD_RELOC_FRV_GPREL12: howto manager. (line 430)
+* BFD_RELOC_FRV_GPREL32: howto manager. (line 432)
+* BFD_RELOC_FRV_GPRELHI: howto manager. (line 433)
+* BFD_RELOC_FRV_GPRELLO: howto manager. (line 434)
+* BFD_RELOC_FRV_GPRELU12: howto manager. (line 431)
+* BFD_RELOC_FRV_HI16: howto manager. (line 429)
+* BFD_RELOC_FRV_LABEL16: howto manager. (line 426)
+* BFD_RELOC_FRV_LABEL24: howto manager. (line 427)
+* BFD_RELOC_FRV_LO16: howto manager. (line 428)
+* BFD_RELOC_FRV_TLSDESC_RELAX: howto manager. (line 461)
+* BFD_RELOC_FRV_TLSDESC_VALUE: howto manager. (line 450)
+* BFD_RELOC_FRV_TLSMOFF: howto manager. (line 464)
+* BFD_RELOC_FRV_TLSMOFF12: howto manager. (line 454)
+* BFD_RELOC_FRV_TLSMOFFHI: howto manager. (line 455)
+* BFD_RELOC_FRV_TLSMOFFLO: howto manager. (line 456)
+* BFD_RELOC_FRV_TLSOFF: howto manager. (line 460)
+* BFD_RELOC_FRV_TLSOFF_RELAX: howto manager. (line 463)
+* BFD_RELOC_GPREL16: howto manager. (line 121)
+* BFD_RELOC_GPREL32: howto manager. (line 122)
+* BFD_RELOC_H8_DIR16A8: howto manager. (line 2004)
+* BFD_RELOC_H8_DIR16R8: howto manager. (line 2005)
+* BFD_RELOC_H8_DIR24A8: howto manager. (line 2006)
+* BFD_RELOC_H8_DIR24R8: howto manager. (line 2007)
+* BFD_RELOC_H8_DIR32A16: howto manager. (line 2008)
+* BFD_RELOC_HI16: howto manager. (line 342)
+* BFD_RELOC_HI16_BASEREL: howto manager. (line 97)
+* BFD_RELOC_HI16_GOTOFF: howto manager. (line 57)
+* BFD_RELOC_HI16_PCREL: howto manager. (line 354)
+* BFD_RELOC_HI16_PLTOFF: howto manager. (line 69)
+* BFD_RELOC_HI16_S: howto manager. (line 345)
+* BFD_RELOC_HI16_S_BASEREL: howto manager. (line 98)
+* BFD_RELOC_HI16_S_GOTOFF: howto manager. (line 58)
+* BFD_RELOC_HI16_S_PCREL: howto manager. (line 357)
+* BFD_RELOC_HI16_S_PLTOFF: howto manager. (line 70)
+* BFD_RELOC_HI22: howto manager. (line 116)
+* BFD_RELOC_I370_D12: howto manager. (line 683)
+* BFD_RELOC_I960_CALLJ: howto manager. (line 128)
+* BFD_RELOC_IA64_COPY: howto manager. (line 1748)
+* BFD_RELOC_IA64_DIR32LSB: howto manager. (line 1693)
+* BFD_RELOC_IA64_DIR32MSB: howto manager. (line 1692)
+* BFD_RELOC_IA64_DIR64LSB: howto manager. (line 1695)
+* BFD_RELOC_IA64_DIR64MSB: howto manager. (line 1694)
+* BFD_RELOC_IA64_DTPMOD64LSB: howto manager. (line 1758)
+* BFD_RELOC_IA64_DTPMOD64MSB: howto manager. (line 1757)
+* BFD_RELOC_IA64_DTPREL14: howto manager. (line 1760)
+* BFD_RELOC_IA64_DTPREL22: howto manager. (line 1761)
+* BFD_RELOC_IA64_DTPREL32LSB: howto manager. (line 1764)
+* BFD_RELOC_IA64_DTPREL32MSB: howto manager. (line 1763)
+* BFD_RELOC_IA64_DTPREL64I: howto manager. (line 1762)
+* BFD_RELOC_IA64_DTPREL64LSB: howto manager. (line 1766)
+* BFD_RELOC_IA64_DTPREL64MSB: howto manager. (line 1765)
+* BFD_RELOC_IA64_FPTR32LSB: howto manager. (line 1710)
+* BFD_RELOC_IA64_FPTR32MSB: howto manager. (line 1709)
+* BFD_RELOC_IA64_FPTR64I: howto manager. (line 1708)
+* BFD_RELOC_IA64_FPTR64LSB: howto manager. (line 1712)
+* BFD_RELOC_IA64_FPTR64MSB: howto manager. (line 1711)
+* BFD_RELOC_IA64_GPREL22: howto manager. (line 1696)
+* BFD_RELOC_IA64_GPREL32LSB: howto manager. (line 1699)
+* BFD_RELOC_IA64_GPREL32MSB: howto manager. (line 1698)
+* BFD_RELOC_IA64_GPREL64I: howto manager. (line 1697)
+* BFD_RELOC_IA64_GPREL64LSB: howto manager. (line 1701)
+* BFD_RELOC_IA64_GPREL64MSB: howto manager. (line 1700)
+* BFD_RELOC_IA64_IMM14: howto manager. (line 1689)
+* BFD_RELOC_IA64_IMM22: howto manager. (line 1690)
+* BFD_RELOC_IA64_IMM64: howto manager. (line 1691)
+* BFD_RELOC_IA64_IPLTLSB: howto manager. (line 1747)
+* BFD_RELOC_IA64_IPLTMSB: howto manager. (line 1746)
+* BFD_RELOC_IA64_LDXMOV: howto manager. (line 1750)
+* BFD_RELOC_IA64_LTOFF22: howto manager. (line 1702)
+* BFD_RELOC_IA64_LTOFF22X: howto manager. (line 1749)
+* BFD_RELOC_IA64_LTOFF64I: howto manager. (line 1703)
+* BFD_RELOC_IA64_LTOFF_DTPMOD22: howto manager. (line 1759)
+* BFD_RELOC_IA64_LTOFF_DTPREL22: howto manager. (line 1767)
+* BFD_RELOC_IA64_LTOFF_FPTR22: howto manager. (line 1724)
+* BFD_RELOC_IA64_LTOFF_FPTR32LSB: howto manager. (line 1727)
+* BFD_RELOC_IA64_LTOFF_FPTR32MSB: howto manager. (line 1726)
+* BFD_RELOC_IA64_LTOFF_FPTR64I: howto manager. (line 1725)
+* BFD_RELOC_IA64_LTOFF_FPTR64LSB: howto manager. (line 1729)
+* BFD_RELOC_IA64_LTOFF_FPTR64MSB: howto manager. (line 1728)
+* BFD_RELOC_IA64_LTOFF_TPREL22: howto manager. (line 1756)
+* BFD_RELOC_IA64_LTV32LSB: howto manager. (line 1743)
+* BFD_RELOC_IA64_LTV32MSB: howto manager. (line 1742)
+* BFD_RELOC_IA64_LTV64LSB: howto manager. (line 1745)
+* BFD_RELOC_IA64_LTV64MSB: howto manager. (line 1744)
+* BFD_RELOC_IA64_PCREL21B: howto manager. (line 1713)
+* BFD_RELOC_IA64_PCREL21BI: howto manager. (line 1714)
+* BFD_RELOC_IA64_PCREL21F: howto manager. (line 1716)
+* BFD_RELOC_IA64_PCREL21M: howto manager. (line 1715)
+* BFD_RELOC_IA64_PCREL22: howto manager. (line 1717)
+* BFD_RELOC_IA64_PCREL32LSB: howto manager. (line 1721)
+* BFD_RELOC_IA64_PCREL32MSB: howto manager. (line 1720)
+* BFD_RELOC_IA64_PCREL60B: howto manager. (line 1718)
+* BFD_RELOC_IA64_PCREL64I: howto manager. (line 1719)
+* BFD_RELOC_IA64_PCREL64LSB: howto manager. (line 1723)
+* BFD_RELOC_IA64_PCREL64MSB: howto manager. (line 1722)
+* BFD_RELOC_IA64_PLTOFF22: howto manager. (line 1704)
+* BFD_RELOC_IA64_PLTOFF64I: howto manager. (line 1705)
+* BFD_RELOC_IA64_PLTOFF64LSB: howto manager. (line 1707)
+* BFD_RELOC_IA64_PLTOFF64MSB: howto manager. (line 1706)
+* BFD_RELOC_IA64_REL32LSB: howto manager. (line 1739)
+* BFD_RELOC_IA64_REL32MSB: howto manager. (line 1738)
+* BFD_RELOC_IA64_REL64LSB: howto manager. (line 1741)
+* BFD_RELOC_IA64_REL64MSB: howto manager. (line 1740)
+* BFD_RELOC_IA64_SECREL32LSB: howto manager. (line 1735)
+* BFD_RELOC_IA64_SECREL32MSB: howto manager. (line 1734)
+* BFD_RELOC_IA64_SECREL64LSB: howto manager. (line 1737)
+* BFD_RELOC_IA64_SECREL64MSB: howto manager. (line 1736)
+* BFD_RELOC_IA64_SEGREL32LSB: howto manager. (line 1731)
+* BFD_RELOC_IA64_SEGREL32MSB: howto manager. (line 1730)
+* BFD_RELOC_IA64_SEGREL64LSB: howto manager. (line 1733)
+* BFD_RELOC_IA64_SEGREL64MSB: howto manager. (line 1732)
+* BFD_RELOC_IA64_TPREL14: howto manager. (line 1751)
+* BFD_RELOC_IA64_TPREL22: howto manager. (line 1752)
+* BFD_RELOC_IA64_TPREL64I: howto manager. (line 1753)
+* BFD_RELOC_IA64_TPREL64LSB: howto manager. (line 1755)
+* BFD_RELOC_IA64_TPREL64MSB: howto manager. (line 1754)
+* BFD_RELOC_IP2K_ADDR16CJP: howto manager. (line 1641)
+* BFD_RELOC_IP2K_BANK: howto manager. (line 1638)
+* BFD_RELOC_IP2K_EX8DATA: howto manager. (line 1649)
+* BFD_RELOC_IP2K_FR9: howto manager. (line 1635)
+* BFD_RELOC_IP2K_FR_OFFSET: howto manager. (line 1662)
+* BFD_RELOC_IP2K_HI8DATA: howto manager. (line 1648)
+* BFD_RELOC_IP2K_HI8INSN: howto manager. (line 1653)
+* BFD_RELOC_IP2K_LO8DATA: howto manager. (line 1647)
+* BFD_RELOC_IP2K_LO8INSN: howto manager. (line 1652)
+* BFD_RELOC_IP2K_PAGE3: howto manager. (line 1644)
+* BFD_RELOC_IP2K_PC_SKIP: howto manager. (line 1656)
+* BFD_RELOC_IP2K_TEXT: howto manager. (line 1659)
+* BFD_RELOC_IQ2000_OFFSET_16: howto manager. (line 2058)
+* BFD_RELOC_IQ2000_OFFSET_21: howto manager. (line 2059)
+* BFD_RELOC_IQ2000_UHI16: howto manager. (line 2060)
+* BFD_RELOC_LM32_16_GOT: howto manager. (line 2165)
+* BFD_RELOC_LM32_BRANCH: howto manager. (line 2164)
+* BFD_RELOC_LM32_CALL: howto manager. (line 2163)
+* BFD_RELOC_LM32_COPY: howto manager. (line 2168)
+* BFD_RELOC_LM32_GLOB_DAT: howto manager. (line 2169)
+* BFD_RELOC_LM32_GOTOFF_HI16: howto manager. (line 2166)
+* BFD_RELOC_LM32_GOTOFF_LO16: howto manager. (line 2167)
+* BFD_RELOC_LM32_JMP_SLOT: howto manager. (line 2170)
+* BFD_RELOC_LM32_RELATIVE: howto manager. (line 2171)
+* BFD_RELOC_LO10: howto manager. (line 117)
+* BFD_RELOC_LO16: howto manager. (line 351)
+* BFD_RELOC_LO16_BASEREL: howto manager. (line 96)
+* BFD_RELOC_LO16_GOTOFF: howto manager. (line 56)
+* BFD_RELOC_LO16_PCREL: howto manager. (line 360)
+* BFD_RELOC_LO16_PLTOFF: howto manager. (line 68)
+* BFD_RELOC_M32C_HI8: howto manager. (line 1127)
+* BFD_RELOC_M32C_RL_1ADDR: howto manager. (line 1129)
+* BFD_RELOC_M32C_RL_2ADDR: howto manager. (line 1130)
+* BFD_RELOC_M32C_RL_JUMP: howto manager. (line 1128)
+* BFD_RELOC_M32R_10_PCREL: howto manager. (line 1137)
+* BFD_RELOC_M32R_18_PCREL: howto manager. (line 1141)
+* BFD_RELOC_M32R_24: howto manager. (line 1133)
+* BFD_RELOC_M32R_26_PCREL: howto manager. (line 1144)
+* BFD_RELOC_M32R_26_PLTREL: howto manager. (line 1163)
+* BFD_RELOC_M32R_COPY: howto manager. (line 1164)
+* BFD_RELOC_M32R_GLOB_DAT: howto manager. (line 1165)
+* BFD_RELOC_M32R_GOT16_HI_SLO: howto manager. (line 1174)
+* BFD_RELOC_M32R_GOT16_HI_ULO: howto manager. (line 1173)
+* BFD_RELOC_M32R_GOT16_LO: howto manager. (line 1175)
+* BFD_RELOC_M32R_GOT24: howto manager. (line 1162)
+* BFD_RELOC_M32R_GOTOFF: howto manager. (line 1168)
+* BFD_RELOC_M32R_GOTOFF_HI_SLO: howto manager. (line 1170)
+* BFD_RELOC_M32R_GOTOFF_HI_ULO: howto manager. (line 1169)
+* BFD_RELOC_M32R_GOTOFF_LO: howto manager. (line 1171)
+* BFD_RELOC_M32R_GOTPC24: howto manager. (line 1172)
+* BFD_RELOC_M32R_GOTPC_HI_SLO: howto manager. (line 1177)
+* BFD_RELOC_M32R_GOTPC_HI_ULO: howto manager. (line 1176)
+* BFD_RELOC_M32R_GOTPC_LO: howto manager. (line 1178)
+* BFD_RELOC_M32R_HI16_SLO: howto manager. (line 1151)
+* BFD_RELOC_M32R_HI16_ULO: howto manager. (line 1147)
+* BFD_RELOC_M32R_JMP_SLOT: howto manager. (line 1166)
+* BFD_RELOC_M32R_LO16: howto manager. (line 1155)
+* BFD_RELOC_M32R_RELATIVE: howto manager. (line 1167)
+* BFD_RELOC_M32R_SDA16: howto manager. (line 1158)
+* BFD_RELOC_M68HC11_24: howto manager. (line 1803)
+* BFD_RELOC_M68HC11_3B: howto manager. (line 1778)
+* BFD_RELOC_M68HC11_HI8: howto manager. (line 1770)
+* BFD_RELOC_M68HC11_LO16: howto manager. (line 1792)
+* BFD_RELOC_M68HC11_LO8: howto manager. (line 1774)
+* BFD_RELOC_M68HC11_PAGE: howto manager. (line 1798)
+* BFD_RELOC_M68HC11_RL_GROUP: howto manager. (line 1787)
+* BFD_RELOC_M68HC11_RL_JUMP: howto manager. (line 1781)
+* BFD_RELOC_M68HC12_5B: howto manager. (line 1809)
+* BFD_RELOC_MACH_O_PAIR: howto manager. (line 2178)
+* BFD_RELOC_MACH_O_SECTDIFF: howto manager. (line 2174)
+* BFD_RELOC_MCORE_PCREL_32: howto manager. (line 1318)
+* BFD_RELOC_MCORE_PCREL_IMM11BY2: howto manager. (line 1316)
+* BFD_RELOC_MCORE_PCREL_IMM4BY2: howto manager. (line 1317)
+* BFD_RELOC_MCORE_PCREL_IMM8BY4: howto manager. (line 1315)
+* BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2: howto manager. (line 1319)
+* BFD_RELOC_MCORE_RVA: howto manager. (line 1320)
+* BFD_RELOC_MEP_16: howto manager. (line 1324)
+* BFD_RELOC_MEP_32: howto manager. (line 1325)
+* BFD_RELOC_MEP_8: howto manager. (line 1323)
+* BFD_RELOC_MEP_ADDR24A4: howto manager. (line 1340)
+* BFD_RELOC_MEP_GNU_VTENTRY: howto manager. (line 1342)
+* BFD_RELOC_MEP_GNU_VTINHERIT: howto manager. (line 1341)
+* BFD_RELOC_MEP_GPREL: howto manager. (line 1334)
+* BFD_RELOC_MEP_HI16S: howto manager. (line 1333)
+* BFD_RELOC_MEP_HI16U: howto manager. (line 1332)
+* BFD_RELOC_MEP_LOW16: howto manager. (line 1331)
+* BFD_RELOC_MEP_PCABS24A2: howto manager. (line 1330)
+* BFD_RELOC_MEP_PCREL12A2: howto manager. (line 1327)
+* BFD_RELOC_MEP_PCREL17A2: howto manager. (line 1328)
+* BFD_RELOC_MEP_PCREL24A2: howto manager. (line 1329)
+* BFD_RELOC_MEP_PCREL8A2: howto manager. (line 1326)
+* BFD_RELOC_MEP_TPREL: howto manager. (line 1335)
+* BFD_RELOC_MEP_TPREL7: howto manager. (line 1336)
+* BFD_RELOC_MEP_TPREL7A2: howto manager. (line 1337)
+* BFD_RELOC_MEP_TPREL7A4: howto manager. (line 1338)
+* BFD_RELOC_MEP_UIMM24: howto manager. (line 1339)
+* BFD_RELOC_MICROBLAZE_32_GOTOFF: howto manager. (line 2225)
+* BFD_RELOC_MICROBLAZE_32_LO: howto manager. (line 2181)
+* BFD_RELOC_MICROBLAZE_32_LO_PCREL: howto manager. (line 2185)
+* BFD_RELOC_MICROBLAZE_32_ROSDA: howto manager. (line 2189)
+* BFD_RELOC_MICROBLAZE_32_RWSDA: howto manager. (line 2193)
+* BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM: howto manager. (line 2197)
+* BFD_RELOC_MICROBLAZE_64_GOT: howto manager. (line 2211)
+* BFD_RELOC_MICROBLAZE_64_GOTOFF: howto manager. (line 2220)
+* BFD_RELOC_MICROBLAZE_64_GOTPC: howto manager. (line 2206)
+* BFD_RELOC_MICROBLAZE_64_NONE: howto manager. (line 2201)
+* BFD_RELOC_MICROBLAZE_64_PLT: howto manager. (line 2215)
+* BFD_RELOC_MICROBLAZE_COPY: howto manager. (line 2229)
+* BFD_RELOC_MIPS16_CALL16: howto manager. (line 364)
+* BFD_RELOC_MIPS16_GOT16: howto manager. (line 363)
+* BFD_RELOC_MIPS16_GPREL: howto manager. (line 339)
+* BFD_RELOC_MIPS16_HI16: howto manager. (line 368)
+* BFD_RELOC_MIPS16_HI16_S: howto manager. (line 371)
+* BFD_RELOC_MIPS16_JMP: howto manager. (line 336)
+* BFD_RELOC_MIPS16_LO16: howto manager. (line 377)
+* BFD_RELOC_MIPS_CALL16: howto manager. (line 384)
+* BFD_RELOC_MIPS_CALL_HI16: howto manager. (line 387)
+* BFD_RELOC_MIPS_CALL_LO16: howto manager. (line 388)
+* BFD_RELOC_MIPS_COPY: howto manager. (line 419)
+* BFD_RELOC_MIPS_DELETE: howto manager. (line 397)
+* BFD_RELOC_MIPS_GOT16: howto manager. (line 383)
+* BFD_RELOC_MIPS_GOT_DISP: howto manager. (line 392)
+* BFD_RELOC_MIPS_GOT_HI16: howto manager. (line 385)
+* BFD_RELOC_MIPS_GOT_LO16: howto manager. (line 386)
+* BFD_RELOC_MIPS_GOT_OFST: howto manager. (line 391)
+* BFD_RELOC_MIPS_GOT_PAGE: howto manager. (line 390)
+* BFD_RELOC_MIPS_HIGHER: howto manager. (line 399)
+* BFD_RELOC_MIPS_HIGHEST: howto manager. (line 398)
+* BFD_RELOC_MIPS_INSERT_A: howto manager. (line 395)
+* BFD_RELOC_MIPS_INSERT_B: howto manager. (line 396)
+* BFD_RELOC_MIPS_JALR: howto manager. (line 403)
+* BFD_RELOC_MIPS_JMP: howto manager. (line 332)
+* BFD_RELOC_MIPS_JUMP_SLOT: howto manager. (line 420)
+* BFD_RELOC_MIPS_LITERAL: howto manager. (line 380)
+* BFD_RELOC_MIPS_REL16: howto manager. (line 401)
+* BFD_RELOC_MIPS_RELGOT: howto manager. (line 402)
+* BFD_RELOC_MIPS_SCN_DISP: howto manager. (line 400)
+* BFD_RELOC_MIPS_SHIFT5: howto manager. (line 393)
+* BFD_RELOC_MIPS_SHIFT6: howto manager. (line 394)
+* BFD_RELOC_MIPS_SUB: howto manager. (line 389)
+* BFD_RELOC_MIPS_TLS_DTPMOD32: howto manager. (line 404)
+* BFD_RELOC_MIPS_TLS_DTPMOD64: howto manager. (line 406)
+* BFD_RELOC_MIPS_TLS_DTPREL32: howto manager. (line 405)
+* BFD_RELOC_MIPS_TLS_DTPREL64: howto manager. (line 407)
+* BFD_RELOC_MIPS_TLS_DTPREL_HI16: howto manager. (line 410)
+* BFD_RELOC_MIPS_TLS_DTPREL_LO16: howto manager. (line 411)
+* BFD_RELOC_MIPS_TLS_GD: howto manager. (line 408)
+* BFD_RELOC_MIPS_TLS_GOTTPREL: howto manager. (line 412)
+* BFD_RELOC_MIPS_TLS_LDM: howto manager. (line 409)
+* BFD_RELOC_MIPS_TLS_TPREL32: howto manager. (line 413)
+* BFD_RELOC_MIPS_TLS_TPREL64: howto manager. (line 414)
+* BFD_RELOC_MIPS_TLS_TPREL_HI16: howto manager. (line 415)
+* BFD_RELOC_MIPS_TLS_TPREL_LO16: howto manager. (line 416)
+* BFD_RELOC_MMIX_ADDR19: howto manager. (line 1371)
+* BFD_RELOC_MMIX_ADDR27: howto manager. (line 1375)
+* BFD_RELOC_MMIX_BASE_PLUS_OFFSET: howto manager. (line 1387)
+* BFD_RELOC_MMIX_CBRANCH: howto manager. (line 1351)
+* BFD_RELOC_MMIX_CBRANCH_1: howto manager. (line 1353)
+* BFD_RELOC_MMIX_CBRANCH_2: howto manager. (line 1354)
+* BFD_RELOC_MMIX_CBRANCH_3: howto manager. (line 1355)
+* BFD_RELOC_MMIX_CBRANCH_J: howto manager. (line 1352)
+* BFD_RELOC_MMIX_GETA: howto manager. (line 1345)
+* BFD_RELOC_MMIX_GETA_1: howto manager. (line 1346)
+* BFD_RELOC_MMIX_GETA_2: howto manager. (line 1347)
+* BFD_RELOC_MMIX_GETA_3: howto manager. (line 1348)
+* BFD_RELOC_MMIX_JMP: howto manager. (line 1365)
+* BFD_RELOC_MMIX_JMP_1: howto manager. (line 1366)
+* BFD_RELOC_MMIX_JMP_2: howto manager. (line 1367)
+* BFD_RELOC_MMIX_JMP_3: howto manager. (line 1368)
+* BFD_RELOC_MMIX_LOCAL: howto manager. (line 1391)
+* BFD_RELOC_MMIX_PUSHJ: howto manager. (line 1358)
+* BFD_RELOC_MMIX_PUSHJ_1: howto manager. (line 1359)
+* BFD_RELOC_MMIX_PUSHJ_2: howto manager. (line 1360)
+* BFD_RELOC_MMIX_PUSHJ_3: howto manager. (line 1361)
+* BFD_RELOC_MMIX_PUSHJ_STUBBABLE: howto manager. (line 1362)
+* BFD_RELOC_MMIX_REG: howto manager. (line 1383)
+* BFD_RELOC_MMIX_REG_OR_BYTE: howto manager. (line 1379)
+* BFD_RELOC_MN10300_16_PCREL: howto manager. (line 1253)
+* BFD_RELOC_MN10300_32_PCREL: howto manager. (line 1249)
+* BFD_RELOC_MN10300_ALIGN: howto manager. (line 499)
+* BFD_RELOC_MN10300_COPY: howto manager. (line 482)
+* BFD_RELOC_MN10300_GLOB_DAT: howto manager. (line 485)
+* BFD_RELOC_MN10300_GOT16: howto manager. (line 478)
+* BFD_RELOC_MN10300_GOT24: howto manager. (line 474)
+* BFD_RELOC_MN10300_GOT32: howto manager. (line 470)
+* BFD_RELOC_MN10300_GOTOFF24: howto manager. (line 467)
+* BFD_RELOC_MN10300_JMP_SLOT: howto manager. (line 488)
+* BFD_RELOC_MN10300_RELATIVE: howto manager. (line 491)
+* BFD_RELOC_MN10300_SYM_DIFF: howto manager. (line 494)
+* BFD_RELOC_MOXIE_10_PCREL: howto manager. (line 423)
+* BFD_RELOC_MSP430_10_PCREL: howto manager. (line 2049)
+* BFD_RELOC_MSP430_16: howto manager. (line 2051)
+* BFD_RELOC_MSP430_16_BYTE: howto manager. (line 2053)
+* BFD_RELOC_MSP430_16_PCREL: howto manager. (line 2050)
+* BFD_RELOC_MSP430_16_PCREL_BYTE: howto manager. (line 2052)
+* BFD_RELOC_MSP430_2X_PCREL: howto manager. (line 2054)
+* BFD_RELOC_MSP430_RL_PCREL: howto manager. (line 2055)
+* BFD_RELOC_MT_GNU_VTENTRY: howto manager. (line 2043)
+* BFD_RELOC_MT_GNU_VTINHERIT: howto manager. (line 2040)
+* BFD_RELOC_MT_HI16: howto manager. (line 2034)
+* BFD_RELOC_MT_LO16: howto manager. (line 2037)
+* BFD_RELOC_MT_PC16: howto manager. (line 2031)
+* BFD_RELOC_MT_PCINSN8: howto manager. (line 2046)
+* BFD_RELOC_NONE: howto manager. (line 131)
+* BFD_RELOC_NS32K_DISP_16: howto manager. (line 565)
+* BFD_RELOC_NS32K_DISP_16_PCREL: howto manager. (line 568)
+* BFD_RELOC_NS32K_DISP_32: howto manager. (line 566)
+* BFD_RELOC_NS32K_DISP_32_PCREL: howto manager. (line 569)
+* BFD_RELOC_NS32K_DISP_8: howto manager. (line 564)
+* BFD_RELOC_NS32K_DISP_8_PCREL: howto manager. (line 567)
+* BFD_RELOC_NS32K_IMM_16: howto manager. (line 559)
+* BFD_RELOC_NS32K_IMM_16_PCREL: howto manager. (line 562)
+* BFD_RELOC_NS32K_IMM_32: howto manager. (line 560)
+* BFD_RELOC_NS32K_IMM_32_PCREL: howto manager. (line 563)
+* BFD_RELOC_NS32K_IMM_8: howto manager. (line 558)
+* BFD_RELOC_NS32K_IMM_8_PCREL: howto manager. (line 561)
+* BFD_RELOC_OPENRISC_ABS_26: howto manager. (line 2000)
+* BFD_RELOC_OPENRISC_REL_26: howto manager. (line 2001)
+* BFD_RELOC_PDP11_DISP_6_PCREL: howto manager. (line 573)
+* BFD_RELOC_PDP11_DISP_8_PCREL: howto manager. (line 572)
+* BFD_RELOC_PJ_CODE_DIR16: howto manager. (line 578)
+* BFD_RELOC_PJ_CODE_DIR32: howto manager. (line 579)
+* BFD_RELOC_PJ_CODE_HI16: howto manager. (line 576)
+* BFD_RELOC_PJ_CODE_LO16: howto manager. (line 577)
+* BFD_RELOC_PJ_CODE_REL16: howto manager. (line 580)
+* BFD_RELOC_PJ_CODE_REL32: howto manager. (line 581)
+* BFD_RELOC_PPC64_ADDR16_DS: howto manager. (line 626)
+* BFD_RELOC_PPC64_ADDR16_LO_DS: howto manager. (line 627)
+* BFD_RELOC_PPC64_DTPREL16_DS: howto manager. (line 675)
+* BFD_RELOC_PPC64_DTPREL16_HIGHER: howto manager. (line 677)
+* BFD_RELOC_PPC64_DTPREL16_HIGHERA: howto manager. (line 678)
+* BFD_RELOC_PPC64_DTPREL16_HIGHEST: howto manager. (line 679)
+* BFD_RELOC_PPC64_DTPREL16_HIGHESTA: howto manager. (line 680)
+* BFD_RELOC_PPC64_DTPREL16_LO_DS: howto manager. (line 676)
+* BFD_RELOC_PPC64_GOT16_DS: howto manager. (line 628)
+* BFD_RELOC_PPC64_GOT16_LO_DS: howto manager. (line 629)
+* BFD_RELOC_PPC64_HIGHER: howto manager. (line 614)
+* BFD_RELOC_PPC64_HIGHER_S: howto manager. (line 615)
+* BFD_RELOC_PPC64_HIGHEST: howto manager. (line 616)
+* BFD_RELOC_PPC64_HIGHEST_S: howto manager. (line 617)
+* BFD_RELOC_PPC64_PLT16_LO_DS: howto manager. (line 630)
+* BFD_RELOC_PPC64_PLTGOT16: howto manager. (line 622)
+* BFD_RELOC_PPC64_PLTGOT16_DS: howto manager. (line 635)
+* BFD_RELOC_PPC64_PLTGOT16_HA: howto manager. (line 625)
+* BFD_RELOC_PPC64_PLTGOT16_HI: howto manager. (line 624)
+* BFD_RELOC_PPC64_PLTGOT16_LO: howto manager. (line 623)
+* BFD_RELOC_PPC64_PLTGOT16_LO_DS: howto manager. (line 636)
+* BFD_RELOC_PPC64_SECTOFF_DS: howto manager. (line 631)
+* BFD_RELOC_PPC64_SECTOFF_LO_DS: howto manager. (line 632)
+* BFD_RELOC_PPC64_TOC: howto manager. (line 621)
+* BFD_RELOC_PPC64_TOC16_DS: howto manager. (line 633)
+* BFD_RELOC_PPC64_TOC16_HA: howto manager. (line 620)
+* BFD_RELOC_PPC64_TOC16_HI: howto manager. (line 619)
+* BFD_RELOC_PPC64_TOC16_LO: howto manager. (line 618)
+* BFD_RELOC_PPC64_TOC16_LO_DS: howto manager. (line 634)
+* BFD_RELOC_PPC64_TPREL16_DS: howto manager. (line 669)
+* BFD_RELOC_PPC64_TPREL16_HIGHER: howto manager. (line 671)
+* BFD_RELOC_PPC64_TPREL16_HIGHERA: howto manager. (line 672)
+* BFD_RELOC_PPC64_TPREL16_HIGHEST: howto manager. (line 673)
+* BFD_RELOC_PPC64_TPREL16_HIGHESTA: howto manager. (line 674)
+* BFD_RELOC_PPC64_TPREL16_LO_DS: howto manager. (line 670)
+* BFD_RELOC_PPC_B16: howto manager. (line 587)
+* BFD_RELOC_PPC_B16_BRNTAKEN: howto manager. (line 589)
+* BFD_RELOC_PPC_B16_BRTAKEN: howto manager. (line 588)
+* BFD_RELOC_PPC_B26: howto manager. (line 584)
+* BFD_RELOC_PPC_BA16: howto manager. (line 590)
+* BFD_RELOC_PPC_BA16_BRNTAKEN: howto manager. (line 592)
+* BFD_RELOC_PPC_BA16_BRTAKEN: howto manager. (line 591)
+* BFD_RELOC_PPC_BA26: howto manager. (line 585)
+* BFD_RELOC_PPC_COPY: howto manager. (line 593)
+* BFD_RELOC_PPC_DTPMOD: howto manager. (line 642)
+* BFD_RELOC_PPC_DTPREL: howto manager. (line 652)
+* BFD_RELOC_PPC_DTPREL16: howto manager. (line 648)
+* BFD_RELOC_PPC_DTPREL16_HA: howto manager. (line 651)
+* BFD_RELOC_PPC_DTPREL16_HI: howto manager. (line 650)
+* BFD_RELOC_PPC_DTPREL16_LO: howto manager. (line 649)
+* BFD_RELOC_PPC_EMB_BIT_FLD: howto manager. (line 612)
+* BFD_RELOC_PPC_EMB_MRKREF: howto manager. (line 607)
+* BFD_RELOC_PPC_EMB_NADDR16: howto manager. (line 599)
+* BFD_RELOC_PPC_EMB_NADDR16_HA: howto manager. (line 602)
+* BFD_RELOC_PPC_EMB_NADDR16_HI: howto manager. (line 601)
+* BFD_RELOC_PPC_EMB_NADDR16_LO: howto manager. (line 600)
+* BFD_RELOC_PPC_EMB_NADDR32: howto manager. (line 598)
+* BFD_RELOC_PPC_EMB_RELSDA: howto manager. (line 613)
+* BFD_RELOC_PPC_EMB_RELSEC16: howto manager. (line 608)
+* BFD_RELOC_PPC_EMB_RELST_HA: howto manager. (line 611)
+* BFD_RELOC_PPC_EMB_RELST_HI: howto manager. (line 610)
+* BFD_RELOC_PPC_EMB_RELST_LO: howto manager. (line 609)
+* BFD_RELOC_PPC_EMB_SDA21: howto manager. (line 606)
+* BFD_RELOC_PPC_EMB_SDA2I16: howto manager. (line 604)
+* BFD_RELOC_PPC_EMB_SDA2REL: howto manager. (line 605)
+* BFD_RELOC_PPC_EMB_SDAI16: howto manager. (line 603)
+* BFD_RELOC_PPC_GLOB_DAT: howto manager. (line 594)
+* BFD_RELOC_PPC_GOT_DTPREL16: howto manager. (line 665)
+* BFD_RELOC_PPC_GOT_DTPREL16_HA: howto manager. (line 668)
+* BFD_RELOC_PPC_GOT_DTPREL16_HI: howto manager. (line 667)
+* BFD_RELOC_PPC_GOT_DTPREL16_LO: howto manager. (line 666)
+* BFD_RELOC_PPC_GOT_TLSGD16: howto manager. (line 653)
+* BFD_RELOC_PPC_GOT_TLSGD16_HA: howto manager. (line 656)
+* BFD_RELOC_PPC_GOT_TLSGD16_HI: howto manager. (line 655)
+* BFD_RELOC_PPC_GOT_TLSGD16_LO: howto manager. (line 654)
+* BFD_RELOC_PPC_GOT_TLSLD16: howto manager. (line 657)
+* BFD_RELOC_PPC_GOT_TLSLD16_HA: howto manager. (line 660)
+* BFD_RELOC_PPC_GOT_TLSLD16_HI: howto manager. (line 659)
+* BFD_RELOC_PPC_GOT_TLSLD16_LO: howto manager. (line 658)
+* BFD_RELOC_PPC_GOT_TPREL16: howto manager. (line 661)
+* BFD_RELOC_PPC_GOT_TPREL16_HA: howto manager. (line 664)
+* BFD_RELOC_PPC_GOT_TPREL16_HI: howto manager. (line 663)
+* BFD_RELOC_PPC_GOT_TPREL16_LO: howto manager. (line 662)
+* BFD_RELOC_PPC_JMP_SLOT: howto manager. (line 595)
+* BFD_RELOC_PPC_LOCAL24PC: howto manager. (line 597)
+* BFD_RELOC_PPC_RELATIVE: howto manager. (line 596)
+* BFD_RELOC_PPC_TLS: howto manager. (line 639)
+* BFD_RELOC_PPC_TLSGD: howto manager. (line 640)
+* BFD_RELOC_PPC_TLSLD: howto manager. (line 641)
+* BFD_RELOC_PPC_TOC16: howto manager. (line 586)
+* BFD_RELOC_PPC_TPREL: howto manager. (line 647)
+* BFD_RELOC_PPC_TPREL16: howto manager. (line 643)
+* BFD_RELOC_PPC_TPREL16_HA: howto manager. (line 646)
+* BFD_RELOC_PPC_TPREL16_HI: howto manager. (line 645)
+* BFD_RELOC_PPC_TPREL16_LO: howto manager. (line 644)
+* BFD_RELOC_RELC: howto manager. (line 2017)
+* BFD_RELOC_RVA: howto manager. (line 100)
+* BFD_RELOC_SCORE16_BRANCH: howto manager. (line 1623)
+* BFD_RELOC_SCORE16_JMP: howto manager. (line 1620)
+* BFD_RELOC_SCORE_BCMP: howto manager. (line 1626)
+* BFD_RELOC_SCORE_BRANCH: howto manager. (line 1611)
+* BFD_RELOC_SCORE_CALL15: howto manager. (line 1631)
+* BFD_RELOC_SCORE_DUMMY2: howto manager. (line 1607)
+* BFD_RELOC_SCORE_DUMMY_HI16: howto manager. (line 1632)
+* BFD_RELOC_SCORE_GOT15: howto manager. (line 1629)
+* BFD_RELOC_SCORE_GOT_LO16: howto manager. (line 1630)
+* BFD_RELOC_SCORE_GPREL15: howto manager. (line 1604)
+* BFD_RELOC_SCORE_IMM30: howto manager. (line 1614)
+* BFD_RELOC_SCORE_IMM32: howto manager. (line 1617)
+* BFD_RELOC_SCORE_JMP: howto manager. (line 1608)
+* BFD_RELOC_SH_ALIGN: howto manager. (line 863)
+* BFD_RELOC_SH_CODE: howto manager. (line 864)
+* BFD_RELOC_SH_COPY: howto manager. (line 869)
+* BFD_RELOC_SH_COPY64: howto manager. (line 894)
+* BFD_RELOC_SH_COUNT: howto manager. (line 862)
+* BFD_RELOC_SH_DATA: howto manager. (line 865)
+* BFD_RELOC_SH_DISP12: howto manager. (line 845)
+* BFD_RELOC_SH_DISP12BY2: howto manager. (line 846)
+* BFD_RELOC_SH_DISP12BY4: howto manager. (line 847)
+* BFD_RELOC_SH_DISP12BY8: howto manager. (line 848)
+* BFD_RELOC_SH_DISP20: howto manager. (line 849)
+* BFD_RELOC_SH_DISP20BY8: howto manager. (line 850)
+* BFD_RELOC_SH_GLOB_DAT: howto manager. (line 870)
+* BFD_RELOC_SH_GLOB_DAT64: howto manager. (line 895)
+* BFD_RELOC_SH_GOT10BY4: howto manager. (line 898)
+* BFD_RELOC_SH_GOT10BY8: howto manager. (line 899)
+* BFD_RELOC_SH_GOT_HI16: howto manager. (line 877)
+* BFD_RELOC_SH_GOT_LOW16: howto manager. (line 874)
+* BFD_RELOC_SH_GOT_MEDHI16: howto manager. (line 876)
+* BFD_RELOC_SH_GOT_MEDLOW16: howto manager. (line 875)
+* BFD_RELOC_SH_GOTOFF_HI16: howto manager. (line 889)
+* BFD_RELOC_SH_GOTOFF_LOW16: howto manager. (line 886)
+* BFD_RELOC_SH_GOTOFF_MEDHI16: howto manager. (line 888)
+* BFD_RELOC_SH_GOTOFF_MEDLOW16: howto manager. (line 887)
+* BFD_RELOC_SH_GOTPC: howto manager. (line 873)
+* BFD_RELOC_SH_GOTPC_HI16: howto manager. (line 893)
+* BFD_RELOC_SH_GOTPC_LOW16: howto manager. (line 890)
+* BFD_RELOC_SH_GOTPC_MEDHI16: howto manager. (line 892)
+* BFD_RELOC_SH_GOTPC_MEDLOW16: howto manager. (line 891)
+* BFD_RELOC_SH_GOTPLT10BY4: howto manager. (line 900)
+* BFD_RELOC_SH_GOTPLT10BY8: howto manager. (line 901)
+* BFD_RELOC_SH_GOTPLT32: howto manager. (line 902)
+* BFD_RELOC_SH_GOTPLT_HI16: howto manager. (line 881)
+* BFD_RELOC_SH_GOTPLT_LOW16: howto manager. (line 878)
+* BFD_RELOC_SH_GOTPLT_MEDHI16: howto manager. (line 880)
+* BFD_RELOC_SH_GOTPLT_MEDLOW16: howto manager. (line 879)
+* BFD_RELOC_SH_IMM3: howto manager. (line 843)
+* BFD_RELOC_SH_IMM3U: howto manager. (line 844)
+* BFD_RELOC_SH_IMM4: howto manager. (line 851)
+* BFD_RELOC_SH_IMM4BY2: howto manager. (line 852)
+* BFD_RELOC_SH_IMM4BY4: howto manager. (line 853)
+* BFD_RELOC_SH_IMM8: howto manager. (line 854)
+* BFD_RELOC_SH_IMM8BY2: howto manager. (line 855)
+* BFD_RELOC_SH_IMM8BY4: howto manager. (line 856)
+* BFD_RELOC_SH_IMM_HI16: howto manager. (line 920)
+* BFD_RELOC_SH_IMM_HI16_PCREL: howto manager. (line 921)
+* BFD_RELOC_SH_IMM_LOW16: howto manager. (line 914)
+* BFD_RELOC_SH_IMM_LOW16_PCREL: howto manager. (line 915)
+* BFD_RELOC_SH_IMM_MEDHI16: howto manager. (line 918)
+* BFD_RELOC_SH_IMM_MEDHI16_PCREL: howto manager. (line 919)
+* BFD_RELOC_SH_IMM_MEDLOW16: howto manager. (line 916)
+* BFD_RELOC_SH_IMM_MEDLOW16_PCREL: howto manager. (line 917)
+* BFD_RELOC_SH_IMMS10: howto manager. (line 908)
+* BFD_RELOC_SH_IMMS10BY2: howto manager. (line 909)
+* BFD_RELOC_SH_IMMS10BY4: howto manager. (line 910)
+* BFD_RELOC_SH_IMMS10BY8: howto manager. (line 911)
+* BFD_RELOC_SH_IMMS16: howto manager. (line 912)
+* BFD_RELOC_SH_IMMS6: howto manager. (line 905)
+* BFD_RELOC_SH_IMMS6BY32: howto manager. (line 906)
+* BFD_RELOC_SH_IMMU16: howto manager. (line 913)
+* BFD_RELOC_SH_IMMU5: howto manager. (line 904)
+* BFD_RELOC_SH_IMMU6: howto manager. (line 907)
+* BFD_RELOC_SH_JMP_SLOT: howto manager. (line 871)
+* BFD_RELOC_SH_JMP_SLOT64: howto manager. (line 896)
+* BFD_RELOC_SH_LABEL: howto manager. (line 866)
+* BFD_RELOC_SH_LOOP_END: howto manager. (line 868)
+* BFD_RELOC_SH_LOOP_START: howto manager. (line 867)
+* BFD_RELOC_SH_PCDISP12BY2: howto manager. (line 842)
+* BFD_RELOC_SH_PCDISP8BY2: howto manager. (line 841)
+* BFD_RELOC_SH_PCRELIMM8BY2: howto manager. (line 857)
+* BFD_RELOC_SH_PCRELIMM8BY4: howto manager. (line 858)
+* BFD_RELOC_SH_PLT_HI16: howto manager. (line 885)
+* BFD_RELOC_SH_PLT_LOW16: howto manager. (line 882)
+* BFD_RELOC_SH_PLT_MEDHI16: howto manager. (line 884)
+* BFD_RELOC_SH_PLT_MEDLOW16: howto manager. (line 883)
+* BFD_RELOC_SH_PT_16: howto manager. (line 922)
+* BFD_RELOC_SH_RELATIVE: howto manager. (line 872)
+* BFD_RELOC_SH_RELATIVE64: howto manager. (line 897)
+* BFD_RELOC_SH_SHMEDIA_CODE: howto manager. (line 903)
+* BFD_RELOC_SH_SWITCH16: howto manager. (line 859)
+* BFD_RELOC_SH_SWITCH32: howto manager. (line 860)
+* BFD_RELOC_SH_TLS_DTPMOD32: howto manager. (line 928)
+* BFD_RELOC_SH_TLS_DTPOFF32: howto manager. (line 929)
+* BFD_RELOC_SH_TLS_GD_32: howto manager. (line 923)
+* BFD_RELOC_SH_TLS_IE_32: howto manager. (line 926)
+* BFD_RELOC_SH_TLS_LD_32: howto manager. (line 924)
+* BFD_RELOC_SH_TLS_LDO_32: howto manager. (line 925)
+* BFD_RELOC_SH_TLS_LE_32: howto manager. (line 927)
+* BFD_RELOC_SH_TLS_TPOFF32: howto manager. (line 930)
+* BFD_RELOC_SH_USES: howto manager. (line 861)
+* BFD_RELOC_SPARC13: howto manager. (line 134)
+* BFD_RELOC_SPARC22: howto manager. (line 133)
+* BFD_RELOC_SPARC_10: howto manager. (line 161)
+* BFD_RELOC_SPARC_11: howto manager. (line 162)
+* BFD_RELOC_SPARC_5: howto manager. (line 174)
+* BFD_RELOC_SPARC_6: howto manager. (line 173)
+* BFD_RELOC_SPARC_64: howto manager. (line 160)
+* BFD_RELOC_SPARC_7: howto manager. (line 172)
+* BFD_RELOC_SPARC_BASE13: howto manager. (line 156)
+* BFD_RELOC_SPARC_BASE22: howto manager. (line 157)
+* BFD_RELOC_SPARC_COPY: howto manager. (line 141)
+* BFD_RELOC_SPARC_DISP64: howto manager. (line 175)
+* BFD_RELOC_SPARC_GLOB_DAT: howto manager. (line 142)
+* BFD_RELOC_SPARC_GOT10: howto manager. (line 135)
+* BFD_RELOC_SPARC_GOT13: howto manager. (line 136)
+* BFD_RELOC_SPARC_GOT22: howto manager. (line 137)
+* BFD_RELOC_SPARC_GOTDATA_HIX22: howto manager. (line 148)
+* BFD_RELOC_SPARC_GOTDATA_LOX10: howto manager. (line 149)
+* BFD_RELOC_SPARC_GOTDATA_OP: howto manager. (line 152)
+* BFD_RELOC_SPARC_GOTDATA_OP_HIX22: howto manager. (line 150)
+* BFD_RELOC_SPARC_GOTDATA_OP_LOX10: howto manager. (line 151)
+* BFD_RELOC_SPARC_H44: howto manager. (line 180)
+* BFD_RELOC_SPARC_HH22: howto manager. (line 164)
+* BFD_RELOC_SPARC_HIX22: howto manager. (line 178)
+* BFD_RELOC_SPARC_HM10: howto manager. (line 165)
+* BFD_RELOC_SPARC_JMP_SLOT: howto manager. (line 143)
+* BFD_RELOC_SPARC_L44: howto manager. (line 182)
+* BFD_RELOC_SPARC_LM22: howto manager. (line 166)
+* BFD_RELOC_SPARC_LOX10: howto manager. (line 179)
+* BFD_RELOC_SPARC_M44: howto manager. (line 181)
+* BFD_RELOC_SPARC_OLO10: howto manager. (line 163)
+* BFD_RELOC_SPARC_PC10: howto manager. (line 138)
+* BFD_RELOC_SPARC_PC22: howto manager. (line 139)
+* BFD_RELOC_SPARC_PC_HH22: howto manager. (line 167)
+* BFD_RELOC_SPARC_PC_HM10: howto manager. (line 168)
+* BFD_RELOC_SPARC_PC_LM22: howto manager. (line 169)
+* BFD_RELOC_SPARC_PLT32: howto manager. (line 176)
+* BFD_RELOC_SPARC_PLT64: howto manager. (line 177)
+* BFD_RELOC_SPARC_REGISTER: howto manager. (line 183)
+* BFD_RELOC_SPARC_RELATIVE: howto manager. (line 144)
+* BFD_RELOC_SPARC_REV32: howto manager. (line 186)
+* BFD_RELOC_SPARC_TLS_DTPMOD32: howto manager. (line 207)
+* BFD_RELOC_SPARC_TLS_DTPMOD64: howto manager. (line 208)
+* BFD_RELOC_SPARC_TLS_DTPOFF32: howto manager. (line 209)
+* BFD_RELOC_SPARC_TLS_DTPOFF64: howto manager. (line 210)
+* BFD_RELOC_SPARC_TLS_GD_ADD: howto manager. (line 191)
+* BFD_RELOC_SPARC_TLS_GD_CALL: howto manager. (line 192)
+* BFD_RELOC_SPARC_TLS_GD_HI22: howto manager. (line 189)
+* BFD_RELOC_SPARC_TLS_GD_LO10: howto manager. (line 190)
+* BFD_RELOC_SPARC_TLS_IE_ADD: howto manager. (line 204)
+* BFD_RELOC_SPARC_TLS_IE_HI22: howto manager. (line 200)
+* BFD_RELOC_SPARC_TLS_IE_LD: howto manager. (line 202)
+* BFD_RELOC_SPARC_TLS_IE_LDX: howto manager. (line 203)
+* BFD_RELOC_SPARC_TLS_IE_LO10: howto manager. (line 201)
+* BFD_RELOC_SPARC_TLS_LDM_ADD: howto manager. (line 195)
+* BFD_RELOC_SPARC_TLS_LDM_CALL: howto manager. (line 196)
+* BFD_RELOC_SPARC_TLS_LDM_HI22: howto manager. (line 193)
+* BFD_RELOC_SPARC_TLS_LDM_LO10: howto manager. (line 194)
+* BFD_RELOC_SPARC_TLS_LDO_ADD: howto manager. (line 199)
+* BFD_RELOC_SPARC_TLS_LDO_HIX22: howto manager. (line 197)
+* BFD_RELOC_SPARC_TLS_LDO_LOX10: howto manager. (line 198)
+* BFD_RELOC_SPARC_TLS_LE_HIX22: howto manager. (line 205)
+* BFD_RELOC_SPARC_TLS_LE_LOX10: howto manager. (line 206)
+* BFD_RELOC_SPARC_TLS_TPOFF32: howto manager. (line 211)
+* BFD_RELOC_SPARC_TLS_TPOFF64: howto manager. (line 212)
+* BFD_RELOC_SPARC_UA16: howto manager. (line 145)
+* BFD_RELOC_SPARC_UA32: howto manager. (line 146)
+* BFD_RELOC_SPARC_UA64: howto manager. (line 147)
+* BFD_RELOC_SPARC_WDISP16: howto manager. (line 170)
+* BFD_RELOC_SPARC_WDISP19: howto manager. (line 171)
+* BFD_RELOC_SPARC_WDISP22: howto manager. (line 132)
+* BFD_RELOC_SPARC_WPLT30: howto manager. (line 140)
+* BFD_RELOC_SPU_ADD_PIC: howto manager. (line 229)
+* BFD_RELOC_SPU_HI16: howto manager. (line 226)
+* BFD_RELOC_SPU_IMM10: howto manager. (line 217)
+* BFD_RELOC_SPU_IMM10W: howto manager. (line 218)
+* BFD_RELOC_SPU_IMM16: howto manager. (line 219)
+* BFD_RELOC_SPU_IMM16W: howto manager. (line 220)
+* BFD_RELOC_SPU_IMM18: howto manager. (line 221)
+* BFD_RELOC_SPU_IMM7: howto manager. (line 215)
+* BFD_RELOC_SPU_IMM8: howto manager. (line 216)
+* BFD_RELOC_SPU_LO16: howto manager. (line 225)
+* BFD_RELOC_SPU_PCREL16: howto manager. (line 224)
+* BFD_RELOC_SPU_PCREL9a: howto manager. (line 222)
+* BFD_RELOC_SPU_PCREL9b: howto manager. (line 223)
+* BFD_RELOC_SPU_PPU32: howto manager. (line 227)
+* BFD_RELOC_SPU_PPU64: howto manager. (line 228)
+* BFD_RELOC_THUMB_PCREL_BLX: howto manager. (line 701)
+* BFD_RELOC_THUMB_PCREL_BRANCH12: howto manager. (line 715)
+* BFD_RELOC_THUMB_PCREL_BRANCH20: howto manager. (line 716)
+* BFD_RELOC_THUMB_PCREL_BRANCH23: howto manager. (line 717)
+* BFD_RELOC_THUMB_PCREL_BRANCH25: howto manager. (line 718)
+* BFD_RELOC_THUMB_PCREL_BRANCH7: howto manager. (line 713)
+* BFD_RELOC_THUMB_PCREL_BRANCH9: howto manager. (line 714)
+* BFD_RELOC_TIC30_LDP: howto manager. (line 1257)
+* BFD_RELOC_TIC54X_16_OF_23: howto manager. (line 1275)
+* BFD_RELOC_TIC54X_23: howto manager. (line 1272)
+* BFD_RELOC_TIC54X_MS7_OF_23: howto manager. (line 1280)
+* BFD_RELOC_TIC54X_PARTLS7: howto manager. (line 1262)
+* BFD_RELOC_TIC54X_PARTMS9: howto manager. (line 1267)
+* bfd_reloc_type_lookup: howto manager. (line 2234)
+* BFD_RELOC_V850_22_PCREL: howto manager. (line 1184)
+* BFD_RELOC_V850_9_PCREL: howto manager. (line 1181)
+* BFD_RELOC_V850_ALIGN: howto manager. (line 1242)
+* BFD_RELOC_V850_CALLT_16_16_OFFSET: howto manager. (line 1233)
+* BFD_RELOC_V850_CALLT_6_7_OFFSET: howto manager. (line 1230)
+* BFD_RELOC_V850_LO16_SPLIT_OFFSET: howto manager. (line 1245)
+* BFD_RELOC_V850_LONGCALL: howto manager. (line 1236)
+* BFD_RELOC_V850_LONGJUMP: howto manager. (line 1239)
+* BFD_RELOC_V850_SDA_15_16_OFFSET: howto manager. (line 1190)
+* BFD_RELOC_V850_SDA_16_16_OFFSET: howto manager. (line 1187)
+* BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET: howto manager. (line 1222)
+* BFD_RELOC_V850_TDA_16_16_OFFSET: howto manager. (line 1212)
+* BFD_RELOC_V850_TDA_4_4_OFFSET: howto manager. (line 1219)
+* BFD_RELOC_V850_TDA_4_5_OFFSET: howto manager. (line 1215)
+* BFD_RELOC_V850_TDA_6_8_OFFSET: howto manager. (line 1201)
+* BFD_RELOC_V850_TDA_7_7_OFFSET: howto manager. (line 1209)
+* BFD_RELOC_V850_TDA_7_8_OFFSET: howto manager. (line 1205)
+* BFD_RELOC_V850_ZDA_15_16_OFFSET: howto manager. (line 1197)
+* BFD_RELOC_V850_ZDA_16_16_OFFSET: howto manager. (line 1194)
+* BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET: howto manager. (line 1226)
+* BFD_RELOC_VAX_GLOB_DAT: howto manager. (line 2026)
+* BFD_RELOC_VAX_JMP_SLOT: howto manager. (line 2027)
+* BFD_RELOC_VAX_RELATIVE: howto manager. (line 2028)
+* BFD_RELOC_VPE4KMATH_DATA: howto manager. (line 1665)
+* BFD_RELOC_VPE4KMATH_INSN: howto manager. (line 1666)
+* BFD_RELOC_VTABLE_ENTRY: howto manager. (line 1670)
+* BFD_RELOC_VTABLE_INHERIT: howto manager. (line 1669)
+* BFD_RELOC_X86_64_32S: howto manager. (line 536)
+* BFD_RELOC_X86_64_COPY: howto manager. (line 531)
+* BFD_RELOC_X86_64_DTPMOD64: howto manager. (line 537)
+* BFD_RELOC_X86_64_DTPOFF32: howto manager. (line 542)
+* BFD_RELOC_X86_64_DTPOFF64: howto manager. (line 538)
+* BFD_RELOC_X86_64_GLOB_DAT: howto manager. (line 532)
+* BFD_RELOC_X86_64_GOT32: howto manager. (line 529)
+* BFD_RELOC_X86_64_GOT64: howto manager. (line 547)
+* BFD_RELOC_X86_64_GOTOFF64: howto manager. (line 545)
+* BFD_RELOC_X86_64_GOTPC32: howto manager. (line 546)
+* BFD_RELOC_X86_64_GOTPC32_TLSDESC: howto manager. (line 552)
+* BFD_RELOC_X86_64_GOTPC64: howto manager. (line 549)
+* BFD_RELOC_X86_64_GOTPCREL: howto manager. (line 535)
+* BFD_RELOC_X86_64_GOTPCREL64: howto manager. (line 548)
+* BFD_RELOC_X86_64_GOTPLT64: howto manager. (line 550)
+* BFD_RELOC_X86_64_GOTTPOFF: howto manager. (line 543)
+* BFD_RELOC_X86_64_IRELATIVE: howto manager. (line 555)
+* BFD_RELOC_X86_64_JUMP_SLOT: howto manager. (line 533)
+* BFD_RELOC_X86_64_PLT32: howto manager. (line 530)
+* BFD_RELOC_X86_64_PLTOFF64: howto manager. (line 551)
+* BFD_RELOC_X86_64_RELATIVE: howto manager. (line 534)
+* BFD_RELOC_X86_64_TLSDESC: howto manager. (line 554)
+* BFD_RELOC_X86_64_TLSDESC_CALL: howto manager. (line 553)
+* BFD_RELOC_X86_64_TLSGD: howto manager. (line 540)
+* BFD_RELOC_X86_64_TLSLD: howto manager. (line 541)
+* BFD_RELOC_X86_64_TPOFF32: howto manager. (line 544)
+* BFD_RELOC_X86_64_TPOFF64: howto manager. (line 539)
+* BFD_RELOC_XC16X_PAG: howto manager. (line 2020)
+* BFD_RELOC_XC16X_POF: howto manager. (line 2021)
+* BFD_RELOC_XC16X_SEG: howto manager. (line 2022)
+* BFD_RELOC_XC16X_SOF: howto manager. (line 2023)
+* BFD_RELOC_XSTORMY16_12: howto manager. (line 2012)
+* BFD_RELOC_XSTORMY16_24: howto manager. (line 2013)
+* BFD_RELOC_XSTORMY16_FPTR16: howto manager. (line 2014)
+* BFD_RELOC_XSTORMY16_REL_12: howto manager. (line 2011)
+* BFD_RELOC_XTENSA_ASM_EXPAND: howto manager. (line 2132)
+* BFD_RELOC_XTENSA_ASM_SIMPLIFY: howto manager. (line 2137)
+* BFD_RELOC_XTENSA_DIFF16: howto manager. (line 2079)
+* BFD_RELOC_XTENSA_DIFF32: howto manager. (line 2080)
+* BFD_RELOC_XTENSA_DIFF8: howto manager. (line 2078)
+* BFD_RELOC_XTENSA_GLOB_DAT: howto manager. (line 2068)
+* BFD_RELOC_XTENSA_JMP_SLOT: howto manager. (line 2069)
+* BFD_RELOC_XTENSA_OP0: howto manager. (line 2126)
+* BFD_RELOC_XTENSA_OP1: howto manager. (line 2127)
+* BFD_RELOC_XTENSA_OP2: howto manager. (line 2128)
+* BFD_RELOC_XTENSA_PLT: howto manager. (line 2073)
+* BFD_RELOC_XTENSA_RELATIVE: howto manager. (line 2070)
+* BFD_RELOC_XTENSA_RTLD: howto manager. (line 2063)
+* BFD_RELOC_XTENSA_SLOT0_ALT: howto manager. (line 2108)
+* BFD_RELOC_XTENSA_SLOT0_OP: howto manager. (line 2088)
+* BFD_RELOC_XTENSA_SLOT10_ALT: howto manager. (line 2118)
+* BFD_RELOC_XTENSA_SLOT10_OP: howto manager. (line 2098)
+* BFD_RELOC_XTENSA_SLOT11_ALT: howto manager. (line 2119)
+* BFD_RELOC_XTENSA_SLOT11_OP: howto manager. (line 2099)
+* BFD_RELOC_XTENSA_SLOT12_ALT: howto manager. (line 2120)
+* BFD_RELOC_XTENSA_SLOT12_OP: howto manager. (line 2100)
+* BFD_RELOC_XTENSA_SLOT13_ALT: howto manager. (line 2121)
+* BFD_RELOC_XTENSA_SLOT13_OP: howto manager. (line 2101)
+* BFD_RELOC_XTENSA_SLOT14_ALT: howto manager. (line 2122)
+* BFD_RELOC_XTENSA_SLOT14_OP: howto manager. (line 2102)
+* BFD_RELOC_XTENSA_SLOT1_ALT: howto manager. (line 2109)
+* BFD_RELOC_XTENSA_SLOT1_OP: howto manager. (line 2089)
+* BFD_RELOC_XTENSA_SLOT2_ALT: howto manager. (line 2110)
+* BFD_RELOC_XTENSA_SLOT2_OP: howto manager. (line 2090)
+* BFD_RELOC_XTENSA_SLOT3_ALT: howto manager. (line 2111)
+* BFD_RELOC_XTENSA_SLOT3_OP: howto manager. (line 2091)
+* BFD_RELOC_XTENSA_SLOT4_ALT: howto manager. (line 2112)
+* BFD_RELOC_XTENSA_SLOT4_OP: howto manager. (line 2092)
+* BFD_RELOC_XTENSA_SLOT5_ALT: howto manager. (line 2113)
+* BFD_RELOC_XTENSA_SLOT5_OP: howto manager. (line 2093)
+* BFD_RELOC_XTENSA_SLOT6_ALT: howto manager. (line 2114)
+* BFD_RELOC_XTENSA_SLOT6_OP: howto manager. (line 2094)
+* BFD_RELOC_XTENSA_SLOT7_ALT: howto manager. (line 2115)
+* BFD_RELOC_XTENSA_SLOT7_OP: howto manager. (line 2095)
+* BFD_RELOC_XTENSA_SLOT8_ALT: howto manager. (line 2116)
+* BFD_RELOC_XTENSA_SLOT8_OP: howto manager. (line 2096)
+* BFD_RELOC_XTENSA_SLOT9_ALT: howto manager. (line 2117)
+* BFD_RELOC_XTENSA_SLOT9_OP: howto manager. (line 2097)
+* BFD_RELOC_XTENSA_TLS_ARG: howto manager. (line 2147)
+* BFD_RELOC_XTENSA_TLS_CALL: howto manager. (line 2148)
+* BFD_RELOC_XTENSA_TLS_DTPOFF: howto manager. (line 2144)
+* BFD_RELOC_XTENSA_TLS_FUNC: howto manager. (line 2146)
+* BFD_RELOC_XTENSA_TLS_TPOFF: howto manager. (line 2145)
+* BFD_RELOC_XTENSA_TLSDESC_ARG: howto manager. (line 2143)
+* BFD_RELOC_XTENSA_TLSDESC_FN: howto manager. (line 2142)
+* BFD_RELOC_Z80_DISP8: howto manager. (line 2151)
+* BFD_RELOC_Z8K_CALLR: howto manager. (line 2157)
+* BFD_RELOC_Z8K_DISP7: howto manager. (line 2154)
+* BFD_RELOC_Z8K_IMM4L: howto manager. (line 2160)
+* bfd_scan_arch: Architectures. (line 433)
+* bfd_scan_vma: BFD front end. (line 513)
+* bfd_seach_for_target: bfd_target. (line 470)
+* bfd_section_already_linked: Writing the symbol table.
+ (line 55)
+* bfd_section_list_clear: section prototypes. (line 8)
+* bfd_sections_find_if: section prototypes. (line 176)
+* bfd_set_arch_info: Architectures. (line 474)
+* bfd_set_archive_head: Archives. (line 69)
+* bfd_set_default_target: bfd_target. (line 435)
+* bfd_set_error: BFD front end. (line 323)
+* bfd_set_error_handler: BFD front end. (line 365)
+* bfd_set_error_program_name: BFD front end. (line 374)
+* bfd_set_file_flags: BFD front end. (line 433)
+* bfd_set_format: Formats. (line 68)
+* bfd_set_gp_size: BFD front end. (line 503)
+* bfd_set_private_flags: BFD front end. (line 580)
+* bfd_set_reloc: BFD front end. (line 423)
+* bfd_set_section_contents: section prototypes. (line 207)
+* bfd_set_section_flags: section prototypes. (line 140)
+* bfd_set_section_size: section prototypes. (line 193)
+* bfd_set_start_address: BFD front end. (line 482)
+* bfd_set_symtab: symbol handling functions.
+ (line 60)
+* bfd_symbol_info: symbol handling functions.
+ (line 130)
+* bfd_target_list: bfd_target. (line 461)
+* bfd_write_bigendian_4byte_int: Internal. (line 13)
+* bfd_zalloc: Opening and Closing.
+ (line 228)
+* bfd_zalloc2: Opening and Closing.
+ (line 237)
+* coff_symbol_type: coff. (line 244)
+* core_file_matches_executable_p: Core Files. (line 30)
+* find_separate_debug_file: Opening and Closing.
+ (line 279)
+* generic_core_file_matches_executable_p: Core Files. (line 40)
+* get_debug_link_info: Opening and Closing.
+ (line 260)
+* Hash tables: Hash Tables. (line 6)
+* internal object-file format: Canonical format. (line 11)
+* Linker: Linker Functions. (line 6)
+* Other functions: BFD front end. (line 595)
+* separate_debug_file_exists: Opening and Closing.
+ (line 270)
+* struct bfd_iovec: BFD front end. (line 798)
+* target vector (_bfd_final_link): Performing the Final Link.
+ (line 6)
+* target vector (_bfd_link_add_symbols): Adding Symbols to the Hash Table.
+ (line 6)
+* target vector (_bfd_link_hash_table_create): Creating a Linker Hash Table.
+ (line 6)
+* The HOWTO Macro: typedef arelent. (line 291)
+* what is it?: Overview. (line 6)
+
+
+
+Tag Table:
+Node: Top1051
+Node: Overview1390
+Node: History2441
+Node: How It Works3387
+Node: What BFD Version 2 Can Do4930
+Node: BFD information loss6245
+Node: Canonical format8777
+Node: BFD front end13149
+Node: Memory Usage44457
+Node: Initialization45685
+Node: Sections46144
+Node: Section Input46627
+Node: Section Output47992
+Node: typedef asection50478
+Node: section prototypes75809
+Node: Symbols85489
+Node: Reading Symbols87084
+Node: Writing Symbols88191
+Node: Mini Symbols89900
+Node: typedef asymbol90874
+Node: symbol handling functions96933
+Node: Archives102275
+Node: Formats106001
+Node: Relocations108949
+Node: typedef arelent109676
+Node: howto manager125487
+Node: Core Files197788
+Node: Targets199605
+Node: bfd_target201575
+Node: Architectures222154
+Node: Opening and Closing245337
+Node: Internal256601
+Node: File Caching262934
+Node: Linker Functions264848
+Node: Creating a Linker Hash Table266521
+Node: Adding Symbols to the Hash Table268259
+Node: Differing file formats269159
+Node: Adding symbols from an object file270884
+Node: Adding symbols from an archive273035
+Node: Performing the Final Link275449
+Node: Information provided by the linker276691
+Node: Relocating the section contents277845
+Node: Writing the symbol table279596
+Node: Hash Tables283611
+Node: Creating and Freeing a Hash Table284809
+Node: Looking Up or Entering a String286059
+Node: Traversing a Hash Table287312
+Node: Deriving a New Hash Table Type288101
+Node: Define the Derived Structures289167
+Node: Write the Derived Creation Routine290248
+Node: Write Other Derived Routines292872
+Node: BFD back ends294187
+Node: What to Put Where294457
+Node: aout294637
+Node: coff300955
+Node: elf329388
+Node: mmo329789
+Node: File layout330717
+Node: Symbol-table336364
+Node: mmo section mapping340133
+Node: GNU Free Documentation License343785
+Node: BFD Index368868
+
+End Tag Table
diff --git a/bfd/doc/bfdio.texi b/bfd/doc/bfdio.texi
new file mode 100644
index 00000000000..9b4952fa956
--- /dev/null
+++ b/bfd/doc/bfdio.texi
@@ -0,0 +1,85 @@
+@findex struct bfd_iovec
+@subsubsection @code{struct bfd_iovec}
+@strong{Description}@*
+The @code{struct bfd_iovec} contains the internal file I/O class.
+Each @code{BFD} has an instance of this class and all file I/O is
+routed through it (it is assumed that the instance implements
+all methods listed below).
+@example
+struct bfd_iovec
+@{
+ /* To avoid problems with macros, a "b" rather than "f"
+ prefix is prepended to each method name. */
+ /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching
+ bytes starting at PTR. Return the number of bytes actually
+ transfered (a read past end-of-file returns less than NBYTES),
+ or -1 (setting @code{bfd_error}) if an error occurs. */
+ file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes);
+ file_ptr (*bwrite) (struct bfd *abfd, const void *ptr,
+ file_ptr nbytes);
+ /* Return the current IOSTREAM file offset, or -1 (setting @code{bfd_error}
+ if an error occurs. */
+ file_ptr (*btell) (struct bfd *abfd);
+ /* For the following, on successful completion a value of 0 is returned.
+ Otherwise, a value of -1 is returned (and @code{bfd_error} is set). */
+ int (*bseek) (struct bfd *abfd, file_ptr offset, int whence);
+ int (*bclose) (struct bfd *abfd);
+ int (*bflush) (struct bfd *abfd);
+ int (*bstat) (struct bfd *abfd, struct stat *sb);
+ /* Just like mmap: (void*)-1 on failure, mmapped address on success. */
+ void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len,
+ int prot, int flags, file_ptr offset);
+@};
+@end example
+
+@findex bfd_get_mtime
+@subsubsection @code{bfd_get_mtime}
+@strong{Synopsis}
+@example
+long bfd_get_mtime (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the file modification time (as read from the file system, or
+from the archive header for archive members).
+
+@findex bfd_get_size
+@subsubsection @code{bfd_get_size}
+@strong{Synopsis}
+@example
+file_ptr bfd_get_size (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the file size (as read from file system) for the file
+associated with BFD @var{abfd}.
+
+The initial motivation for, and use of, this routine is not
+so we can get the exact size of the object the BFD applies to, since
+that might not be generally possible (archive members for example).
+It would be ideal if someone could eventually modify
+it so that such results were guaranteed.
+
+Instead, we want to ask questions like "is this NNN byte sized
+object I'm about to try read from file offset YYY reasonable?"
+As as example of where we might do this, some object formats
+use string tables for which the first @code{sizeof (long)} bytes of the
+table contain the size of the table itself, including the size bytes.
+If an application tries to read what it thinks is one of these
+string tables, without some way to validate the size, and for
+some reason the size is wrong (byte swapping error, wrong location
+for the string table, etc.), the only clue is likely to be a read
+error when it tries to read the table, or a "virtual memory
+exhausted" error when it tries to allocate 15 bazillon bytes
+of space for the 15 bazillon byte table it is about to read.
+This function at least allows us to answer the question, "is the
+size reasonable?".
+
+@findex bfd_mmap
+@subsubsection @code{bfd_mmap}
+@strong{Synopsis}
+@example
+void *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len,
+ int prot, int flags, file_ptr offset);
+@end example
+@strong{Description}@*
+Return mmap()ed region of the file, if possible and implemented.
+
diff --git a/bfd/doc/bfdt.texi b/bfd/doc/bfdt.texi
new file mode 100644
index 00000000000..7468872c008
--- /dev/null
+++ b/bfd/doc/bfdt.texi
@@ -0,0 +1,871 @@
+@section @code{typedef bfd}
+A BFD has type @code{bfd}; objects of this type are the
+cornerstone of any application using BFD. Using BFD
+consists of making references though the BFD and to data in the BFD.
+
+Here is the structure that defines the type @code{bfd}. It
+contains the major data about the file and pointers
+to the rest of the data.
+
+
+@example
+
+enum bfd_direction
+ @{
+ no_direction = 0,
+ read_direction = 1,
+ write_direction = 2,
+ both_direction = 3
+ @};
+
+struct bfd
+@{
+ /* A unique identifier of the BFD */
+ unsigned int id;
+
+ /* The filename the application opened the BFD with. */
+ const char *filename;
+
+ /* A pointer to the target jump table. */
+ const struct bfd_target *xvec;
+
+ /* The IOSTREAM, and corresponding IO vector that provide access
+ to the file backing the BFD. */
+ void *iostream;
+ const struct bfd_iovec *iovec;
+
+ /* The caching routines use these to maintain a
+ least-recently-used list of BFDs. */
+ struct bfd *lru_prev, *lru_next;
+
+ /* When a file is closed by the caching routines, BFD retains
+ state information on the file here... */
+ ufile_ptr where;
+
+ /* File modified time, if mtime_set is TRUE. */
+ long mtime;
+
+ /* Reserved for an unimplemented file locking extension. */
+ int ifd;
+
+ /* The format which belongs to the BFD. (object, core, etc.) */
+ bfd_format format;
+
+ /* The direction with which the BFD was opened. */
+ enum bfd_direction direction;
+
+ /* Format_specific flags. */
+ flagword flags;
+
+ /* Values that may appear in the flags field of a BFD. These also
+ appear in the object_flags field of the bfd_target structure, where
+ they indicate the set of flags used by that backend (not all flags
+ are meaningful for all object file formats) (FIXME: at the moment,
+ the object_flags values have mostly just been copied from backend
+ to another, and are not necessarily correct). */
+
+#define BFD_NO_FLAGS 0x00
+
+ /* BFD contains relocation entries. */
+#define HAS_RELOC 0x01
+
+ /* BFD is directly executable. */
+#define EXEC_P 0x02
+
+ /* BFD has line number information (basically used for F_LNNO in a
+ COFF header). */
+#define HAS_LINENO 0x04
+
+ /* BFD has debugging information. */
+#define HAS_DEBUG 0x08
+
+ /* BFD has symbols. */
+#define HAS_SYMS 0x10
+
+ /* BFD has local symbols (basically used for F_LSYMS in a COFF
+ header). */
+#define HAS_LOCALS 0x20
+
+ /* BFD is a dynamic object. */
+#define DYNAMIC 0x40
+
+ /* Text section is write protected (if D_PAGED is not set, this is
+ like an a.out NMAGIC file) (the linker sets this by default, but
+ clears it for -r or -N). */
+#define WP_TEXT 0x80
+
+ /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the
+ linker sets this by default, but clears it for -r or -n or -N). */
+#define D_PAGED 0x100
+
+ /* BFD is relaxable (this means that bfd_relax_section may be able to
+ do something) (sometimes bfd_relax_section can do something even if
+ this is not set). */
+#define BFD_IS_RELAXABLE 0x200
+
+ /* This may be set before writing out a BFD to request using a
+ traditional format. For example, this is used to request that when
+ writing out an a.out object the symbols not be hashed to eliminate
+ duplicates. */
+#define BFD_TRADITIONAL_FORMAT 0x400
+
+ /* This flag indicates that the BFD contents are actually cached
+ in memory. If this is set, iostream points to a bfd_in_memory
+ struct. */
+#define BFD_IN_MEMORY 0x800
+
+ /* The sections in this BFD specify a memory page. */
+#define HAS_LOAD_PAGE 0x1000
+
+ /* This BFD has been created by the linker and doesn't correspond
+ to any input file. */
+#define BFD_LINKER_CREATED 0x2000
+
+ /* This may be set before writing out a BFD to request that it
+ be written using values for UIDs, GIDs, timestamps, etc. that
+ will be consistent from run to run. */
+#define BFD_DETERMINISTIC_OUTPUT 0x4000
+
+ /* Currently my_archive is tested before adding origin to
+ anything. I believe that this can become always an add of
+ origin, with origin set to 0 for non archive files. */
+ ufile_ptr origin;
+
+ /* The origin in the archive of the proxy entry. This will
+ normally be the same as origin, except for thin archives,
+ when it will contain the current offset of the proxy in the
+ thin archive rather than the offset of the bfd in its actual
+ container. */
+ ufile_ptr proxy_origin;
+
+ /* A hash table for section names. */
+ struct bfd_hash_table section_htab;
+
+ /* Pointer to linked list of sections. */
+ struct bfd_section *sections;
+
+ /* The last section on the section list. */
+ struct bfd_section *section_last;
+
+ /* The number of sections. */
+ unsigned int section_count;
+
+ /* Stuff only useful for object files:
+ The start address. */
+ bfd_vma start_address;
+
+ /* Used for input and output. */
+ unsigned int symcount;
+
+ /* Symbol table for output BFD (with symcount entries).
+ Also used by the linker to cache input BFD symbols. */
+ struct bfd_symbol **outsymbols;
+
+ /* Used for slurped dynamic symbol tables. */
+ unsigned int dynsymcount;
+
+ /* Pointer to structure which contains architecture information. */
+ const struct bfd_arch_info *arch_info;
+
+ /* Stuff only useful for archives. */
+ void *arelt_data;
+ struct bfd *my_archive; /* The containing archive BFD. */
+ struct bfd *archive_next; /* The next BFD in the archive. */
+ struct bfd *archive_head; /* The first BFD in the archive. */
+ struct bfd *nested_archives; /* List of nested archive in a flattened
+ thin archive. */
+
+ /* A chain of BFD structures involved in a link. */
+ struct bfd *link_next;
+
+ /* A field used by _bfd_generic_link_add_archive_symbols. This will
+ be used only for archive elements. */
+ int archive_pass;
+
+ /* Used by the back end to hold private data. */
+ union
+ @{
+ struct aout_data_struct *aout_data;
+ struct artdata *aout_ar_data;
+ struct _oasys_data *oasys_obj_data;
+ struct _oasys_ar_data *oasys_ar_data;
+ struct coff_tdata *coff_obj_data;
+ struct pe_tdata *pe_obj_data;
+ struct xcoff_tdata *xcoff_obj_data;
+ struct ecoff_tdata *ecoff_obj_data;
+ struct ieee_data_struct *ieee_data;
+ struct ieee_ar_data_struct *ieee_ar_data;
+ struct srec_data_struct *srec_data;
+ struct verilog_data_struct *verilog_data;
+ struct ihex_data_struct *ihex_data;
+ struct tekhex_data_struct *tekhex_data;
+ struct elf_obj_tdata *elf_obj_data;
+ struct nlm_obj_tdata *nlm_obj_data;
+ struct bout_data_struct *bout_data;
+ struct mmo_data_struct *mmo_data;
+ struct sun_core_struct *sun_core_data;
+ struct sco5_core_struct *sco5_core_data;
+ struct trad_core_struct *trad_core_data;
+ struct som_data_struct *som_data;
+ struct hpux_core_struct *hpux_core_data;
+ struct hppabsd_core_struct *hppabsd_core_data;
+ struct sgi_core_struct *sgi_core_data;
+ struct lynx_core_struct *lynx_core_data;
+ struct osf_core_struct *osf_core_data;
+ struct cisco_core_struct *cisco_core_data;
+ struct versados_data_struct *versados_data;
+ struct netbsd_core_struct *netbsd_core_data;
+ struct mach_o_data_struct *mach_o_data;
+ struct mach_o_fat_data_struct *mach_o_fat_data;
+ struct plugin_data_struct *plugin_data;
+ struct bfd_pef_data_struct *pef_data;
+ struct bfd_pef_xlib_data_struct *pef_xlib_data;
+ struct bfd_sym_data_struct *sym_data;
+ void *any;
+ @}
+ tdata;
+
+ /* Used by the application to hold private data. */
+ void *usrdata;
+
+ /* Where all the allocated stuff under this BFD goes. This is a
+ struct objalloc *, but we use void * to avoid requiring the inclusion
+ of objalloc.h. */
+ void *memory;
+
+ /* Is the file descriptor being cached? That is, can it be closed as
+ needed, and re-opened when accessed later? */
+ unsigned int cacheable : 1;
+
+ /* Marks whether there was a default target specified when the
+ BFD was opened. This is used to select which matching algorithm
+ to use to choose the back end. */
+ unsigned int target_defaulted : 1;
+
+ /* ... and here: (``once'' means at least once). */
+ unsigned int opened_once : 1;
+
+ /* Set if we have a locally maintained mtime value, rather than
+ getting it from the file each time. */
+ unsigned int mtime_set : 1;
+
+ /* Flag set if symbols from this BFD should not be exported. */
+ unsigned int no_export : 1;
+
+ /* Remember when output has begun, to stop strange things
+ from happening. */
+ unsigned int output_has_begun : 1;
+
+ /* Have archive map. */
+ unsigned int has_armap : 1;
+
+ /* Set if this is a thin archive. */
+ unsigned int is_thin_archive : 1;
+@};
+
+@end example
+@section Error reporting
+Most BFD functions return nonzero on success (check their
+individual documentation for precise semantics). On an error,
+they call @code{bfd_set_error} to set an error condition that callers
+can check by calling @code{bfd_get_error}.
+If that returns @code{bfd_error_system_call}, then check
+@code{errno}.
+
+The easiest way to report a BFD error to the user is to
+use @code{bfd_perror}.
+
+@subsection Type @code{bfd_error_type}
+The values returned by @code{bfd_get_error} are defined by the
+enumerated type @code{bfd_error_type}.
+
+
+@example
+
+typedef enum bfd_error
+@{
+ bfd_error_no_error = 0,
+ bfd_error_system_call,
+ bfd_error_invalid_target,
+ bfd_error_wrong_format,
+ bfd_error_wrong_object_format,
+ bfd_error_invalid_operation,
+ bfd_error_no_memory,
+ bfd_error_no_symbols,
+ bfd_error_no_armap,
+ bfd_error_no_more_archived_files,
+ bfd_error_malformed_archive,
+ bfd_error_file_not_recognized,
+ bfd_error_file_ambiguously_recognized,
+ bfd_error_no_contents,
+ bfd_error_nonrepresentable_section,
+ bfd_error_no_debug_section,
+ bfd_error_bad_value,
+ bfd_error_file_truncated,
+ bfd_error_file_too_big,
+ bfd_error_on_input,
+ bfd_error_invalid_error_code
+@}
+bfd_error_type;
+
+@end example
+@findex bfd_get_error
+@subsubsection @code{bfd_get_error}
+@strong{Synopsis}
+@example
+bfd_error_type bfd_get_error (void);
+@end example
+@strong{Description}@*
+Return the current BFD error condition.
+
+@findex bfd_set_error
+@subsubsection @code{bfd_set_error}
+@strong{Synopsis}
+@example
+void bfd_set_error (bfd_error_type error_tag, ...);
+@end example
+@strong{Description}@*
+Set the BFD error condition to be @var{error_tag}.
+If @var{error_tag} is bfd_error_on_input, then this function
+takes two more parameters, the input bfd where the error
+occurred, and the bfd_error_type error.
+
+@findex bfd_errmsg
+@subsubsection @code{bfd_errmsg}
+@strong{Synopsis}
+@example
+const char *bfd_errmsg (bfd_error_type error_tag);
+@end example
+@strong{Description}@*
+Return a string describing the error @var{error_tag}, or
+the system error if @var{error_tag} is @code{bfd_error_system_call}.
+
+@findex bfd_perror
+@subsubsection @code{bfd_perror}
+@strong{Synopsis}
+@example
+void bfd_perror (const char *message);
+@end example
+@strong{Description}@*
+Print to the standard error stream a string describing the
+last BFD error that occurred, or the last system error if
+the last BFD error was a system call failure. If @var{message}
+is non-NULL and non-empty, the error string printed is preceded
+by @var{message}, a colon, and a space. It is followed by a newline.
+
+@subsection BFD error handler
+Some BFD functions want to print messages describing the
+problem. They call a BFD error handler function. This
+function may be overridden by the program.
+
+The BFD error handler acts like printf.
+
+
+@example
+
+typedef void (*bfd_error_handler_type) (const char *, ...);
+
+@end example
+@findex bfd_set_error_handler
+@subsubsection @code{bfd_set_error_handler}
+@strong{Synopsis}
+@example
+bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
+@end example
+@strong{Description}@*
+Set the BFD error handler function. Returns the previous
+function.
+
+@findex bfd_set_error_program_name
+@subsubsection @code{bfd_set_error_program_name}
+@strong{Synopsis}
+@example
+void bfd_set_error_program_name (const char *);
+@end example
+@strong{Description}@*
+Set the program name to use when printing a BFD error. This
+is printed before the error message followed by a colon and
+space. The string must not be changed after it is passed to
+this function.
+
+@findex bfd_get_error_handler
+@subsubsection @code{bfd_get_error_handler}
+@strong{Synopsis}
+@example
+bfd_error_handler_type bfd_get_error_handler (void);
+@end example
+@strong{Description}@*
+Return the BFD error handler function.
+
+@section Miscellaneous
+
+
+@subsection Miscellaneous functions
+
+
+@findex bfd_get_reloc_upper_bound
+@subsubsection @code{bfd_get_reloc_upper_bound}
+@strong{Synopsis}
+@example
+long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
+@end example
+@strong{Description}@*
+Return the number of bytes required to store the
+relocation information associated with section @var{sect}
+attached to bfd @var{abfd}. If an error occurs, return -1.
+
+@findex bfd_canonicalize_reloc
+@subsubsection @code{bfd_canonicalize_reloc}
+@strong{Synopsis}
+@example
+long bfd_canonicalize_reloc
+ (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
+@end example
+@strong{Description}@*
+Call the back end associated with the open BFD
+@var{abfd} and translate the external form of the relocation
+information attached to @var{sec} into the internal canonical
+form. Place the table into memory at @var{loc}, which has
+been preallocated, usually by a call to
+@code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or
+-1 on error.
+
+The @var{syms} table is also needed for horrible internal magic
+reasons.
+
+@findex bfd_set_reloc
+@subsubsection @code{bfd_set_reloc}
+@strong{Synopsis}
+@example
+void bfd_set_reloc
+ (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
+@end example
+@strong{Description}@*
+Set the relocation pointer and count within
+section @var{sec} to the values @var{rel} and @var{count}.
+The argument @var{abfd} is ignored.
+
+@findex bfd_set_file_flags
+@subsubsection @code{bfd_set_file_flags}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
+@end example
+@strong{Description}@*
+Set the flag word in the BFD @var{abfd} to the value @var{flags}.
+
+Possible errors are:
+@itemize @bullet
+
+@item
+@code{bfd_error_wrong_format} - The target bfd was not of object format.
+@item
+@code{bfd_error_invalid_operation} - The target bfd was open for reading.
+@item
+@code{bfd_error_invalid_operation} -
+The flag word contained a bit which was not applicable to the
+type of file. E.g., an attempt was made to set the @code{D_PAGED} bit
+on a BFD format which does not support demand paging.
+@end itemize
+
+@findex bfd_get_arch_size
+@subsubsection @code{bfd_get_arch_size}
+@strong{Synopsis}
+@example
+int bfd_get_arch_size (bfd *abfd);
+@end example
+@strong{Description}@*
+Returns the architecture address size, in bits, as determined
+by the object file's format. For ELF, this information is
+included in the header.
+
+@strong{Returns}@*
+Returns the arch size in bits if known, @code{-1} otherwise.
+
+@findex bfd_get_sign_extend_vma
+@subsubsection @code{bfd_get_sign_extend_vma}
+@strong{Synopsis}
+@example
+int bfd_get_sign_extend_vma (bfd *abfd);
+@end example
+@strong{Description}@*
+Indicates if the target architecture "naturally" sign extends
+an address. Some architectures implicitly sign extend address
+values when they are converted to types larger than the size
+of an address. For instance, bfd_get_start_address() will
+return an address sign extended to fill a bfd_vma when this is
+the case.
+
+@strong{Returns}@*
+Returns @code{1} if the target architecture is known to sign
+extend addresses, @code{0} if the target architecture is known to
+not sign extend addresses, and @code{-1} otherwise.
+
+@findex bfd_set_start_address
+@subsubsection @code{bfd_set_start_address}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
+@end example
+@strong{Description}@*
+Make @var{vma} the entry point of output BFD @var{abfd}.
+
+@strong{Returns}@*
+Returns @code{TRUE} on success, @code{FALSE} otherwise.
+
+@findex bfd_get_gp_size
+@subsubsection @code{bfd_get_gp_size}
+@strong{Synopsis}
+@example
+unsigned int bfd_get_gp_size (bfd *abfd);
+@end example
+@strong{Description}@*
+Return the maximum size of objects to be optimized using the GP
+register under MIPS ECOFF. This is typically set by the @code{-G}
+argument to the compiler, assembler or linker.
+
+@findex bfd_set_gp_size
+@subsubsection @code{bfd_set_gp_size}
+@strong{Synopsis}
+@example
+void bfd_set_gp_size (bfd *abfd, unsigned int i);
+@end example
+@strong{Description}@*
+Set the maximum size of objects to be optimized using the GP
+register under ECOFF or MIPS ELF. This is typically set by
+the @code{-G} argument to the compiler, assembler or linker.
+
+@findex bfd_scan_vma
+@subsubsection @code{bfd_scan_vma}
+@strong{Synopsis}
+@example
+bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
+@end example
+@strong{Description}@*
+Convert, like @code{strtoul}, a numerical expression
+@var{string} into a @code{bfd_vma} integer, and return that integer.
+(Though without as many bells and whistles as @code{strtoul}.)
+The expression is assumed to be unsigned (i.e., positive).
+If given a @var{base}, it is used as the base for conversion.
+A base of 0 causes the function to interpret the string
+in hex if a leading "0x" or "0X" is found, otherwise
+in octal if a leading zero is found, otherwise in decimal.
+
+If the value would overflow, the maximum @code{bfd_vma} value is
+returned.
+
+@findex bfd_copy_private_header_data
+@subsubsection @code{bfd_copy_private_header_data}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
+@end example
+@strong{Description}@*
+Copy private BFD header information from the BFD @var{ibfd} to the
+the BFD @var{obfd}. This copies information that may require
+sections to exist, but does not require symbol tables. Return
+@code{true} on success, @code{false} on error.
+Possible error returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_no_memory} -
+Not enough memory exists to create private data for @var{obfd}.
+@end itemize
+@example
+#define bfd_copy_private_header_data(ibfd, obfd) \
+ BFD_SEND (obfd, _bfd_copy_private_header_data, \
+ (ibfd, obfd))
+@end example
+
+@findex bfd_copy_private_bfd_data
+@subsubsection @code{bfd_copy_private_bfd_data}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
+@end example
+@strong{Description}@*
+Copy private BFD information from the BFD @var{ibfd} to the
+the BFD @var{obfd}. Return @code{TRUE} on success, @code{FALSE} on error.
+Possible error returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_no_memory} -
+Not enough memory exists to create private data for @var{obfd}.
+@end itemize
+@example
+#define bfd_copy_private_bfd_data(ibfd, obfd) \
+ BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
+ (ibfd, obfd))
+@end example
+
+@findex bfd_merge_private_bfd_data
+@subsubsection @code{bfd_merge_private_bfd_data}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
+@end example
+@strong{Description}@*
+Merge private BFD information from the BFD @var{ibfd} to the
+the output file BFD @var{obfd} when linking. Return @code{TRUE}
+on success, @code{FALSE} on error. Possible error returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_no_memory} -
+Not enough memory exists to create private data for @var{obfd}.
+@end itemize
+@example
+#define bfd_merge_private_bfd_data(ibfd, obfd) \
+ BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
+ (ibfd, obfd))
+@end example
+
+@findex bfd_set_private_flags
+@subsubsection @code{bfd_set_private_flags}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
+@end example
+@strong{Description}@*
+Set private BFD flag information in the BFD @var{abfd}.
+Return @code{TRUE} on success, @code{FALSE} on error. Possible error
+returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_no_memory} -
+Not enough memory exists to create private data for @var{obfd}.
+@end itemize
+@example
+#define bfd_set_private_flags(abfd, flags) \
+ BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
+@end example
+
+@findex Other functions
+@subsubsection @code{Other functions}
+@strong{Description}@*
+The following functions exist but have not yet been documented.
+@example
+#define bfd_sizeof_headers(abfd, info) \
+ BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info))
+
+#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
+ BFD_SEND (abfd, _bfd_find_nearest_line, \
+ (abfd, sec, syms, off, file, func, line))
+
+#define bfd_find_line(abfd, syms, sym, file, line) \
+ BFD_SEND (abfd, _bfd_find_line, \
+ (abfd, syms, sym, file, line))
+
+#define bfd_find_inliner_info(abfd, file, func, line) \
+ BFD_SEND (abfd, _bfd_find_inliner_info, \
+ (abfd, file, func, line))
+
+#define bfd_debug_info_start(abfd) \
+ BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
+
+#define bfd_debug_info_end(abfd) \
+ BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
+
+#define bfd_debug_info_accumulate(abfd, section) \
+ BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
+
+#define bfd_stat_arch_elt(abfd, stat) \
+ BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
+
+#define bfd_update_armap_timestamp(abfd) \
+ BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
+
+#define bfd_set_arch_mach(abfd, arch, mach)\
+ BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
+
+#define bfd_relax_section(abfd, section, link_info, again) \
+ BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
+
+#define bfd_gc_sections(abfd, link_info) \
+ BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
+
+#define bfd_merge_sections(abfd, link_info) \
+ BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
+
+#define bfd_is_group_section(abfd, sec) \
+ BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
+
+#define bfd_discard_group(abfd, sec) \
+ BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
+
+#define bfd_link_hash_table_create(abfd) \
+ BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
+
+#define bfd_link_hash_table_free(abfd, hash) \
+ BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
+
+#define bfd_link_add_symbols(abfd, info) \
+ BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
+
+#define bfd_link_just_syms(abfd, sec, info) \
+ BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
+
+#define bfd_final_link(abfd, info) \
+ BFD_SEND (abfd, _bfd_final_link, (abfd, info))
+
+#define bfd_free_cached_info(abfd) \
+ BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
+
+#define bfd_get_dynamic_symtab_upper_bound(abfd) \
+ BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
+
+#define bfd_print_private_bfd_data(abfd, file)\
+ BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
+
+#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
+ BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
+
+#define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
+ BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
+ dyncount, dynsyms, ret))
+
+#define bfd_get_dynamic_reloc_upper_bound(abfd) \
+ BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
+
+#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
+ BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
+
+extern bfd_byte *bfd_get_relocated_section_contents
+ (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
+ bfd_boolean, asymbol **);
+
+@end example
+
+@findex bfd_alt_mach_code
+@subsubsection @code{bfd_alt_mach_code}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
+@end example
+@strong{Description}@*
+When more than one machine code number is available for the
+same machine type, this function can be used to switch between
+the preferred one (alternative == 0) and any others. Currently,
+only ELF supports this feature, with up to two alternate
+machine codes.
+
+
+@example
+struct bfd_preserve
+@{
+ void *marker;
+ void *tdata;
+ flagword flags;
+ const struct bfd_arch_info *arch_info;
+ struct bfd_section *sections;
+ struct bfd_section *section_last;
+ unsigned int section_count;
+ struct bfd_hash_table section_htab;
+@};
+
+@end example
+@findex bfd_preserve_save
+@subsubsection @code{bfd_preserve_save}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
+@end example
+@strong{Description}@*
+When testing an object for compatibility with a particular
+target back-end, the back-end object_p function needs to set
+up certain fields in the bfd on successfully recognizing the
+object. This typically happens in a piecemeal fashion, with
+failures possible at many points. On failure, the bfd is
+supposed to be restored to its initial state, which is
+virtually impossible. However, restoring a subset of the bfd
+state works in practice. This function stores the subset and
+reinitializes the bfd.
+
+@findex bfd_preserve_restore
+@subsubsection @code{bfd_preserve_restore}
+@strong{Synopsis}
+@example
+void bfd_preserve_restore (bfd *, struct bfd_preserve *);
+@end example
+@strong{Description}@*
+This function restores bfd state saved by bfd_preserve_save.
+If MARKER is non-NULL in struct bfd_preserve then that block
+and all subsequently bfd_alloc'd memory is freed.
+
+@findex bfd_preserve_finish
+@subsubsection @code{bfd_preserve_finish}
+@strong{Synopsis}
+@example
+void bfd_preserve_finish (bfd *, struct bfd_preserve *);
+@end example
+@strong{Description}@*
+This function should be called when the bfd state saved by
+bfd_preserve_save is no longer needed. ie. when the back-end
+object_p function returns with success.
+
+@findex bfd_emul_get_maxpagesize
+@subsubsection @code{bfd_emul_get_maxpagesize}
+@strong{Synopsis}
+@example
+bfd_vma bfd_emul_get_maxpagesize (const char *);
+@end example
+@strong{Description}@*
+Returns the maximum page size, in bytes, as determined by
+emulation.
+
+@strong{Returns}@*
+Returns the maximum page size in bytes for ELF, 0 otherwise.
+
+@findex bfd_emul_set_maxpagesize
+@subsubsection @code{bfd_emul_set_maxpagesize}
+@strong{Synopsis}
+@example
+void bfd_emul_set_maxpagesize (const char *, bfd_vma);
+@end example
+@strong{Description}@*
+For ELF, set the maximum page size for the emulation. It is
+a no-op for other formats.
+
+@findex bfd_emul_get_commonpagesize
+@subsubsection @code{bfd_emul_get_commonpagesize}
+@strong{Synopsis}
+@example
+bfd_vma bfd_emul_get_commonpagesize (const char *);
+@end example
+@strong{Description}@*
+Returns the common page size, in bytes, as determined by
+emulation.
+
+@strong{Returns}@*
+Returns the common page size in bytes for ELF, 0 otherwise.
+
+@findex bfd_emul_set_commonpagesize
+@subsubsection @code{bfd_emul_set_commonpagesize}
+@strong{Synopsis}
+@example
+void bfd_emul_set_commonpagesize (const char *, bfd_vma);
+@end example
+@strong{Description}@*
+For ELF, set the common page size for the emulation. It is
+a no-op for other formats.
+
+@findex bfd_demangle
+@subsubsection @code{bfd_demangle}
+@strong{Synopsis}
+@example
+char *bfd_demangle (bfd *, const char *, int);
+@end example
+@strong{Description}@*
+Wrapper around cplus_demangle. Strips leading underscores and
+other such chars that would otherwise confuse the demangler.
+If passed a g++ v3 ABI mangled name, returns a buffer allocated
+with malloc holding the demangled name. Returns NULL otherwise
+and on memory alloc failure.
+
diff --git a/bfd/doc/bfdver.texi b/bfd/doc/bfdver.texi
new file mode 100644
index 00000000000..6ae2b4333be
--- /dev/null
+++ b/bfd/doc/bfdver.texi
@@ -0,0 +1,4 @@
+@set VERSION 2.20
+@set VERSION_PACKAGE (GNU Binutils)
+@set UPDATED October 2009
+@set BUGURL @uref{http://www.sourceware.org/bugzilla/}
diff --git a/bfd/doc/bfdwin.texi b/bfd/doc/bfdwin.texi
new file mode 100644
index 00000000000..b1fd7d5bed6
--- /dev/null
+++ b/bfd/doc/bfdwin.texi
@@ -0,0 +1,2 @@
+@findex
+@subsubsection @code{}
diff --git a/bfd/doc/cache.texi b/bfd/doc/cache.texi
new file mode 100644
index 00000000000..5820a2a6a1d
--- /dev/null
+++ b/bfd/doc/cache.texi
@@ -0,0 +1,65 @@
+@section File caching
+The file caching mechanism is embedded within BFD and allows
+the application to open as many BFDs as it wants without
+regard to the underlying operating system's file descriptor
+limit (often as low as 20 open files). The module in
+@code{cache.c} maintains a least recently used list of
+@code{BFD_CACHE_MAX_OPEN} files, and exports the name
+@code{bfd_cache_lookup}, which runs around and makes sure that
+the required BFD is open. If not, then it chooses a file to
+close, closes it and opens the one wanted, returning its file
+handle.
+
+@subsection Caching functions
+
+
+@findex bfd_cache_init
+@subsubsection @code{bfd_cache_init}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_cache_init (bfd *abfd);
+@end example
+@strong{Description}@*
+Add a newly opened BFD to the cache.
+
+@findex bfd_cache_close
+@subsubsection @code{bfd_cache_close}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_cache_close (bfd *abfd);
+@end example
+@strong{Description}@*
+Remove the BFD @var{abfd} from the cache. If the attached file is open,
+then close it too.
+
+@strong{Returns}@*
+@code{FALSE} is returned if closing the file fails, @code{TRUE} is
+returned if all is well.
+
+@findex bfd_cache_close_all
+@subsubsection @code{bfd_cache_close_all}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_cache_close_all (void);
+@end example
+@strong{Description}@*
+Remove all BFDs from the cache. If the attached file is open,
+then close it too.
+
+@strong{Returns}@*
+@code{FALSE} is returned if closing one of the file fails, @code{TRUE} is
+returned if all is well.
+
+@findex bfd_open_file
+@subsubsection @code{bfd_open_file}
+@strong{Synopsis}
+@example
+FILE* bfd_open_file (bfd *abfd);
+@end example
+@strong{Description}@*
+Call the OS to open a file for @var{abfd}. Return the @code{FILE *}
+(possibly @code{NULL}) that results from this operation. Set up the
+BFD so that future accesses know the file is open. If the @code{FILE *}
+returned is @code{NULL}, then it won't have been put in the
+cache, so it won't have to be removed from it.
+
diff --git a/bfd/doc/coffcode.texi b/bfd/doc/coffcode.texi
new file mode 100644
index 00000000000..e487d84701e
--- /dev/null
+++ b/bfd/doc/coffcode.texi
@@ -0,0 +1,685 @@
+@section coff backends
+BFD supports a number of different flavours of coff format.
+The major differences between formats are the sizes and
+alignments of fields in structures on disk, and the occasional
+extra field.
+
+Coff in all its varieties is implemented with a few common
+files and a number of implementation specific files. For
+example, The 88k bcs coff format is implemented in the file
+@file{coff-m88k.c}. This file @code{#include}s
+@file{coff/m88k.h} which defines the external structure of the
+coff format for the 88k, and @file{coff/internal.h} which
+defines the internal structure. @file{coff-m88k.c} also
+defines the relocations used by the 88k format
+@xref{Relocations}.
+
+The Intel i960 processor version of coff is implemented in
+@file{coff-i960.c}. This file has the same structure as
+@file{coff-m88k.c}, except that it includes @file{coff/i960.h}
+rather than @file{coff-m88k.h}.
+
+@subsection Porting to a new version of coff
+The recommended method is to select from the existing
+implementations the version of coff which is most like the one
+you want to use. For example, we'll say that i386 coff is
+the one you select, and that your coff flavour is called foo.
+Copy @file{i386coff.c} to @file{foocoff.c}, copy
+@file{../include/coff/i386.h} to @file{../include/coff/foo.h},
+and add the lines to @file{targets.c} and @file{Makefile.in}
+so that your new back end is used. Alter the shapes of the
+structures in @file{../include/coff/foo.h} so that they match
+what you need. You will probably also have to add
+@code{#ifdef}s to the code in @file{coff/internal.h} and
+@file{coffcode.h} if your version of coff is too wild.
+
+You can verify that your new BFD backend works quite simply by
+building @file{objdump} from the @file{binutils} directory,
+and making sure that its version of what's going on and your
+host system's idea (assuming it has the pretty standard coff
+dump utility, usually called @code{att-dump} or just
+@code{dump}) are the same. Then clean up your code, and send
+what you've done to Cygnus. Then your stuff will be in the
+next release, and you won't have to keep integrating it.
+
+@subsection How the coff backend works
+
+
+@subsubsection File layout
+The Coff backend is split into generic routines that are
+applicable to any Coff target and routines that are specific
+to a particular target. The target-specific routines are
+further split into ones which are basically the same for all
+Coff targets except that they use the external symbol format
+or use different values for certain constants.
+
+The generic routines are in @file{coffgen.c}. These routines
+work for any Coff target. They use some hooks into the target
+specific code; the hooks are in a @code{bfd_coff_backend_data}
+structure, one of which exists for each target.
+
+The essentially similar target-specific routines are in
+@file{coffcode.h}. This header file includes executable C code.
+The various Coff targets first include the appropriate Coff
+header file, make any special defines that are needed, and
+then include @file{coffcode.h}.
+
+Some of the Coff targets then also have additional routines in
+the target source file itself.
+
+For example, @file{coff-i960.c} includes
+@file{coff/internal.h} and @file{coff/i960.h}. It then
+defines a few constants, such as @code{I960}, and includes
+@file{coffcode.h}. Since the i960 has complex relocation
+types, @file{coff-i960.c} also includes some code to
+manipulate the i960 relocs. This code is not in
+@file{coffcode.h} because it would not be used by any other
+target.
+
+@subsubsection Coff long section names
+In the standard Coff object format, section names are limited to
+the eight bytes available in the @code{s_name} field of the
+@code{SCNHDR} section header structure. The format requires the
+field to be NUL-padded, but not necessarily NUL-terminated, so
+the longest section names permitted are a full eight characters.
+
+The Microsoft PE variants of the Coff object file format add
+an extension to support the use of long section names. This
+extension is defined in section 4 of the Microsoft PE/COFF
+specification (rev 8.1). If a section name is too long to fit
+into the section header's @code{s_name} field, it is instead
+placed into the string table, and the @code{s_name} field is
+filled with a slash ("/") followed by the ASCII decimal
+representation of the offset of the full name relative to the
+string table base.
+
+Note that this implies that the extension can only be used in object
+files, as executables do not contain a string table. The standard
+specifies that long section names from objects emitted into executable
+images are to be truncated.
+
+However, as a GNU extension, BFD can generate executable images
+that contain a string table and long section names. This
+would appear to be technically valid, as the standard only says
+that Coff debugging information is deprecated, not forbidden,
+and in practice it works, although some tools that parse PE files
+expecting the MS standard format may become confused; @file{PEview} is
+one known example.
+
+The functionality is supported in BFD by code implemented under
+the control of the macro @code{COFF_LONG_SECTION_NAMES}. If not
+defined, the format does not support long section names in any way.
+If defined, it is used to initialise a flag,
+@code{_bfd_coff_long_section_names}, and a hook function pointer,
+@code{_bfd_coff_set_long_section_names}, in the Coff backend data
+structure. The flag controls the generation of long section names
+in output BFDs at runtime; if it is false, as it will be by default
+when generating an executable image, long section names are truncated;
+if true, the long section names extension is employed. The hook
+points to a function that allows the value of the flag to be altered
+at runtime, on formats that support long section names at all; on
+other formats it points to a stub that returns an error indication.
+With input BFDs, the flag is set according to whether any long section
+names are detected while reading the section headers. For a completely
+new BFD, the flag is set to the default for the target format. This
+information can be used by a client of the BFD library when deciding
+what output format to generate, and means that a BFD that is opened
+for read and subsequently converted to a writeable BFD and modified
+in-place will retain whatever format it had on input.
+
+If @code{COFF_LONG_SECTION_NAMES} is simply defined (blank), or is
+defined to the value "1", then long section names are enabled by
+default; if it is defined to the value zero, they are disabled by
+default (but still accepted in input BFDs). The header @file{coffcode.h}
+defines a macro, @code{COFF_DEFAULT_LONG_SECTION_NAMES}, which is
+used in the backends to initialise the backend data structure fields
+appropriately; see the comments for further detail.
+
+@subsubsection Bit twiddling
+Each flavour of coff supported in BFD has its own header file
+describing the external layout of the structures. There is also
+an internal description of the coff layout, in
+@file{coff/internal.h}. A major function of the
+coff backend is swapping the bytes and twiddling the bits to
+translate the external form of the structures into the normal
+internal form. This is all performed in the
+@code{bfd_swap}_@i{thing}_@i{direction} routines. Some
+elements are different sizes between different versions of
+coff; it is the duty of the coff version specific include file
+to override the definitions of various packing routines in
+@file{coffcode.h}. E.g., the size of line number entry in coff is
+sometimes 16 bits, and sometimes 32 bits. @code{#define}ing
+@code{PUT_LNSZ_LNNO} and @code{GET_LNSZ_LNNO} will select the
+correct one. No doubt, some day someone will find a version of
+coff which has a varying field size not catered to at the
+moment. To port BFD, that person will have to add more @code{#defines}.
+Three of the bit twiddling routines are exported to
+@code{gdb}; @code{coff_swap_aux_in}, @code{coff_swap_sym_in}
+and @code{coff_swap_lineno_in}. @code{GDB} reads the symbol
+table on its own, but uses BFD to fix things up. More of the
+bit twiddlers are exported for @code{gas};
+@code{coff_swap_aux_out}, @code{coff_swap_sym_out},
+@code{coff_swap_lineno_out}, @code{coff_swap_reloc_out},
+@code{coff_swap_filehdr_out}, @code{coff_swap_aouthdr_out},
+@code{coff_swap_scnhdr_out}. @code{Gas} currently keeps track
+of all the symbol table and reloc drudgery itself, thereby
+saving the internal BFD overhead, but uses BFD to swap things
+on the way out, making cross ports much safer. Doing so also
+allows BFD (and thus the linker) to use the same header files
+as @code{gas}, which makes one avenue to disaster disappear.
+
+@subsubsection Symbol reading
+The simple canonical form for symbols used by BFD is not rich
+enough to keep all the information available in a coff symbol
+table. The back end gets around this problem by keeping the original
+symbol table around, "behind the scenes".
+
+When a symbol table is requested (through a call to
+@code{bfd_canonicalize_symtab}), a request gets through to
+@code{coff_get_normalized_symtab}. This reads the symbol table from
+the coff file and swaps all the structures inside into the
+internal form. It also fixes up all the pointers in the table
+(represented in the file by offsets from the first symbol in
+the table) into physical pointers to elements in the new
+internal table. This involves some work since the meanings of
+fields change depending upon context: a field that is a
+pointer to another structure in the symbol table at one moment
+may be the size in bytes of a structure at the next. Another
+pass is made over the table. All symbols which mark file names
+(@code{C_FILE} symbols) are modified so that the internal
+string points to the value in the auxent (the real filename)
+rather than the normal text associated with the symbol
+(@code{".file"}).
+
+At this time the symbol names are moved around. Coff stores
+all symbols less than nine characters long physically
+within the symbol table; longer strings are kept at the end of
+the file in the string table. This pass moves all strings
+into memory and replaces them with pointers to the strings.
+
+The symbol table is massaged once again, this time to create
+the canonical table used by the BFD application. Each symbol
+is inspected in turn, and a decision made (using the
+@code{sclass} field) about the various flags to set in the
+@code{asymbol}. @xref{Symbols}. The generated canonical table
+shares strings with the hidden internal symbol table.
+
+Any linenumbers are read from the coff file too, and attached
+to the symbols which own the functions the linenumbers belong to.
+
+@subsubsection Symbol writing
+Writing a symbol to a coff file which didn't come from a coff
+file will lose any debugging information. The @code{asymbol}
+structure remembers the BFD from which the symbol was taken, and on
+output the back end makes sure that the same destination target as
+source target is present.
+
+When the symbols have come from a coff file then all the
+debugging information is preserved.
+
+Symbol tables are provided for writing to the back end in a
+vector of pointers to pointers. This allows applications like
+the linker to accumulate and output large symbol tables
+without having to do too much byte copying.
+
+This function runs through the provided symbol table and
+patches each symbol marked as a file place holder
+(@code{C_FILE}) to point to the next file place holder in the
+list. It also marks each @code{offset} field in the list with
+the offset from the first symbol of the current symbol.
+
+Another function of this procedure is to turn the canonical
+value form of BFD into the form used by coff. Internally, BFD
+expects symbol values to be offsets from a section base; so a
+symbol physically at 0x120, but in a section starting at
+0x100, would have the value 0x20. Coff expects symbols to
+contain their final value, so symbols have their values
+changed at this point to reflect their sum with their owning
+section. This transformation uses the
+@code{output_section} field of the @code{asymbol}'s
+@code{asection} @xref{Sections}.
+
+@itemize @bullet
+
+@item
+@code{coff_mangle_symbols}
+@end itemize
+This routine runs though the provided symbol table and uses
+the offsets generated by the previous pass and the pointers
+generated when the symbol table was read in to create the
+structured hierarchy required by coff. It changes each pointer
+to a symbol into the index into the symbol table of the asymbol.
+
+@itemize @bullet
+
+@item
+@code{coff_write_symbols}
+@end itemize
+This routine runs through the symbol table and patches up the
+symbols from their internal form into the coff way, calls the
+bit twiddlers, and writes out the table to the file.
+
+@findex coff_symbol_type
+@subsubsection @code{coff_symbol_type}
+@strong{Description}@*
+The hidden information for an @code{asymbol} is described in a
+@code{combined_entry_type}:
+
+
+@example
+
+typedef struct coff_ptr_struct
+@{
+ /* Remembers the offset from the first symbol in the file for
+ this symbol. Generated by coff_renumber_symbols. */
+ unsigned int offset;
+
+ /* Should the value of this symbol be renumbered. Used for
+ XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */
+ unsigned int fix_value : 1;
+
+ /* Should the tag field of this symbol be renumbered.
+ Created by coff_pointerize_aux. */
+ unsigned int fix_tag : 1;
+
+ /* Should the endidx field of this symbol be renumbered.
+ Created by coff_pointerize_aux. */
+ unsigned int fix_end : 1;
+
+ /* Should the x_csect.x_scnlen field be renumbered.
+ Created by coff_pointerize_aux. */
+ unsigned int fix_scnlen : 1;
+
+ /* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the
+ index into the line number entries. Set by coff_slurp_symbol_table. */
+ unsigned int fix_line : 1;
+
+ /* The container for the symbol structure as read and translated
+ from the file. */
+ union
+ @{
+ union internal_auxent auxent;
+ struct internal_syment syment;
+ @} u;
+@} combined_entry_type;
+
+
+/* Each canonical asymbol really looks like this: */
+
+typedef struct coff_symbol_struct
+@{
+ /* The actual symbol which the rest of BFD works with */
+ asymbol symbol;
+
+ /* A pointer to the hidden information for this symbol */
+ combined_entry_type *native;
+
+ /* A pointer to the linenumber information for this symbol */
+ struct lineno_cache_entry *lineno;
+
+ /* Have the line numbers been relocated yet ? */
+ bfd_boolean done_lineno;
+@} coff_symbol_type;
+@end example
+@findex bfd_coff_backend_data
+@subsubsection @code{bfd_coff_backend_data}
+
+@example
+/* COFF symbol classifications. */
+
+enum coff_symbol_classification
+@{
+ /* Global symbol. */
+ COFF_SYMBOL_GLOBAL,
+ /* Common symbol. */
+ COFF_SYMBOL_COMMON,
+ /* Undefined symbol. */
+ COFF_SYMBOL_UNDEFINED,
+ /* Local symbol. */
+ COFF_SYMBOL_LOCAL,
+ /* PE section symbol. */
+ COFF_SYMBOL_PE_SECTION
+@};
+
+@end example
+Special entry points for gdb to swap in coff symbol table parts:
+@example
+typedef struct
+@{
+ void (*_bfd_coff_swap_aux_in)
+ (bfd *, void *, int, int, int, int, void *);
+
+ void (*_bfd_coff_swap_sym_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_lineno_in)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_aux_out)
+ (bfd *, void *, int, int, int, int, void *);
+
+ unsigned int (*_bfd_coff_swap_sym_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_lineno_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_reloc_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_filehdr_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_aouthdr_out)
+ (bfd *, void *, void *);
+
+ unsigned int (*_bfd_coff_swap_scnhdr_out)
+ (bfd *, void *, void *);
+
+ unsigned int _bfd_filhsz;
+ unsigned int _bfd_aoutsz;
+ unsigned int _bfd_scnhsz;
+ unsigned int _bfd_symesz;
+ unsigned int _bfd_auxesz;
+ unsigned int _bfd_relsz;
+ unsigned int _bfd_linesz;
+ unsigned int _bfd_filnmlen;
+ bfd_boolean _bfd_coff_long_filenames;
+
+ bfd_boolean _bfd_coff_long_section_names;
+ bfd_boolean (*_bfd_coff_set_long_section_names)
+ (bfd *, int);
+
+ unsigned int _bfd_coff_default_section_alignment_power;
+ bfd_boolean _bfd_coff_force_symnames_in_strings;
+ unsigned int _bfd_coff_debug_string_prefix_length;
+
+ void (*_bfd_coff_swap_filehdr_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_aouthdr_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_scnhdr_in)
+ (bfd *, void *, void *);
+
+ void (*_bfd_coff_swap_reloc_in)
+ (bfd *abfd, void *, void *);
+
+ bfd_boolean (*_bfd_coff_bad_format_hook)
+ (bfd *, void *);
+
+ bfd_boolean (*_bfd_coff_set_arch_mach_hook)
+ (bfd *, void *);
+
+ void * (*_bfd_coff_mkobject_hook)
+ (bfd *, void *, void *);
+
+ bfd_boolean (*_bfd_styp_to_sec_flags_hook)
+ (bfd *, void *, const char *, asection *, flagword *);
+
+ void (*_bfd_set_alignment_hook)
+ (bfd *, asection *, void *);
+
+ bfd_boolean (*_bfd_coff_slurp_symbol_table)
+ (bfd *);
+
+ bfd_boolean (*_bfd_coff_symname_in_debug)
+ (bfd *, struct internal_syment *);
+
+ bfd_boolean (*_bfd_coff_pointerize_aux_hook)
+ (bfd *, combined_entry_type *, combined_entry_type *,
+ unsigned int, combined_entry_type *);
+
+ bfd_boolean (*_bfd_coff_print_aux)
+ (bfd *, FILE *, combined_entry_type *, combined_entry_type *,
+ combined_entry_type *, unsigned int);
+
+ void (*_bfd_coff_reloc16_extra_cases)
+ (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *,
+ bfd_byte *, unsigned int *, unsigned int *);
+
+ int (*_bfd_coff_reloc16_estimate)
+ (bfd *, asection *, arelent *, unsigned int,
+ struct bfd_link_info *);
+
+ enum coff_symbol_classification (*_bfd_coff_classify_symbol)
+ (bfd *, struct internal_syment *);
+
+ bfd_boolean (*_bfd_coff_compute_section_file_positions)
+ (bfd *);
+
+ bfd_boolean (*_bfd_coff_start_final_link)
+ (bfd *, struct bfd_link_info *);
+
+ bfd_boolean (*_bfd_coff_relocate_section)
+ (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *,
+ struct internal_reloc *, struct internal_syment *, asection **);
+
+ reloc_howto_type *(*_bfd_coff_rtype_to_howto)
+ (bfd *, asection *, struct internal_reloc *,
+ struct coff_link_hash_entry *, struct internal_syment *,
+ bfd_vma *);
+
+ bfd_boolean (*_bfd_coff_adjust_symndx)
+ (bfd *, struct bfd_link_info *, bfd *, asection *,
+ struct internal_reloc *, bfd_boolean *);
+
+ bfd_boolean (*_bfd_coff_link_add_one_symbol)
+ (struct bfd_link_info *, bfd *, const char *, flagword,
+ asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean,
+ struct bfd_link_hash_entry **);
+
+ bfd_boolean (*_bfd_coff_link_output_has_begun)
+ (bfd *, struct coff_final_link_info *);
+
+ bfd_boolean (*_bfd_coff_final_link_postscript)
+ (bfd *, struct coff_final_link_info *);
+
+ bfd_boolean (*_bfd_coff_print_pdata)
+ (bfd *, void *);
+
+@} bfd_coff_backend_data;
+
+#define coff_backend_info(abfd) \
+ ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)
+
+#define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
+ ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))
+
+#define bfd_coff_swap_sym_in(a,e,i) \
+ ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))
+
+#define bfd_coff_swap_lineno_in(a,e,i) \
+ ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))
+
+#define bfd_coff_swap_reloc_out(abfd, i, o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))
+
+#define bfd_coff_swap_lineno_out(abfd, i, o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))
+
+#define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
+ ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))
+
+#define bfd_coff_swap_sym_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))
+
+#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))
+
+#define bfd_coff_swap_filehdr_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))
+
+#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))
+
+#define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
+#define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
+#define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
+#define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
+#define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
+#define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz)
+#define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
+#define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen)
+#define bfd_coff_long_filenames(abfd) \
+ (coff_backend_info (abfd)->_bfd_coff_long_filenames)
+#define bfd_coff_long_section_names(abfd) \
+ (coff_backend_info (abfd)->_bfd_coff_long_section_names)
+#define bfd_coff_set_long_section_names(abfd, enable) \
+ ((coff_backend_info (abfd)->_bfd_coff_set_long_section_names) (abfd, enable))
+#define bfd_coff_default_section_alignment_power(abfd) \
+ (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
+#define bfd_coff_swap_filehdr_in(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))
+
+#define bfd_coff_swap_aouthdr_in(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))
+
+#define bfd_coff_swap_scnhdr_in(abfd, i,o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))
+
+#define bfd_coff_swap_reloc_in(abfd, i, o) \
+ ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))
+
+#define bfd_coff_bad_format_hook(abfd, filehdr) \
+ ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))
+
+#define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
+ ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
+#define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
+ ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\
+ (abfd, filehdr, aouthdr))
+
+#define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\
+ ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\
+ (abfd, scnhdr, name, section, flags_ptr))
+
+#define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
+ ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))
+
+#define bfd_coff_slurp_symbol_table(abfd)\
+ ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))
+
+#define bfd_coff_symname_in_debug(abfd, sym)\
+ ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))
+
+#define bfd_coff_force_symnames_in_strings(abfd)\
+ (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings)
+
+#define bfd_coff_debug_string_prefix_length(abfd)\
+ (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length)
+
+#define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
+ ((coff_backend_info (abfd)->_bfd_coff_print_aux)\
+ (abfd, file, base, symbol, aux, indaux))
+
+#define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\
+ reloc, data, src_ptr, dst_ptr)\
+ ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
+ (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))
+
+#define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
+ ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
+ (abfd, section, reloc, shrink, link_info))
+
+#define bfd_coff_classify_symbol(abfd, sym)\
+ ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\
+ (abfd, sym))
+
+#define bfd_coff_compute_section_file_positions(abfd)\
+ ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
+ (abfd))
+
+#define bfd_coff_start_final_link(obfd, info)\
+ ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
+ (obfd, info))
+#define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
+ ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
+ (obfd, info, ibfd, o, con, rel, isyms, secs))
+#define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
+ ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
+ (abfd, sec, rel, h, sym, addendp))
+#define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
+ ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
+ (obfd, info, ibfd, sec, rel, adjustedp))
+#define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\
+ value, string, cp, coll, hashp)\
+ ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
+ (info, abfd, name, flags, section, value, string, cp, coll, hashp))
+
+#define bfd_coff_link_output_has_begun(a,p) \
+ ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a, p))
+#define bfd_coff_final_link_postscript(a,p) \
+ ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a, p))
+
+#define bfd_coff_have_print_pdata(a) \
+ (coff_backend_info (a)->_bfd_coff_print_pdata)
+#define bfd_coff_print_pdata(a,p) \
+ ((coff_backend_info (a)->_bfd_coff_print_pdata) (a, p))
+
+/* Macro: Returns true if the bfd is a PE executable as opposed to a
+ PE object file. */
+#define bfd_pei_p(abfd) \
+ (CONST_STRNEQ ((abfd)->xvec->name, "pei-"))
+@end example
+@subsubsection Writing relocations
+To write relocations, the back end steps though the
+canonical relocation table and create an
+@code{internal_reloc}. The symbol index to use is removed from
+the @code{offset} field in the symbol table supplied. The
+address comes directly from the sum of the section base
+address and the relocation offset; the type is dug directly
+from the howto field. Then the @code{internal_reloc} is
+swapped into the shape of an @code{external_reloc} and written
+out to disk.
+
+@subsubsection Reading linenumbers
+Creating the linenumber table is done by reading in the entire
+coff linenumber table, and creating another table for internal use.
+
+A coff linenumber table is structured so that each function
+is marked as having a line number of 0. Each line within the
+function is an offset from the first line in the function. The
+base of the line number information for the table is stored in
+the symbol associated with the function.
+
+Note: The PE format uses line number 0 for a flag indicating a
+new source file.
+
+The information is copied from the external to the internal
+table, and each symbol which marks a function is marked by
+pointing its...
+
+How does this work ?
+
+@subsubsection Reading relocations
+Coff relocations are easily transformed into the internal BFD form
+(@code{arelent}).
+
+Reading a coff relocation table is done in the following stages:
+
+@itemize @bullet
+
+@item
+Read the entire coff relocation table into memory.
+
+@item
+Process each relocation in turn; first swap it from the
+external to the internal form.
+
+@item
+Turn the symbol referenced in the relocation's symbol index
+into a pointer into the canonical symbol table.
+This table is the same as the one returned by a call to
+@code{bfd_canonicalize_symtab}. The back end will call that
+routine and save the result if a canonicalization hasn't been done.
+
+@item
+The reloc index is turned into a pointer to a howto
+structure, in a back end specific way. For instance, the 386
+and 960 use the @code{r_type} to directly produce an index
+into a howto table vector; the 88k subtracts a number from the
+@code{r_type} field and creates an addend field.
+@end itemize
+
diff --git a/bfd/doc/core.texi b/bfd/doc/core.texi
new file mode 100644
index 00000000000..1f09445ef76
--- /dev/null
+++ b/bfd/doc/core.texi
@@ -0,0 +1,60 @@
+@section Core files
+
+
+@subsection Core file functions
+
+
+@strong{Description}@*
+These are functions pertaining to core files.
+
+@findex bfd_core_file_failing_command
+@subsubsection @code{bfd_core_file_failing_command}
+@strong{Synopsis}
+@example
+const char *bfd_core_file_failing_command (bfd *abfd);
+@end example
+@strong{Description}@*
+Return a read-only string explaining which program was running
+when it failed and produced the core file @var{abfd}.
+
+@findex bfd_core_file_failing_signal
+@subsubsection @code{bfd_core_file_failing_signal}
+@strong{Synopsis}
+@example
+int bfd_core_file_failing_signal (bfd *abfd);
+@end example
+@strong{Description}@*
+Returns the signal number which caused the core dump which
+generated the file the BFD @var{abfd} is attached to.
+
+@findex core_file_matches_executable_p
+@subsubsection @code{core_file_matches_executable_p}
+@strong{Synopsis}
+@example
+bfd_boolean core_file_matches_executable_p
+ (bfd *core_bfd, bfd *exec_bfd);
+@end example
+@strong{Description}@*
+Return @code{TRUE} if the core file attached to @var{core_bfd}
+was generated by a run of the executable file attached to
+@var{exec_bfd}, @code{FALSE} otherwise.
+
+@findex generic_core_file_matches_executable_p
+@subsubsection @code{generic_core_file_matches_executable_p}
+@strong{Synopsis}
+@example
+bfd_boolean generic_core_file_matches_executable_p
+ (bfd *core_bfd, bfd *exec_bfd);
+@end example
+@strong{Description}@*
+Return TRUE if the core file attached to @var{core_bfd}
+was generated by a run of the executable file attached
+to @var{exec_bfd}. The match is based on executable
+basenames only.
+
+Note: When not able to determine the core file failing
+command or the executable name, we still return TRUE even
+though we're not sure that core file and executable match.
+This is to avoid generating a false warning in situations
+where we really don't know whether they match or not.
+
diff --git a/bfd/doc/elf.texi b/bfd/doc/elf.texi
new file mode 100644
index 00000000000..40533860c85
--- /dev/null
+++ b/bfd/doc/elf.texi
@@ -0,0 +1,9 @@
+@section ELF backends
+BFD support for ELF formats is being worked on.
+Currently, the best supported back ends are for sparc and i386
+(running svr4 or Solaris 2).
+
+Documentation of the internals of the support code still needs
+to be written. The code is changing quickly enough that we
+haven't bothered yet.
+
diff --git a/bfd/doc/elfcode.texi b/bfd/doc/elfcode.texi
new file mode 100644
index 00000000000..e69de29bb2d
--- /dev/null
+++ b/bfd/doc/elfcode.texi
diff --git a/bfd/doc/format.texi b/bfd/doc/format.texi
new file mode 100644
index 00000000000..9674acff440
--- /dev/null
+++ b/bfd/doc/format.texi
@@ -0,0 +1,112 @@
+@section File formats
+A format is a BFD concept of high level file contents type. The
+formats supported by BFD are:
+
+@itemize @bullet
+
+@item
+@code{bfd_object}
+@end itemize
+The BFD may contain data, symbols, relocations and debug info.
+
+@itemize @bullet
+
+@item
+@code{bfd_archive}
+@end itemize
+The BFD contains other BFDs and an optional index.
+
+@itemize @bullet
+
+@item
+@code{bfd_core}
+@end itemize
+The BFD contains the result of an executable core dump.
+
+@subsection File format functions
+
+
+@findex bfd_check_format
+@subsubsection @code{bfd_check_format}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
+@end example
+@strong{Description}@*
+Verify if the file attached to the BFD @var{abfd} is compatible
+with the format @var{format} (i.e., one of @code{bfd_object},
+@code{bfd_archive} or @code{bfd_core}).
+
+If the BFD has been set to a specific target before the
+call, only the named target and format combination is
+checked. If the target has not been set, or has been set to
+@code{default}, then all the known target backends is
+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 @code{TRUE} on success, otherwise @code{FALSE}
+with one of the following error codes:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_invalid_operation} -
+if @code{format} is not one of @code{bfd_object}, @code{bfd_archive} or
+@code{bfd_core}.
+
+@item
+@code{bfd_error_system_call} -
+if an error occured during a read - even some file mismatches
+can cause bfd_error_system_calls.
+
+@item
+@code{file_not_recognised} -
+none of the backends recognised the file format.
+
+@item
+@code{bfd_error_file_ambiguously_recognized} -
+more than one backend recognised the file format.
+@end itemize
+
+@findex bfd_check_format_matches
+@subsubsection @code{bfd_check_format_matches}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_check_format_matches
+ (bfd *abfd, bfd_format format, char ***matching);
+@end example
+@strong{Description}@*
+Like @code{bfd_check_format}, except when it returns FALSE with
+@code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}. In that
+case, if @var{matching} is not NULL, it will be filled in with
+a NULL-terminated list of the names of the formats that matched,
+allocated with @code{malloc}.
+Then the user may choose a format and try again.
+
+When done with the list that @var{matching} points to, the caller
+should free it.
+
+@findex bfd_set_format
+@subsubsection @code{bfd_set_format}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
+@end example
+@strong{Description}@*
+This function sets the file format of the BFD @var{abfd} to the
+format @var{format}. If the target set in the BFD does not
+support the format requested, the format is invalid, or the BFD
+is not open for writing, then an error occurs.
+
+@findex bfd_format_string
+@subsubsection @code{bfd_format_string}
+@strong{Synopsis}
+@example
+const char *bfd_format_string (bfd_format format);
+@end example
+@strong{Description}@*
+Return a pointer to a const string
+@code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown},
+depending upon the value of @var{format}.
+
diff --git a/bfd/doc/hash.texi b/bfd/doc/hash.texi
new file mode 100644
index 00000000000..88d9585cc40
--- /dev/null
+++ b/bfd/doc/hash.texi
@@ -0,0 +1,247 @@
+@section Hash Tables
+@cindex 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 @code{hash.c}.
+
+@menu
+* Creating and Freeing a Hash Table::
+* Looking Up or Entering a String::
+* Traversing a Hash Table::
+* Deriving a New Hash Table Type::
+@end menu
+
+@node Creating and Freeing a Hash Table, Looking Up or Entering a String, Hash Tables, Hash Tables
+@subsection Creating and freeing a hash table
+@findex bfd_hash_table_init
+@findex bfd_hash_table_init_n
+To create a hash table, create an instance of a @code{struct
+bfd_hash_table} (defined in @code{bfd.h}) and call
+@code{bfd_hash_table_init} (if you know approximately how many
+entries you will need, the function @code{bfd_hash_table_init_n},
+which takes a @var{size} argument, may be used).
+@code{bfd_hash_table_init} returns @code{FALSE} if some sort of
+error occurs.
+
+@findex bfd_hash_newfunc
+The function @code{bfd_hash_table_init} take as an argument a
+function to use to create new entries. For a basic hash
+table, use the function @code{bfd_hash_newfunc}. @xref{Deriving
+a New Hash Table Type}, for why you would want to use a
+different value for this argument.
+
+@findex bfd_hash_allocate
+@code{bfd_hash_table_init} will create an objalloc which will be
+used to allocate new entries. You may allocate memory on this
+objalloc using @code{bfd_hash_allocate}.
+
+@findex bfd_hash_table_free
+Use @code{bfd_hash_table_free} to free up all the memory that has
+been allocated for a hash table. This will not free up the
+@code{struct bfd_hash_table} itself, which you must provide.
+
+@findex bfd_hash_set_default_size
+Use @code{bfd_hash_set_default_size} to set the default size of
+hash table to use.
+
+@node Looking Up or Entering a String, Traversing a Hash Table, Creating and Freeing a Hash Table, Hash Tables
+@subsection Looking up or entering a string
+@findex bfd_hash_lookup
+The function @code{bfd_hash_lookup} is used both to look up a
+string in the hash table and to create a new entry.
+
+If the @var{create} argument is @code{FALSE}, @code{bfd_hash_lookup}
+will look up a string. If the string is found, it will
+returns a pointer to a @code{struct bfd_hash_entry}. If the
+string is not found in the table @code{bfd_hash_lookup} will
+return @code{NULL}. You should not modify any of the fields in
+the returns @code{struct bfd_hash_entry}.
+
+If the @var{create} argument is @code{TRUE}, the string will be
+entered into the hash table if it is not already there.
+Either way a pointer to a @code{struct bfd_hash_entry} will be
+returned, either to the existing structure or to a newly
+created one. In this case, a @code{NULL} return means that an
+error occurred.
+
+If the @var{create} argument is @code{TRUE}, and a new entry is
+created, the @var{copy} argument is used to decide whether to
+copy the string onto the hash table objalloc or not. If
+@var{copy} is passed as @code{FALSE}, you must be careful not to
+deallocate or modify the string as long as the hash table
+exists.
+
+@node Traversing a Hash Table, Deriving a New Hash Table Type, Looking Up or Entering a String, Hash Tables
+@subsection Traversing a hash table
+@findex bfd_hash_traverse
+The function @code{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.
+
+@code{bfd_hash_traverse} takes as arguments a function and a
+generic @code{void *} pointer. The function is called with a
+hash table entry (a @code{struct bfd_hash_entry *}) and the
+generic pointer passed to @code{bfd_hash_traverse}. The function
+must return a @code{boolean} value, which indicates whether to
+continue traversing the hash table. If the function returns
+@code{FALSE}, @code{bfd_hash_traverse} will stop the traversal and
+return immediately.
+
+@node Deriving a New Hash Table Type, , Traversing a Hash Table, Hash Tables
+@subsection 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 @code{bfdlink.h}. The
+functions are in @code{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.
+
+@menu
+* Define the Derived Structures::
+* Write the Derived Creation Routine::
+* Write Other Derived Routines::
+@end menu
+
+@node Define the Derived Structures, Write the Derived Creation Routine, Deriving a New Hash Table Type, Deriving a New Hash Table Type
+@subsubsection 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 @code{struct bfd_hash_entry}, which is defined in
+@code{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 @code{struct bfd_hash_table}.
+
+For example, the linker hash table defines @code{struct
+bfd_link_hash_entry} (in @code{bfdlink.h}). The first field,
+@code{root}, is of type @code{struct bfd_hash_entry}. Similarly,
+the first field in @code{struct bfd_link_hash_table}, @code{table},
+is of type @code{struct bfd_hash_table}.
+
+@node Write the Derived Creation Routine, Write Other Derived Routines, Define the Derived Structures, Deriving a New Hash Table Type
+@subsubsection 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 @code{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 @code{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.
+@var{function_name} is the name of the routine.
+@var{entry_type} is the type of an entry in the hash table you
+are creating. @var{base_newfunc} is the name of the creation
+routine of the hash table type your hash table is derived
+from.
+
+
+@example
+struct bfd_hash_entry *
+@var{function_name} (struct bfd_hash_entry *entry,
+ struct bfd_hash_table *table,
+ const char *string)
+@{
+ struct @var{entry_type} *ret = (@var{entry_type} *) entry;
+
+ /* Allocate the structure if it has not already been allocated by a
+ derived class. */
+ if (ret == NULL)
+ @{
+ ret = bfd_hash_allocate (table, sizeof (* ret));
+ if (ret == NULL)
+ return NULL;
+ @}
+
+ /* Call the allocation method of the base class. */
+ ret = ((@var{entry_type} *)
+ @var{base_newfunc} ((struct bfd_hash_entry *) ret, table, string));
+
+ /* Initialize the local fields here. */
+
+ return (struct bfd_hash_entry *) ret;
+@}
+@end example
+@strong{Description}@*
+The creation routine for the linker hash table, which is in
+@code{linker.c}, looks just like this example.
+@var{function_name} is @code{_bfd_link_hash_newfunc}.
+@var{entry_type} is @code{struct bfd_link_hash_entry}.
+@var{base_newfunc} is @code{bfd_hash_newfunc}, the creation
+routine for a basic hash table.
+
+@code{_bfd_link_hash_newfunc} also initializes the local fields
+in a linker hash table entry: @code{type}, @code{written} and
+@code{next}.
+
+@node Write Other Derived Routines, , Write the Derived Creation Routine, Deriving a New Hash Table Type
+@subsubsection 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 @code{_bfd_link_hash_table_init} in @code{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 @code{bfd_link_hash_lookup} in
+@code{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
+@code{bfd_link_hash_traverse} in @code{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 @code{aout_link_hash_lookup} and
+@code{aout_link_hash_traverse} in aoutx.h.
+
diff --git a/bfd/doc/init.texi b/bfd/doc/init.texi
new file mode 100644
index 00000000000..ab735f8e986
--- /dev/null
+++ b/bfd/doc/init.texi
@@ -0,0 +1,16 @@
+@section Initialization
+
+
+@subsection Initialization functions
+These are the functions that handle initializing a BFD.
+
+@findex bfd_init
+@subsubsection @code{bfd_init}
+@strong{Synopsis}
+@example
+void bfd_init (void);
+@end example
+@strong{Description}@*
+This routine must be called before any other BFD function to
+initialize magical internal data structures.
+
diff --git a/bfd/doc/libbfd.texi b/bfd/doc/libbfd.texi
new file mode 100644
index 00000000000..fef6e0e842e
--- /dev/null
+++ b/bfd/doc/libbfd.texi
@@ -0,0 +1,179 @@
+@section Implementation details
+
+
+@subsection Internal functions
+
+
+@strong{Description}@*
+These routines are used within BFD.
+They are not intended for export, but are documented here for
+completeness.
+
+@findex bfd_write_bigendian_4byte_int
+@subsubsection @code{bfd_write_bigendian_4byte_int}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_write_bigendian_4byte_int (bfd *, unsigned int);
+@end example
+@strong{Description}@*
+Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big
+endian order regardless of what else is going on. This is useful in
+archives.
+
+@findex bfd_put_size
+@subsubsection @code{bfd_put_size}
+@findex bfd_get_size
+@subsubsection @code{bfd_get_size}
+@strong{Description}@*
+These macros as used for reading and writing raw data in
+sections; each access (except for bytes) is vectored through
+the target format of the BFD and mangled accordingly. The
+mangling performs any necessary endian translations and
+removes alignment restrictions. Note that types accepted and
+returned by these macros are identical so they can be swapped
+around in macros---for example, @file{libaout.h} defines @code{GET_WORD}
+to either @code{bfd_get_32} or @code{bfd_get_64}.
+
+In the put routines, @var{val} must be a @code{bfd_vma}. If we are on a
+system without prototypes, the caller is responsible for making
+sure that is true, with a cast if necessary. We don't cast
+them in the macro definitions because that would prevent @code{lint}
+or @code{gcc -Wall} from detecting sins such as passing a pointer.
+To detect calling these with less than a @code{bfd_vma}, use
+@code{gcc -Wconversion} on a host with 64 bit @code{bfd_vma}'s.
+@example
+
+/* Byte swapping macros for user section data. */
+
+#define bfd_put_8(abfd, val, ptr) \
+ ((void) (*((unsigned char *) (ptr)) = (val) & 0xff))
+#define bfd_put_signed_8 \
+ bfd_put_8
+#define bfd_get_8(abfd, ptr) \
+ (*(unsigned char *) (ptr) & 0xff)
+#define bfd_get_signed_8(abfd, ptr) \
+ (((*(unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80)
+
+#define bfd_put_16(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_putx16, ((val),(ptr)))
+#define bfd_put_signed_16 \
+ bfd_put_16
+#define bfd_get_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx16, (ptr))
+#define bfd_get_signed_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx_signed_16, (ptr))
+
+#define bfd_put_32(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_putx32, ((val),(ptr)))
+#define bfd_put_signed_32 \
+ bfd_put_32
+#define bfd_get_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx32, (ptr))
+#define bfd_get_signed_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx_signed_32, (ptr))
+
+#define bfd_put_64(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_putx64, ((val), (ptr)))
+#define bfd_put_signed_64 \
+ bfd_put_64
+#define bfd_get_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx64, (ptr))
+#define bfd_get_signed_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_getx_signed_64, (ptr))
+
+#define bfd_get(bits, abfd, ptr) \
+ ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr) \
+ : (bits) == 16 ? bfd_get_16 (abfd, ptr) \
+ : (bits) == 32 ? bfd_get_32 (abfd, ptr) \
+ : (bits) == 64 ? bfd_get_64 (abfd, ptr) \
+ : (abort (), (bfd_vma) - 1))
+
+#define bfd_put(bits, abfd, val, ptr) \
+ ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \
+ : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \
+ : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \
+ : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \
+ : (abort (), (void) 0))
+
+@end example
+
+@findex bfd_h_put_size
+@subsubsection @code{bfd_h_put_size}
+@strong{Description}@*
+These macros have the same function as their @code{bfd_get_x}
+brethren, except that they are used for removing information
+for the header records of object files. Believe it or not,
+some object files keep their header records in big endian
+order and their data in little endian order.
+@example
+
+/* Byte swapping macros for file header data. */
+
+#define bfd_h_put_8(abfd, val, ptr) \
+ bfd_put_8 (abfd, val, ptr)
+#define bfd_h_put_signed_8(abfd, val, ptr) \
+ bfd_put_8 (abfd, val, ptr)
+#define bfd_h_get_8(abfd, ptr) \
+ bfd_get_8 (abfd, ptr)
+#define bfd_h_get_signed_8(abfd, ptr) \
+ bfd_get_signed_8 (abfd, ptr)
+
+#define bfd_h_put_16(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_h_putx16, (val, ptr))
+#define bfd_h_put_signed_16 \
+ bfd_h_put_16
+#define bfd_h_get_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx16, (ptr))
+#define bfd_h_get_signed_16(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr))
+
+#define bfd_h_put_32(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_h_putx32, (val, ptr))
+#define bfd_h_put_signed_32 \
+ bfd_h_put_32
+#define bfd_h_get_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx32, (ptr))
+#define bfd_h_get_signed_32(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr))
+
+#define bfd_h_put_64(abfd, val, ptr) \
+ BFD_SEND (abfd, bfd_h_putx64, (val, ptr))
+#define bfd_h_put_signed_64 \
+ bfd_h_put_64
+#define bfd_h_get_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx64, (ptr))
+#define bfd_h_get_signed_64(abfd, ptr) \
+ BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr))
+
+/* Aliases for the above, which should eventually go away. */
+
+#define H_PUT_64 bfd_h_put_64
+#define H_PUT_32 bfd_h_put_32
+#define H_PUT_16 bfd_h_put_16
+#define H_PUT_8 bfd_h_put_8
+#define H_PUT_S64 bfd_h_put_signed_64
+#define H_PUT_S32 bfd_h_put_signed_32
+#define H_PUT_S16 bfd_h_put_signed_16
+#define H_PUT_S8 bfd_h_put_signed_8
+#define H_GET_64 bfd_h_get_64
+#define H_GET_32 bfd_h_get_32
+#define H_GET_16 bfd_h_get_16
+#define H_GET_8 bfd_h_get_8
+#define H_GET_S64 bfd_h_get_signed_64
+#define H_GET_S32 bfd_h_get_signed_32
+#define H_GET_S16 bfd_h_get_signed_16
+#define H_GET_S8 bfd_h_get_signed_8
+
+
+@end example
+
+@findex bfd_log2
+@subsubsection @code{bfd_log2}
+@strong{Synopsis}
+@example
+unsigned int bfd_log2 (bfd_vma x);
+@end example
+@strong{Description}@*
+Return the log base 2 of the value supplied, rounded up. E.g., an
+@var{x} of 1025 returns 11. A @var{x} of 0 returns 0.
+
diff --git a/bfd/doc/linker.texi b/bfd/doc/linker.texi
new file mode 100644
index 00000000000..27055dc251e
--- /dev/null
+++ b/bfd/doc/linker.texi
@@ -0,0 +1,412 @@
+@section Linker Functions
+@cindex Linker
+The linker uses three special entry points in the BFD target
+vector. It is not necessary to write special routines for
+these entry points when creating a new BFD back end, since
+generic versions are provided. However, writing them can
+speed up linking and make it use significantly less runtime
+memory.
+
+The first routine creates a hash table used by the other
+routines. The second routine adds the symbols from an object
+file to the hash table. The third routine takes all the
+object files and links them together to create the output
+file. These routines are designed so that the linker proper
+does not need to know anything about the symbols in the object
+files that it is linking. The linker merely arranges the
+sections as directed by the linker script and lets BFD handle
+the details of symbols and relocs.
+
+The second routine and third routines are passed a pointer to
+a @code{struct bfd_link_info} structure (defined in
+@code{bfdlink.h}) which holds information relevant to the link,
+including the linker hash table (which was created by the
+first routine) and a set of callback functions to the linker
+proper.
+
+The generic linker routines are in @code{linker.c}, and use the
+header file @code{genlink.h}. As of this writing, the only back
+ends which have implemented versions of these routines are
+a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}). The a.out
+routines are used as examples throughout this section.
+
+@menu
+* Creating a Linker Hash Table::
+* Adding Symbols to the Hash Table::
+* Performing the Final Link::
+@end menu
+
+@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions
+@subsection Creating a linker hash table
+@cindex _bfd_link_hash_table_create in target vector
+@cindex target vector (_bfd_link_hash_table_create)
+The linker routines must create a hash table, which must be
+derived from @code{struct bfd_link_hash_table} described in
+@code{bfdlink.c}. @xref{Hash Tables}, for information on how to
+create a derived hash table. This entry point is called using
+the target vector of the linker output file.
+
+The @code{_bfd_link_hash_table_create} entry point must allocate
+and initialize an instance of the desired hash table. If the
+back end does not require any additional information to be
+stored with the entries in the hash table, the entry point may
+simply create a @code{struct bfd_link_hash_table}. Most likely,
+however, some additional information will be needed.
+
+For example, with each entry in the hash table the a.out
+linker keeps the index the symbol has in the final output file
+(this index number is used so that when doing a relocatable
+link the symbol index used in the output file can be quickly
+filled in when copying over a reloc). The a.out linker code
+defines the required structures and functions for a hash table
+derived from @code{struct bfd_link_hash_table}. The a.out linker
+hash table is created by the function
+@code{NAME(aout,link_hash_table_create)}; it simply allocates
+space for the hash table, initializes it, and returns a
+pointer to it.
+
+When writing the linker routines for a new back end, you will
+generally not know exactly which fields will be required until
+you have finished. You should simply create a new hash table
+which defines no additional fields, and then simply add fields
+as they become necessary.
+
+@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions
+@subsection Adding symbols to the hash table
+@cindex _bfd_link_add_symbols in target vector
+@cindex target vector (_bfd_link_add_symbols)
+The linker proper will call the @code{_bfd_link_add_symbols}
+entry point for each object file or archive which is to be
+linked (typically these are the files named on the command
+line, but some may also come from the linker script). The
+entry point is responsible for examining the file. For an
+object file, BFD must add any relevant symbol information to
+the hash table. For an archive, BFD must determine which
+elements of the archive should be used and adding them to the
+link.
+
+The a.out version of this entry point is
+@code{NAME(aout,link_add_symbols)}.
+
+@menu
+* Differing file formats::
+* Adding symbols from an object file::
+* Adding symbols from an archive::
+@end menu
+
+@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table
+@subsubsection Differing file formats
+Normally all the files involved in a link will be of the same
+format, but it is also possible to link together different
+format object files, and the back end must support that. The
+@code{_bfd_link_add_symbols} entry point is called via the target
+vector of the file to be added. This has an important
+consequence: the function may not assume that the hash table
+is the type created by the corresponding
+@code{_bfd_link_hash_table_create} vector. All the
+@code{_bfd_link_add_symbols} function can assume about the hash
+table is that it is derived from @code{struct
+bfd_link_hash_table}.
+
+Sometimes the @code{_bfd_link_add_symbols} function must store
+some information in the hash table entry to be used by the
+@code{_bfd_final_link} function. In such a case the output bfd
+xvec must be checked to make sure that the hash table was
+created by an object file of the same format.
+
+The @code{_bfd_final_link} routine must be prepared to handle a
+hash entry without any extra information added by the
+@code{_bfd_link_add_symbols} function. A hash entry without
+extra information will also occur when the linker script
+directs the linker to create a symbol. Note that, regardless
+of how a hash table entry is added, all the fields will be
+initialized to some sort of null value by the hash table entry
+initialization function.
+
+See @code{ecoff_link_add_externals} for an example of how to
+check the output bfd before saving information (in this
+case, the ECOFF external symbol debugging information) in a
+hash table entry.
+
+@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table
+@subsubsection Adding symbols from an object file
+When the @code{_bfd_link_add_symbols} routine is passed an object
+file, it must add all externally visible symbols in that
+object file to the hash table. The actual work of adding the
+symbol to the hash table is normally handled by the function
+@code{_bfd_generic_link_add_one_symbol}. The
+@code{_bfd_link_add_symbols} routine is responsible for reading
+all the symbols from the object file and passing the correct
+information to @code{_bfd_generic_link_add_one_symbol}.
+
+The @code{_bfd_link_add_symbols} routine should not use
+@code{bfd_canonicalize_symtab} to read the symbols. The point of
+providing this routine is to avoid the overhead of converting
+the symbols into generic @code{asymbol} structures.
+
+@findex _bfd_generic_link_add_one_symbol
+@code{_bfd_generic_link_add_one_symbol} handles the details of
+combining common symbols, warning about multiple definitions,
+and so forth. It takes arguments which describe the symbol to
+add, notably symbol flags, a section, and an offset. The
+symbol flags include such things as @code{BSF_WEAK} or
+@code{BSF_INDIRECT}. The section is a section in the object
+file, or something like @code{bfd_und_section_ptr} for an undefined
+symbol or @code{bfd_com_section_ptr} for a common symbol.
+
+If the @code{_bfd_final_link} routine is also going to need to
+read the symbol information, the @code{_bfd_link_add_symbols}
+routine should save it somewhere attached to the object file
+BFD. However, the information should only be saved if the
+@code{keep_memory} field of the @code{info} argument is TRUE, so
+that the @code{-no-keep-memory} linker switch is effective.
+
+The a.out function which adds symbols from an object file is
+@code{aout_link_add_object_symbols}, and most of the interesting
+work is in @code{aout_link_add_symbols}. The latter saves
+pointers to the hash tables entries created by
+@code{_bfd_generic_link_add_one_symbol} indexed by symbol number,
+so that the @code{_bfd_final_link} routine does not have to call
+the hash table lookup routine to locate the entry.
+
+@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table
+@subsubsection Adding symbols from an archive
+When the @code{_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
+@code{add_archive_element} linker callback, and it must add the
+symbols from the object file to the linker hash table.
+
+@findex _bfd_generic_link_add_archive_symbols
+In most cases the work of looking through the symbols in the
+archive should be done by the
+@code{_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.
+@code{_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
+@code{_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 @code{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
+@code{_bfd_link_add_symbols} function.
+
+When the a.out @code{_bfd_link_add_symbols} function receives an
+archive, it calls @code{_bfd_generic_link_add_archive_symbols}
+passing @code{aout_link_check_archive_element} as the function
+argument. @code{aout_link_check_archive_element} calls
+@code{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 @code{add_archive_element} callback and then
+@code{aout_link_check_archive_element} calls
+@code{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 @code{_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.
+
+@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions
+@subsection Performing the final link
+@cindex _bfd_link_final_link in target vector
+@cindex target vector (_bfd_final_link)
+When all the input files have been processed, the linker calls
+the @code{_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 relocatable 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 @code{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
+@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}.
+
+@menu
+* Information provided by the linker::
+* Relocating the section contents::
+* Writing the symbol table::
+@end menu
+
+@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link
+@subsubsection Information provided by the linker
+Before the linker calls the @code{_bfd_final_link} entry point,
+it sets up some data structures for the function to use.
+
+The @code{input_bfds} field of the @code{bfd_link_info} structure
+will point to a list of all the input files included in the
+link. These files are linked through the @code{link_next} field
+of the @code{bfd} structure.
+
+Each section in the output file will have a list of
+@code{link_order} structures attached to the @code{map_head.link_order}
+field (the @code{link_order} structure is defined in
+@code{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 relocatable object file.
+
+@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link
+@subsubsection Relocating the section contents
+The @code{_bfd_final_link} function should look through the
+@code{link_order} structures attached to each section of the
+output file. Each @code{link_order} structure should either be
+handled specially, or it should be passed to the function
+@code{_bfd_default_link_order} which will do the right thing
+(@code{_bfd_default_link_order} is defined in @code{linker.c}).
+
+For efficiency, a @code{link_order} of type
+@code{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 @code{link_order} describes part of an
+output section in terms of a section belonging to one of the
+input files. The @code{_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 relocatable link, the
+relocs themselves must also be modified and written out.
+
+@findex _bfd_relocate_contents
+@findex _bfd_final_link_relocate
+The functions @code{_bfd_relocate_contents} and
+@code{_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 @code{reloc_howto_type} argument
+which describes the relocation to perform. These functions
+are defined in @code{reloc.c}.
+
+The a.out function which handles reading, relocating, and
+writing section contents is @code{aout_link_input_section}. The
+actual relocation is done in @code{aout_link_input_section_std}
+and @code{aout_link_input_section_ext}.
+
+@node Writing the symbol table, , Relocating the section contents, Performing the Final Link
+@subsubsection Writing the symbol table
+The @code{_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 @code{strip} and @code{discard} fields of the
+@code{bfd_link_info} structure.
+
+The local symbols of the input files will not have been
+entered into the linker hash table. The @code{_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 @code{link_order} structures, or it may be
+done by stepping through the @code{input_bfds} list.
+
+The @code{_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 @code{strip} field of the @code{bfd_link_info} structure
+controls which symbols are written out. The possible values
+are listed in @code{bfdlink.h}. If the value is @code{strip_some},
+then the @code{keep_hash} field of the @code{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 @code{strip} field of the @code{bfd_link_info} structure
+permits local symbols to be written out, the @code{discard} field
+is used to further controls which local symbols are included
+in the output file. If the value is @code{discard_l}, then all
+local symbols which begin with a certain prefix are discarded;
+this is controlled by the @code{bfd_is_local_label_name} entry point.
+
+The a.out backend handles symbols by calling
+@code{aout_link_write_symbols} on each input BFD and then
+traversing the global hash table with the function
+@code{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 @code{NAME(aout,final_link)}.
+
+@findex bfd_link_split_section
+@subsubsection @code{bfd_link_split_section}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec);
+@end example
+@strong{Description}@*
+Return nonzero if @var{sec} should be split during a
+reloceatable or final link.
+@example
+#define bfd_link_split_section(abfd, sec) \
+ BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))
+
+@end example
+
+@findex bfd_section_already_linked
+@subsubsection @code{bfd_section_already_linked}
+@strong{Synopsis}
+@example
+void bfd_section_already_linked (bfd *abfd, asection *sec,
+ struct bfd_link_info *info);
+@end example
+@strong{Description}@*
+Check if @var{sec} has been already linked during a reloceatable
+or final link.
+@example
+#define bfd_section_already_linked(abfd, sec, info) \
+ BFD_SEND (abfd, _section_already_linked, (abfd, sec, info))
+
+@end example
+
+@findex bfd_generic_define_common_symbol
+@subsubsection @code{bfd_generic_define_common_symbol}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_generic_define_common_symbol
+ (bfd *output_bfd, struct bfd_link_info *info,
+ struct bfd_link_hash_entry *h);
+@end example
+@strong{Description}@*
+Convert common symbol @var{h} into a defined symbol.
+Return TRUE on success and FALSE on failure.
+@example
+#define bfd_define_common_symbol(output_bfd, info, h) \
+ BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h))
+
+@end example
+
+@findex bfd_find_version_for_sym
+@subsubsection @code{bfd_find_version_for_sym }
+@strong{Synopsis}
+@example
+struct bfd_elf_version_tree * bfd_find_version_for_sym
+ (struct bfd_elf_version_tree *verdefs,
+ const char *sym_name, bfd_boolean *hide);
+@end example
+@strong{Description}@*
+Search an elf version script tree for symbol versioning
+info and export / don't-export status for a given symbol.
+Return non-NULL on success and NULL on failure; also sets
+the output @samp{hide} boolean parameter.
+
diff --git a/bfd/doc/mmo.texi b/bfd/doc/mmo.texi
new file mode 100644
index 00000000000..b0d726aad9c
--- /dev/null
+++ b/bfd/doc/mmo.texi
@@ -0,0 +1,365 @@
+@section mmo backend
+The mmo object format is used exclusively together with Professor
+Donald E.@: Knuth's educational 64-bit processor MMIX. The simulator
+@command{mmix} which is available at
+@url{http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz}
+understands this format. That package also includes a combined
+assembler and linker called @command{mmixal}. The mmo format has
+no advantages feature-wise compared to e.g. ELF. It is a simple
+non-relocatable object format with no support for archives or
+debugging information, except for symbol value information and
+line numbers (which is not yet implemented in BFD). See
+@url{http://www-cs-faculty.stanford.edu/~knuth/mmix.html} for more
+information about MMIX. The ELF format is used for intermediate
+object files in the BFD implementation.
+
+@c We want to xref the symbol table node. A feature in "chew"
+@c requires that "commands" do not contain spaces in the
+@c arguments. Hence the hyphen in "Symbol-table".
+@menu
+* File layout::
+* Symbol-table::
+* mmo section mapping::
+@end menu
+
+@node File layout, Symbol-table, mmo, mmo
+@subsection File layout
+The mmo file contents is not partitioned into named sections as
+with e.g.@: ELF. Memory areas is formed by specifying the
+location of the data that follows. Only the memory area
+@samp{0x0000@dots{}00} to @samp{0x01ff@dots{}ff} is executable, so
+it is used for code (and constants) and the area
+@samp{0x2000@dots{}00} to @samp{0x20ff@dots{}ff} is used for
+writable data. @xref{mmo section mapping}.
+
+There is provision for specifying ``special data'' of 65536
+different types. We use type 80 (decimal), arbitrarily chosen the
+same as the ELF @code{e_machine} number for MMIX, filling it with
+section information normally found in ELF objects. @xref{mmo
+section mapping}.
+
+Contents is entered as 32-bit words, xor:ed over previous
+contents, always zero-initialized. A word that starts with the
+byte @samp{0x98} forms a command called a @samp{lopcode}, where
+the next byte distinguished between the thirteen lopcodes. The
+two remaining bytes, called the @samp{Y} and @samp{Z} fields, or
+the @samp{YZ} field (a 16-bit big-endian number), are used for
+various purposes different for each lopcode. As documented in
+@url{http://www-cs-faculty.stanford.edu/~knuth/mmixal-intro.ps.gz},
+the lopcodes are:
+
+@table @code
+@item lop_quote
+0x98000001. The next word is contents, regardless of whether it
+starts with 0x98 or not.
+
+@item lop_loc
+0x9801YYZZ, where @samp{Z} is 1 or 2. This is a location
+directive, setting the location for the next data to the next
+32-bit word (for @math{Z = 1}) or 64-bit word (for @math{Z = 2}),
+plus @math{Y * 2^56}. Normally @samp{Y} is 0 for the text segment
+and 2 for the data segment.
+
+@item lop_skip
+0x9802YYZZ. Increase the current location by @samp{YZ} bytes.
+
+@item lop_fixo
+0x9803YYZZ, where @samp{Z} is 1 or 2. Store the current location
+as 64 bits into the location pointed to by the next 32-bit
+(@math{Z = 1}) or 64-bit (@math{Z = 2}) word, plus @math{Y *
+2^56}.
+
+@item lop_fixr
+0x9804YYZZ. @samp{YZ} is stored into the current location plus
+@math{2 - 4 * YZ}.
+
+@item lop_fixrx
+0x980500ZZ. @samp{Z} is 16 or 24. A value @samp{L} derived from
+the following 32-bit word are used in a manner similar to
+@samp{YZ} in lop_fixr: it is xor:ed into the current location
+minus @math{4 * L}. The first byte of the word is 0 or 1. If it
+is 1, then @math{L = (@var{lowest 24 bits of word}) - 2^Z}, if 0,
+then @math{L = (@var{lowest 24 bits of word})}.
+
+@item lop_file
+0x9806YYZZ. @samp{Y} is the file number, @samp{Z} is count of
+32-bit words. Set the file number to @samp{Y} and the line
+counter to 0. The next @math{Z * 4} bytes contain the file name,
+padded with zeros if the count is not a multiple of four. The
+same @samp{Y} may occur multiple times, but @samp{Z} must be 0 for
+all but the first occurrence.
+
+@item lop_line
+0x9807YYZZ. @samp{YZ} is the line number. Together with
+lop_file, it forms the source location for the next 32-bit word.
+Note that for each non-lopcode 32-bit word, line numbers are
+assumed incremented by one.
+
+@item lop_spec
+0x9808YYZZ. @samp{YZ} is the type number. Data until the next
+lopcode other than lop_quote forms special data of type @samp{YZ}.
+@xref{mmo section mapping}.
+
+Other types than 80, (or type 80 with a content that does not
+parse) is stored in sections named @code{.MMIX.spec_data.@var{n}}
+where @var{n} is the @samp{YZ}-type. The flags for such a
+sections say not to allocate or load the data. The vma is 0.
+Contents of multiple occurrences of special data @var{n} is
+concatenated to the data of the previous lop_spec @var{n}s. The
+location in data or code at which the lop_spec occurred is lost.
+
+@item lop_pre
+0x980901ZZ. The first lopcode in a file. The @samp{Z} field forms the
+length of header information in 32-bit words, where the first word
+tells the time in seconds since @samp{00:00:00 GMT Jan 1 1970}.
+
+@item lop_post
+0x980a00ZZ. @math{Z > 32}. This lopcode follows after all
+content-generating lopcodes in a program. The @samp{Z} field
+denotes the value of @samp{rG} at the beginning of the program.
+The following @math{256 - Z} big-endian 64-bit words are loaded
+into global registers @samp{$G} @dots{} @samp{$255}.
+
+@item lop_stab
+0x980b0000. The next-to-last lopcode in a program. Must follow
+immediately after the lop_post lopcode and its data. After this
+lopcode follows all symbols in a compressed format
+(@pxref{Symbol-table}).
+
+@item lop_end
+0x980cYYZZ. The last lopcode in a program. It must follow the
+lop_stab lopcode and its data. The @samp{YZ} field contains the
+number of 32-bit words of symbol table information after the
+preceding lop_stab lopcode.
+@end table
+
+Note that the lopcode "fixups"; @code{lop_fixr}, @code{lop_fixrx} and
+@code{lop_fixo} are not generated by BFD, but are handled. They are
+generated by @code{mmixal}.
+
+This trivial one-label, one-instruction file:
+
+@example
+ :Main TRAP 1,2,3
+@end example
+
+can be represented this way in mmo:
+
+@example
+ 0x98090101 - lop_pre, one 32-bit word with timestamp.
+ <timestamp>
+ 0x98010002 - lop_loc, text segment, using a 64-bit address.
+ Note that mmixal does not emit this for the file above.
+ 0x00000000 - Address, high 32 bits.
+ 0x00000000 - Address, low 32 bits.
+ 0x98060002 - lop_file, 2 32-bit words for file-name.
+ 0x74657374 - "test"
+ 0x2e730000 - ".s\0\0"
+ 0x98070001 - lop_line, line 1.
+ 0x00010203 - TRAP 1,2,3
+ 0x980a00ff - lop_post, setting $255 to 0.
+ 0x00000000
+ 0x00000000
+ 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
+ 0x203a4040 @xref{Symbol-table}.
+ 0x10404020
+ 0x4d206120
+ 0x69016e00
+ 0x81000000
+ 0x980c0005 - lop_end; symbol table contained five 32-bit words.
+@end example
+@node Symbol-table, mmo section mapping, File layout, mmo
+@subsection Symbol table format
+From mmixal.w (or really, the generated mmixal.tex) in
+@url{http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz}):
+``Symbols are stored and retrieved by means of a @samp{ternary
+search trie}, following ideas of Bentley and Sedgewick. (See
+ACM--SIAM Symp.@: on Discrete Algorithms @samp{8} (1997), 360--369;
+R.@:Sedgewick, @samp{Algorithms in C} (Reading, Mass.@:
+Addison--Wesley, 1998), @samp{15.4}.) Each trie node stores a
+character, and there are branches to subtries for the cases where
+a given character is less than, equal to, or greater than the
+character in the trie. There also is a pointer to a symbol table
+entry if a symbol ends at the current node.''
+
+So it's a tree encoded as a stream of bytes. The stream of bytes
+acts on a single virtual global symbol, adding and removing
+characters and signalling complete symbol points. Here, we read
+the stream and create symbols at the completion points.
+
+First, there's a control byte @code{m}. If any of the listed bits
+in @code{m} is nonzero, we execute what stands at the right, in
+the listed order:
+
+@example
+ (MMO3_LEFT)
+ 0x40 - Traverse left trie.
+ (Read a new command byte and recurse.)
+
+ (MMO3_SYMBITS)
+ 0x2f - Read the next byte as a character and store it in the
+ current character position; increment character position.
+ Test the bits of @code{m}:
+
+ (MMO3_WCHAR)
+ 0x80 - The character is 16-bit (so read another byte,
+ merge into current character.
+
+ (MMO3_TYPEBITS)
+ 0xf - We have a complete symbol; parse the type, value
+ and serial number and do what should be done
+ with a symbol. The type and length information
+ is in j = (m & 0xf).
+
+ (MMO3_REGQUAL_BITS)
+ j == 0xf: A register variable. The following
+ byte tells which register.
+ j <= 8: An absolute symbol. Read j bytes as the
+ big-endian number the symbol equals.
+ A j = 2 with two zero bytes denotes an
+ unknown symbol.
+ j > 8: As with j <= 8, but add (0x20 << 56)
+ to the value in the following j - 8
+ bytes.
+
+ Then comes the serial number, as a variant of
+ uleb128, but better named ubeb128:
+ Read bytes and shift the previous value left 7
+ (multiply by 128). Add in the new byte, repeat
+ until a byte has bit 7 set. The serial number
+ is the computed value minus 128.
+
+ (MMO3_MIDDLE)
+ 0x20 - Traverse middle trie. (Read a new command byte
+ and recurse.) Decrement character position.
+
+ (MMO3_RIGHT)
+ 0x10 - Traverse right trie. (Read a new command byte and
+ recurse.)
+@end example
+
+Let's look again at the @code{lop_stab} for the trivial file
+(@pxref{File layout}).
+
+@example
+ 0x980b0000 - lop_stab for ":Main" = 0, serial 1.
+ 0x203a4040
+ 0x10404020
+ 0x4d206120
+ 0x69016e00
+ 0x81000000
+@end example
+
+This forms the trivial trie (note that the path between ``:'' and
+``M'' is redundant):
+
+@example
+ 203a ":"
+ 40 /
+ 40 /
+ 10 \
+ 40 /
+ 40 /
+ 204d "M"
+ 2061 "a"
+ 2069 "i"
+ 016e "n" is the last character in a full symbol, and
+ with a value represented in one byte.
+ 00 The value is 0.
+ 81 The serial number is 1.
+@end example
+
+@node mmo section mapping, , Symbol-table, mmo
+@subsection mmo section mapping
+The implementation in BFD uses special data type 80 (decimal) to
+encapsulate and describe named sections, containing e.g.@: debug
+information. If needed, any datum in the encapsulation will be
+quoted using lop_quote. First comes a 32-bit word holding the
+number of 32-bit words containing the zero-terminated zero-padded
+segment name. After the name there's a 32-bit word holding flags
+describing the section type. Then comes a 64-bit big-endian word
+with the section length (in bytes), then another with the section
+start address. Depending on the type of section, the contents
+might follow, zero-padded to 32-bit boundary. For a loadable
+section (such as data or code), the contents might follow at some
+later point, not necessarily immediately, as a lop_loc with the
+same start address as in the section description, followed by the
+contents. This in effect forms a descriptor that must be emitted
+before the actual contents. Sections described this way must not
+overlap.
+
+For areas that don't have such descriptors, synthetic sections are
+formed by BFD. Consecutive contents in the two memory areas
+@samp{0x0000@dots{}00} to @samp{0x01ff@dots{}ff} and
+@samp{0x2000@dots{}00} to @samp{0x20ff@dots{}ff} are entered in
+sections named @code{.text} and @code{.data} respectively. If an area
+is not otherwise described, but would together with a neighboring
+lower area be less than @samp{0x40000000} bytes long, it is joined
+with the lower area and the gap is zero-filled. For other cases,
+a new section is formed, named @code{.MMIX.sec.@var{n}}. Here,
+@var{n} is a number, a running count through the mmo file,
+starting at 0.
+
+A loadable section specified as:
+
+@example
+ .section secname,"ax"
+ TETRA 1,2,3,4,-1,-2009
+ BYTE 80
+@end example
+
+and linked to address @samp{0x4}, is represented by the sequence:
+
+@example
+ 0x98080050 - lop_spec 80
+ 0x00000002 - two 32-bit words for the section name
+ 0x7365636e - "secn"
+ 0x616d6500 - "ame\0"
+ 0x00000033 - flags CODE, READONLY, LOAD, ALLOC
+ 0x00000000 - high 32 bits of section length
+ 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits
+ 0x00000000 - high 32 bits of section address
+ 0x00000004 - section address is 4
+ 0x98010002 - 64 bits with address of following data
+ 0x00000000 - high 32 bits of address
+ 0x00000004 - low 32 bits: data starts at address 4
+ 0x00000001 - 1
+ 0x00000002 - 2
+ 0x00000003 - 3
+ 0x00000004 - 4
+ 0xffffffff - -1
+ 0xfffff827 - -2009
+ 0x50000000 - 80 as a byte, padded with zeros.
+@end example
+
+Note that the lop_spec wrapping does not include the section
+contents. Compare this to a non-loaded section specified as:
+
+@example
+ .section thirdsec
+ TETRA 200001,100002
+ BYTE 38,40
+@end example
+
+This, when linked to address @samp{0x200000000000001c}, is
+represented by:
+
+@example
+ 0x98080050 - lop_spec 80
+ 0x00000002 - two 32-bit words for the section name
+ 0x7365636e - "thir"
+ 0x616d6500 - "dsec"
+ 0x00000010 - flag READONLY
+ 0x00000000 - high 32 bits of section length
+ 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits
+ 0x20000000 - high 32 bits of address
+ 0x0000001c - low 32 bits of address 0x200000000000001c
+ 0x00030d41 - 200001
+ 0x000186a2 - 100002
+ 0x26280000 - 38, 40 as bytes, padded with zeros
+@end example
+
+For the latter example, the section contents must not be
+loaded in memory, and is therefore specified as part of the
+special data. The address is usually unimportant but might
+provide information for e.g.@: the DWARF 2 debugging format.
diff --git a/bfd/doc/opncls.texi b/bfd/doc/opncls.texi
new file mode 100644
index 00000000000..94f2f9fc5c1
--- /dev/null
+++ b/bfd/doc/opncls.texi
@@ -0,0 +1,372 @@
+@section Opening and closing BFDs
+
+
+@subsection Functions for opening and closing
+
+
+@findex bfd_fopen
+@subsubsection @code{bfd_fopen}
+@strong{Synopsis}
+@example
+bfd *bfd_fopen (const char *filename, const char *target,
+ const char *mode, int fd);
+@end example
+@strong{Description}@*
+Open the file @var{filename} with the target @var{target}.
+Return a pointer to the created BFD. If @var{fd} is not -1,
+then @code{fdopen} is used to open the file; otherwise, @code{fopen}
+is used. @var{mode} is passed directly to @code{fopen} or
+@code{fdopen}.
+
+Calls @code{bfd_find_target}, so @var{target} is interpreted as by
+that function.
+
+The new BFD is marked as cacheable iff @var{fd} is -1.
+
+If @code{NULL} is returned then an error has occured. Possible errors
+are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
+@code{system_call} error.
+
+@findex bfd_openr
+@subsubsection @code{bfd_openr}
+@strong{Synopsis}
+@example
+bfd *bfd_openr (const char *filename, const char *target);
+@end example
+@strong{Description}@*
+Open the file @var{filename} (using @code{fopen}) with the target
+@var{target}. Return a pointer to the created BFD.
+
+Calls @code{bfd_find_target}, so @var{target} is interpreted as by
+that function.
+
+If @code{NULL} is returned then an error has occured. Possible errors
+are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
+@code{system_call} error.
+
+@findex bfd_fdopenr
+@subsubsection @code{bfd_fdopenr}
+@strong{Synopsis}
+@example
+bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
+@end example
+@strong{Description}@*
+@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to
+@code{fopen}. It opens a BFD on a file already described by the
+@var{fd} supplied.
+
+When the file is later @code{bfd_close}d, the file descriptor will
+be closed. If the caller desires that this file descriptor be
+cached by BFD (opened as needed, closed as needed to free
+descriptors for other opens), with the supplied @var{fd} used as
+an initial file descriptor (but subject to closure at any time),
+call bfd_set_cacheable(bfd, 1) on the returned BFD. The default
+is to assume no caching; the file descriptor will remain open
+until @code{bfd_close}, and will not be affected by BFD operations
+on other files.
+
+Possible errors are @code{bfd_error_no_memory},
+@code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
+
+@findex bfd_openstreamr
+@subsubsection @code{bfd_openstreamr}
+@strong{Synopsis}
+@example
+bfd *bfd_openstreamr (const char *, const char *, void *);
+@end example
+@strong{Description}@*
+Open a BFD for read access on an existing stdio stream. When
+the BFD is passed to @code{bfd_close}, the stream will be closed.
+
+@findex bfd_openr_iovec
+@subsubsection @code{bfd_openr_iovec}
+@strong{Synopsis}
+@example
+bfd *bfd_openr_iovec (const char *filename, const char *target,
+ void *(*open) (struct bfd *nbfd,
+ void *open_closure),
+ void *open_closure,
+ file_ptr (*pread) (struct bfd *nbfd,
+ void *stream,
+ void *buf,
+ file_ptr nbytes,
+ file_ptr offset),
+ int (*close) (struct bfd *nbfd,
+ void *stream),
+ int (*stat) (struct bfd *abfd,
+ void *stream,
+ struct stat *sb));
+@end example
+@strong{Description}@*
+Create and return a BFD backed by a read-only @var{stream}.
+The @var{stream} is created using @var{open}, accessed using
+@var{pread} and destroyed using @var{close}.
+
+Calls @code{bfd_find_target}, so @var{target} is interpreted as by
+that function.
+
+Calls @var{open} (which can call @code{bfd_zalloc} and
+@code{bfd_get_filename}) to obtain the read-only stream backing
+the BFD. @var{open} either succeeds returning the
+non-@code{NULL} @var{stream}, or fails returning @code{NULL}
+(setting @code{bfd_error}).
+
+Calls @var{pread} to request @var{nbytes} of data from
+@var{stream} starting at @var{offset} (e.g., via a call to
+@code{bfd_read}). @var{pread} either succeeds returning the
+number of bytes read (which can be less than @var{nbytes} when
+end-of-file), or fails returning -1 (setting @code{bfd_error}).
+
+Calls @var{close} when the BFD is later closed using
+@code{bfd_close}. @var{close} either succeeds returning 0, or
+fails returning -1 (setting @code{bfd_error}).
+
+Calls @var{stat} to fill in a stat structure for bfd_stat,
+bfd_get_size, and bfd_get_mtime calls. @var{stat} returns 0
+on success, or returns -1 on failure (setting @code{bfd_error}).
+
+If @code{bfd_openr_iovec} returns @code{NULL} then an error has
+occurred. Possible errors are @code{bfd_error_no_memory},
+@code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
+
+@findex bfd_openw
+@subsubsection @code{bfd_openw}
+@strong{Synopsis}
+@example
+bfd *bfd_openw (const char *filename, const char *target);
+@end example
+@strong{Description}@*
+Create a BFD, associated with file @var{filename}, using the
+file format @var{target}, and return a pointer to it.
+
+Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
+@code{bfd_error_invalid_target}.
+
+@findex bfd_close
+@subsubsection @code{bfd_close}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_close (bfd *abfd);
+@end example
+@strong{Description}@*
+Close a BFD. If the BFD was open for writing, then pending
+operations are completed and the file written out and closed.
+If the created file is executable, then @code{chmod} is called
+to mark it as such.
+
+All memory attached to the BFD is released.
+
+The file descriptor associated with the BFD is closed (even
+if it was passed in to BFD by @code{bfd_fdopenr}).
+
+@strong{Returns}@*
+@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
+
+@findex bfd_close_all_done
+@subsubsection @code{bfd_close_all_done}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_close_all_done (bfd *);
+@end example
+@strong{Description}@*
+Close a BFD. Differs from @code{bfd_close} since it does not
+complete any pending operations. This routine would be used
+if the application had just used BFD for swapping and didn't
+want to use any of the writing code.
+
+If the created file is executable, then @code{chmod} is called
+to mark it as such.
+
+All memory attached to the BFD is released.
+
+@strong{Returns}@*
+@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
+
+@findex bfd_create
+@subsubsection @code{bfd_create}
+@strong{Synopsis}
+@example
+bfd *bfd_create (const char *filename, bfd *templ);
+@end example
+@strong{Description}@*
+Create a new BFD in the manner of @code{bfd_openw}, but without
+opening a file. The new BFD takes the target from the target
+used by @var{template}. The format is always set to @code{bfd_object}.
+
+@findex bfd_make_writable
+@subsubsection @code{bfd_make_writable}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_make_writable (bfd *abfd);
+@end example
+@strong{Description}@*
+Takes a BFD as created by @code{bfd_create} and converts it
+into one like as returned by @code{bfd_openw}. It does this
+by converting the BFD to BFD_IN_MEMORY. It's assumed that
+you will call @code{bfd_make_readable} on this bfd later.
+
+@strong{Returns}@*
+@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
+
+@findex bfd_make_readable
+@subsubsection @code{bfd_make_readable}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_make_readable (bfd *abfd);
+@end example
+@strong{Description}@*
+Takes a BFD as created by @code{bfd_create} and
+@code{bfd_make_writable} and converts it into one like as
+returned by @code{bfd_openr}. It does this by writing the
+contents out to the memory buffer, then reversing the
+direction.
+
+@strong{Returns}@*
+@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
+
+@findex bfd_alloc
+@subsubsection @code{bfd_alloc}
+@strong{Synopsis}
+@example
+void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
+@end example
+@strong{Description}@*
+Allocate a block of @var{wanted} bytes of memory attached to
+@code{abfd} and return a pointer to it.
+
+@findex bfd_alloc2
+@subsubsection @code{bfd_alloc2}
+@strong{Synopsis}
+@example
+void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
+@end example
+@strong{Description}@*
+Allocate a block of @var{nmemb} elements of @var{size} bytes each
+of memory attached to @code{abfd} and return a pointer to it.
+
+@findex bfd_zalloc
+@subsubsection @code{bfd_zalloc}
+@strong{Synopsis}
+@example
+void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
+@end example
+@strong{Description}@*
+Allocate a block of @var{wanted} bytes of zeroed memory
+attached to @code{abfd} and return a pointer to it.
+
+@findex bfd_zalloc2
+@subsubsection @code{bfd_zalloc2}
+@strong{Synopsis}
+@example
+void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
+@end example
+@strong{Description}@*
+Allocate a block of @var{nmemb} elements of @var{size} bytes each
+of zeroed memory attached to @code{abfd} and return a pointer to it.
+
+@findex bfd_calc_gnu_debuglink_crc32
+@subsubsection @code{bfd_calc_gnu_debuglink_crc32}
+@strong{Synopsis}
+@example
+unsigned long bfd_calc_gnu_debuglink_crc32
+ (unsigned long crc, const unsigned char *buf, bfd_size_type len);
+@end example
+@strong{Description}@*
+Computes a CRC value as used in the .gnu_debuglink section.
+Advances the previously computed @var{crc} value by computing
+and adding in the crc32 for @var{len} bytes of @var{buf}.
+
+@strong{Returns}@*
+Return the updated CRC32 value.
+
+@findex get_debug_link_info
+@subsubsection @code{get_debug_link_info}
+@strong{Synopsis}
+@example
+char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
+@end example
+@strong{Description}@*
+fetch the filename and CRC32 value for any separate debuginfo
+associated with @var{abfd}. Return NULL if no such info found,
+otherwise return filename and update @var{crc32_out}.
+
+@findex separate_debug_file_exists
+@subsubsection @code{separate_debug_file_exists}
+@strong{Synopsis}
+@example
+bfd_boolean separate_debug_file_exists
+ (char *name, unsigned long crc32);
+@end example
+@strong{Description}@*
+Checks to see if @var{name} is a file and if its contents
+match @var{crc32}.
+
+@findex find_separate_debug_file
+@subsubsection @code{find_separate_debug_file}
+@strong{Synopsis}
+@example
+char *find_separate_debug_file (bfd *abfd);
+@end example
+@strong{Description}@*
+Searches @var{abfd} for a reference to separate debugging
+information, scans various locations in the filesystem, including
+the file tree rooted at @var{debug_file_directory}, and returns a
+filename of such debugging information if the file is found and has
+matching CRC32. Returns NULL if no reference to debugging file
+exists, or file cannot be found.
+
+@findex bfd_follow_gnu_debuglink
+@subsubsection @code{bfd_follow_gnu_debuglink}
+@strong{Synopsis}
+@example
+char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
+@end example
+@strong{Description}@*
+Takes a BFD and searches it for a .gnu_debuglink section. If this
+section is found, it examines the section for the name and checksum
+of a '.debug' file containing auxiliary debugging information. It
+then searches the filesystem for this .debug file in some standard
+locations, including the directory tree rooted at @var{dir}, and if
+found returns the full filename.
+
+If @var{dir} is NULL, it will search a default path configured into
+libbfd at build time. [XXX this feature is not currently
+implemented].
+
+@strong{Returns}@*
+@code{NULL} on any errors or failure to locate the .debug file,
+otherwise a pointer to a heap-allocated string containing the
+filename. The caller is responsible for freeing this string.
+
+@findex bfd_create_gnu_debuglink_section
+@subsubsection @code{bfd_create_gnu_debuglink_section}
+@strong{Synopsis}
+@example
+struct bfd_section *bfd_create_gnu_debuglink_section
+ (bfd *abfd, const char *filename);
+@end example
+@strong{Description}@*
+Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized
+to be big enough to contain a link to the specified @var{filename}.
+
+@strong{Returns}@*
+A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is
+returned and bfd_error is set.
+
+@findex bfd_fill_in_gnu_debuglink_section
+@subsubsection @code{bfd_fill_in_gnu_debuglink_section}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_fill_in_gnu_debuglink_section
+ (bfd *abfd, struct bfd_section *sect, const char *filename);
+@end example
+@strong{Description}@*
+Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
+and fills in the contents of the section to contain a link to the
+specified @var{filename}. The filename should be relative to the
+current directory.
+
+@strong{Returns}@*
+@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned
+and bfd_error is set.
+
diff --git a/bfd/doc/reloc.texi b/bfd/doc/reloc.texi
new file mode 100644
index 00000000000..74902ae2011
--- /dev/null
+++ b/bfd/doc/reloc.texi
@@ -0,0 +1,2813 @@
+@section Relocations
+BFD maintains relocations in much the same way it maintains
+symbols: they are left alone until required, then read in
+en-masse and translated into an internal form. A common
+routine @code{bfd_perform_relocation} acts upon the
+canonical form to do the fixup.
+
+Relocations are maintained on a per section basis,
+while symbols are maintained on a per BFD basis.
+
+All that a back end has to do to fit the BFD interface is to create
+a @code{struct reloc_cache_entry} for each relocation
+in a particular section, and fill in the right bits of the structures.
+
+@menu
+* typedef arelent::
+* howto manager::
+@end menu
+
+
+@node typedef arelent, howto manager, Relocations, Relocations
+@subsection typedef arelent
+This is the structure of a relocation entry:
+
+
+@example
+
+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,
+
+ /* Unsupported relocation size requested. */
+ bfd_reloc_notsupported,
+
+ /* Unused. */
+ 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. If this type is returned, the error_message argument
+ to bfd_perform_relocation will be set. */
+ bfd_reloc_dangerous
+ @}
+ bfd_reloc_status_type;
+
+
+typedef struct reloc_cache_entry
+@{
+ /* A pointer into the canonical table of pointers. */
+ struct bfd_symbol **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. */
+ reloc_howto_type *howto;
+
+@}
+arelent;
+
+@end example
+@strong{Description}@*
+Here is a description of each of the fields within an @code{arelent}:
+
+@itemize @bullet
+
+@item
+@code{sym_ptr_ptr}
+@end itemize
+The symbol table pointer points to a pointer to the symbol
+associated with the relocation request. It is the pointer
+into the table returned by the back end's
+@code{canonicalize_symtab} action. @xref{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.
+
+@itemize @bullet
+
+@item
+@code{address}
+@end itemize
+The @code{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.
+
+@itemize @bullet
+
+@item
+@code{addend}
+@end itemize
+The @code{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:
+
+@example
+ char foo[];
+ main()
+ @{
+ return foo[0x12345678];
+ @}
+@end example
+
+Could be compiled into:
+
+@example
+ linkw fp,#-4
+ moveb @@#12345678,d0
+ extbl d0
+ unlk fp
+ rts
+@end example
+
+This could create a reloc pointing to @code{foo}, but leave the
+offset in the data, something like:
+
+@example
+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
+@end example
+
+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:
+
+@example
+ or.u r13,r0,hi16(_foo+0x12345678)
+ ld.b r2,r13,lo16(_foo+0x12345678)
+ jmp r1
+@end example
+
+This should create two relocs, both pointing to @code{_foo}, and with
+0x12340000 in their addend field. The data would consist of:
+
+@example
+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
+@end example
+
+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 @code{_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 in odd sized lumps. The designers of
+the a.out format chose to not use the data within the section
+for storing part of the offset; all the offset is kept within
+the reloc. Anything in the data should be ignored.
+
+@example
+ save %sp,-112,%sp
+ sethi %hi(_foo+0x12345678),%g2
+ ldsb [%g2+%lo(_foo+0x12345678)],%i0
+ ret
+ restore
+@end example
+
+Both relocs contain a pointer to @code{foo}, and the offsets
+contain junk.
+
+@example
+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
+@end example
+
+@itemize @bullet
+
+@item
+@code{howto}
+@end itemize
+The @code{howto} field can be imagined as a
+relocation instruction. It is a pointer to a structure which
+contains information on what to do with all of 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.
+
+@subsubsection @code{enum complain_overflow}
+Indicates what sort of overflow checking should be done when
+performing a relocation.
+
+
+@example
+
+enum complain_overflow
+@{
+ /* Do not complain on overflow. */
+ complain_overflow_dont,
+
+ /* Complain if the value overflows when considered as a signed
+ number one bit larger than the field. ie. A bitfield of N bits
+ is allowed to represent -2**n to 2**n-1. */
+ complain_overflow_bitfield,
+
+ /* Complain if the value overflows when considered as a signed
+ number. */
+ complain_overflow_signed,
+
+ /* Complain if the value overflows when considered as an
+ unsigned number. */
+ complain_overflow_unsigned
+@};
+@end example
+@subsubsection @code{reloc_howto_type}
+The @code{reloc_howto_type} is a structure which contains all the
+information that libbfd needs to know to tie up a back end's data.
+
+
+@example
+struct bfd_symbol; /* Forward declaration. */
+
+struct reloc_howto_struct
+@{
+ /* The type field has mainly a documentary use - the back end can
+ do what it wants with it, though normally the back end's
+ external idea of what a reloc number is stored
+ in this field. For example, a PC relative word relocation
+ in a coff environment has 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. To get the number of bytes operated
+ on by a type of relocation, use bfd_get_reloc_size. */
+ 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. */
+ bfd_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 accommodated (e.g., i960 callj
+ instructions). */
+ bfd_reloc_status_type (*special_function)
+ (bfd *, arelent *, struct bfd_symbol *, void *, asection *,
+ bfd *, char **);
+
+ /* The textual name of the relocation type. */
+ char *name;
+
+ /* Some formats record a relocation addend in the section contents
+ rather than with the relocation. For ELF formats this is the
+ distinction between USE_REL and USE_RELA (though the code checks
+ for USE_REL == 1/0). The value of this field is TRUE if the
+ addend is recorded with the section contents; when performing a
+ partial link (ld -r) the section contents (the data) will be
+ modified. The value of this field is FALSE if addends are
+ recorded with the relocation (in arelent.addend); when performing
+ a partial link the relocation will be modified.
+ All relocations for all ELF USE_RELA targets should set this field
+ to FALSE (values of TRUE should be looked on with suspicion).
+ However, the converse is not true: not all relocations of all ELF
+ USE_REL targets set this field to TRUE. Why this is so is peculiar
+ to each particular target. For relocs that aren't used in partial
+ links (e.g. GOT stuff) it doesn't matter what this is set to. */
+ bfd_boolean partial_inplace;
+
+ /* src_mask selects the part of the instruction (or data) to be used
+ in the relocation sum. If the target relocations don't have an
+ addend in the reloc, eg. ELF USE_REL, src_mask will normally equal
+ dst_mask to extract the addend from the section contents. If
+ relocations do have an addend in the reloc, eg. ELF USE_RELA, this
+ field should be zero. Non-zero values for ELF USE_RELA targets are
+ bogus as in those cases the value in the dst_mask part of the
+ section contents should be treated as garbage. */
+ bfd_vma src_mask;
+
+ /* dst_mask selects which parts of the instruction (or data) are
+ replaced with a relocated value. */
+ 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. */
+ bfd_boolean pcrel_offset;
+@};
+
+@end example
+@findex The HOWTO Macro
+@subsubsection @code{The HOWTO Macro}
+@strong{Description}@*
+The HOWTO define is horrible and will go away.
+@example
+#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 @}
+@end example
+
+@strong{Description}@*
+And will be replaced with the totally magic way. But for the
+moment, we are compatible, so do it this way.
+@example
+#define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \
+ HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \
+ NAME, FALSE, 0, 0, IN)
+
+@end example
+
+@strong{Description}@*
+This is used to fill in an empty howto entry in an array.
+@example
+#define EMPTY_HOWTO(C) \
+ HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \
+ NULL, FALSE, 0, 0, FALSE)
+
+@end example
+
+@strong{Description}@*
+Helper routine to turn a symbol into a relocation value.
+@example
+#define HOWTO_PREPARE(relocation, symbol) \
+ @{ \
+ if (symbol != NULL) \
+ @{ \
+ if (bfd_is_com_section (symbol->section)) \
+ @{ \
+ relocation = 0; \
+ @} \
+ else \
+ @{ \
+ relocation = symbol->value; \
+ @} \
+ @} \
+ @}
+
+@end example
+
+@findex bfd_get_reloc_size
+@subsubsection @code{bfd_get_reloc_size}
+@strong{Synopsis}
+@example
+unsigned int bfd_get_reloc_size (reloc_howto_type *);
+@end example
+@strong{Description}@*
+For a reloc_howto_type that operates on a fixed number of bytes,
+this returns the number of bytes operated on.
+
+@findex arelent_chain
+@subsubsection @code{arelent_chain}
+@strong{Description}@*
+How relocs are tied together in an @code{asection}:
+@example
+typedef struct relent_chain
+@{
+ arelent relent;
+ struct relent_chain *next;
+@}
+arelent_chain;
+
+@end example
+
+@findex bfd_check_overflow
+@subsubsection @code{bfd_check_overflow}
+@strong{Synopsis}
+@example
+bfd_reloc_status_type bfd_check_overflow
+ (enum complain_overflow how,
+ unsigned int bitsize,
+ unsigned int rightshift,
+ unsigned int addrsize,
+ bfd_vma relocation);
+@end example
+@strong{Description}@*
+Perform overflow checking on @var{relocation} which has
+@var{bitsize} significant bits and will be shifted right by
+@var{rightshift} bits, on a machine with addresses containing
+@var{addrsize} significant bits. The result is either of
+@code{bfd_reloc_ok} or @code{bfd_reloc_overflow}.
+
+@findex bfd_perform_relocation
+@subsubsection @code{bfd_perform_relocation}
+@strong{Synopsis}
+@example
+bfd_reloc_status_type bfd_perform_relocation
+ (bfd *abfd,
+ arelent *reloc_entry,
+ void *data,
+ asection *input_section,
+ bfd *output_bfd,
+ char **error_message);
+@end example
+@strong{Description}@*
+If @var{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 @var{error_message} argument is set to an error message if
+this return @code{bfd_reloc_dangerous}.
+
+@findex bfd_install_relocation
+@subsubsection @code{bfd_install_relocation}
+@strong{Synopsis}
+@example
+bfd_reloc_status_type bfd_install_relocation
+ (bfd *abfd,
+ arelent *reloc_entry,
+ void *data, bfd_vma data_start,
+ asection *input_section,
+ char **error_message);
+@end example
+@strong{Description}@*
+This looks remarkably like @code{bfd_perform_relocation}, except it
+does not expect that the section contents have been filled in.
+I.e., it's suitable for use when creating, rather than applying
+a relocation.
+
+For now, this function should be considered reserved for the
+assembler.
+
+
+@node howto manager, , typedef arelent, Relocations
+@subsection 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.
+
+@findex bfd_reloc_code_type
+@subsubsection @code{bfd_reloc_code_type}
+@strong{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 @code{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.
+
+Here are the possible values for @code{enum bfd_reloc_code_real}:
+
+@deffn {} BFD_RELOC_64
+@deffnx {} BFD_RELOC_32
+@deffnx {} BFD_RELOC_26
+@deffnx {} BFD_RELOC_24
+@deffnx {} BFD_RELOC_16
+@deffnx {} BFD_RELOC_14
+@deffnx {} BFD_RELOC_8
+Basic absolute relocations of N bits.
+@end deffn
+@deffn {} BFD_RELOC_64_PCREL
+@deffnx {} BFD_RELOC_32_PCREL
+@deffnx {} BFD_RELOC_24_PCREL
+@deffnx {} BFD_RELOC_16_PCREL
+@deffnx {} BFD_RELOC_12_PCREL
+@deffnx {} BFD_RELOC_8_PCREL
+PC-relative relocations. Sometimes these are relative to the address
+of the relocation itself; sometimes they are relative to the start of
+the section containing the relocation. It depends on the specific target.
+
+The 24-bit relocation is used in some Intel 960 configurations.
+@end deffn
+@deffn {} BFD_RELOC_32_SECREL
+Section relative relocations. Some targets need this for DWARF2.
+@end deffn
+@deffn {} BFD_RELOC_32_GOT_PCREL
+@deffnx {} BFD_RELOC_16_GOT_PCREL
+@deffnx {} BFD_RELOC_8_GOT_PCREL
+@deffnx {} BFD_RELOC_32_GOTOFF
+@deffnx {} BFD_RELOC_16_GOTOFF
+@deffnx {} BFD_RELOC_LO16_GOTOFF
+@deffnx {} BFD_RELOC_HI16_GOTOFF
+@deffnx {} BFD_RELOC_HI16_S_GOTOFF
+@deffnx {} BFD_RELOC_8_GOTOFF
+@deffnx {} BFD_RELOC_64_PLT_PCREL
+@deffnx {} BFD_RELOC_32_PLT_PCREL
+@deffnx {} BFD_RELOC_24_PLT_PCREL
+@deffnx {} BFD_RELOC_16_PLT_PCREL
+@deffnx {} BFD_RELOC_8_PLT_PCREL
+@deffnx {} BFD_RELOC_64_PLTOFF
+@deffnx {} BFD_RELOC_32_PLTOFF
+@deffnx {} BFD_RELOC_16_PLTOFF
+@deffnx {} BFD_RELOC_LO16_PLTOFF
+@deffnx {} BFD_RELOC_HI16_PLTOFF
+@deffnx {} BFD_RELOC_HI16_S_PLTOFF
+@deffnx {} BFD_RELOC_8_PLTOFF
+For ELF.
+@end deffn
+@deffn {} BFD_RELOC_68K_GLOB_DAT
+@deffnx {} BFD_RELOC_68K_JMP_SLOT
+@deffnx {} BFD_RELOC_68K_RELATIVE
+@deffnx {} BFD_RELOC_68K_TLS_GD32
+@deffnx {} BFD_RELOC_68K_TLS_GD16
+@deffnx {} BFD_RELOC_68K_TLS_GD8
+@deffnx {} BFD_RELOC_68K_TLS_LDM32
+@deffnx {} BFD_RELOC_68K_TLS_LDM16
+@deffnx {} BFD_RELOC_68K_TLS_LDM8
+@deffnx {} BFD_RELOC_68K_TLS_LDO32
+@deffnx {} BFD_RELOC_68K_TLS_LDO16
+@deffnx {} BFD_RELOC_68K_TLS_LDO8
+@deffnx {} BFD_RELOC_68K_TLS_IE32
+@deffnx {} BFD_RELOC_68K_TLS_IE16
+@deffnx {} BFD_RELOC_68K_TLS_IE8
+@deffnx {} BFD_RELOC_68K_TLS_LE32
+@deffnx {} BFD_RELOC_68K_TLS_LE16
+@deffnx {} BFD_RELOC_68K_TLS_LE8
+Relocations used by 68K ELF.
+@end deffn
+@deffn {} BFD_RELOC_32_BASEREL
+@deffnx {} BFD_RELOC_16_BASEREL
+@deffnx {} BFD_RELOC_LO16_BASEREL
+@deffnx {} BFD_RELOC_HI16_BASEREL
+@deffnx {} BFD_RELOC_HI16_S_BASEREL
+@deffnx {} BFD_RELOC_8_BASEREL
+@deffnx {} BFD_RELOC_RVA
+Linkage-table relative.
+@end deffn
+@deffn {} BFD_RELOC_8_FFnn
+Absolute 8-bit relocation, but used to form an address like 0xFFnn.
+@end deffn
+@deffn {} BFD_RELOC_32_PCREL_S2
+@deffnx {} BFD_RELOC_16_PCREL_S2
+@deffnx {} BFD_RELOC_23_PCREL_S2
+These PC-relative relocations are stored as word displacements --
+i.e., byte displacements shifted right two bits. The 30-bit word
+displacement (<<32_PCREL_S2>> -- 32 bits, shifted 2) is used on the
+SPARC. (SPARC tools generally refer to this as <<WDISP30>>.) The
+signed 16-bit displacement is used on the MIPS, and the 23-bit
+displacement is used on the Alpha.
+@end deffn
+@deffn {} BFD_RELOC_HI22
+@deffnx {} BFD_RELOC_LO10
+High 22 bits and low 10 bits of 32-bit value, placed into lower bits of
+the target word. These are used on the SPARC.
+@end deffn
+@deffn {} BFD_RELOC_GPREL16
+@deffnx {} BFD_RELOC_GPREL32
+For systems that allocate a Global Pointer register, these are
+displacements off that register. These relocation types are
+handled specially, because the value the register will have is
+decided relatively late.
+@end deffn
+@deffn {} BFD_RELOC_I960_CALLJ
+Reloc types used for i960/b.out.
+@end deffn
+@deffn {} BFD_RELOC_NONE
+@deffnx {} BFD_RELOC_SPARC_WDISP22
+@deffnx {} BFD_RELOC_SPARC22
+@deffnx {} BFD_RELOC_SPARC13
+@deffnx {} BFD_RELOC_SPARC_GOT10
+@deffnx {} BFD_RELOC_SPARC_GOT13
+@deffnx {} BFD_RELOC_SPARC_GOT22
+@deffnx {} BFD_RELOC_SPARC_PC10
+@deffnx {} BFD_RELOC_SPARC_PC22
+@deffnx {} BFD_RELOC_SPARC_WPLT30
+@deffnx {} BFD_RELOC_SPARC_COPY
+@deffnx {} BFD_RELOC_SPARC_GLOB_DAT
+@deffnx {} BFD_RELOC_SPARC_JMP_SLOT
+@deffnx {} BFD_RELOC_SPARC_RELATIVE
+@deffnx {} BFD_RELOC_SPARC_UA16
+@deffnx {} BFD_RELOC_SPARC_UA32
+@deffnx {} BFD_RELOC_SPARC_UA64
+@deffnx {} BFD_RELOC_SPARC_GOTDATA_HIX22
+@deffnx {} BFD_RELOC_SPARC_GOTDATA_LOX10
+@deffnx {} BFD_RELOC_SPARC_GOTDATA_OP_HIX22
+@deffnx {} BFD_RELOC_SPARC_GOTDATA_OP_LOX10
+@deffnx {} BFD_RELOC_SPARC_GOTDATA_OP
+SPARC ELF relocations. There is probably some overlap with other
+relocation types already defined.
+@end deffn
+@deffn {} BFD_RELOC_SPARC_BASE13
+@deffnx {} BFD_RELOC_SPARC_BASE22
+I think these are specific to SPARC a.out (e.g., Sun 4).
+@end deffn
+@deffn {} BFD_RELOC_SPARC_64
+@deffnx {} BFD_RELOC_SPARC_10
+@deffnx {} BFD_RELOC_SPARC_11
+@deffnx {} BFD_RELOC_SPARC_OLO10
+@deffnx {} BFD_RELOC_SPARC_HH22
+@deffnx {} BFD_RELOC_SPARC_HM10
+@deffnx {} BFD_RELOC_SPARC_LM22
+@deffnx {} BFD_RELOC_SPARC_PC_HH22
+@deffnx {} BFD_RELOC_SPARC_PC_HM10
+@deffnx {} BFD_RELOC_SPARC_PC_LM22
+@deffnx {} BFD_RELOC_SPARC_WDISP16
+@deffnx {} BFD_RELOC_SPARC_WDISP19
+@deffnx {} BFD_RELOC_SPARC_7
+@deffnx {} BFD_RELOC_SPARC_6
+@deffnx {} BFD_RELOC_SPARC_5
+@deffnx {} BFD_RELOC_SPARC_DISP64
+@deffnx {} BFD_RELOC_SPARC_PLT32
+@deffnx {} BFD_RELOC_SPARC_PLT64
+@deffnx {} BFD_RELOC_SPARC_HIX22
+@deffnx {} BFD_RELOC_SPARC_LOX10
+@deffnx {} BFD_RELOC_SPARC_H44
+@deffnx {} BFD_RELOC_SPARC_M44
+@deffnx {} BFD_RELOC_SPARC_L44
+@deffnx {} BFD_RELOC_SPARC_REGISTER
+SPARC64 relocations
+@end deffn
+@deffn {} BFD_RELOC_SPARC_REV32
+SPARC little endian relocation
+@end deffn
+@deffn {} BFD_RELOC_SPARC_TLS_GD_HI22
+@deffnx {} BFD_RELOC_SPARC_TLS_GD_LO10
+@deffnx {} BFD_RELOC_SPARC_TLS_GD_ADD
+@deffnx {} BFD_RELOC_SPARC_TLS_GD_CALL
+@deffnx {} BFD_RELOC_SPARC_TLS_LDM_HI22
+@deffnx {} BFD_RELOC_SPARC_TLS_LDM_LO10
+@deffnx {} BFD_RELOC_SPARC_TLS_LDM_ADD
+@deffnx {} BFD_RELOC_SPARC_TLS_LDM_CALL
+@deffnx {} BFD_RELOC_SPARC_TLS_LDO_HIX22
+@deffnx {} BFD_RELOC_SPARC_TLS_LDO_LOX10
+@deffnx {} BFD_RELOC_SPARC_TLS_LDO_ADD
+@deffnx {} BFD_RELOC_SPARC_TLS_IE_HI22
+@deffnx {} BFD_RELOC_SPARC_TLS_IE_LO10
+@deffnx {} BFD_RELOC_SPARC_TLS_IE_LD
+@deffnx {} BFD_RELOC_SPARC_TLS_IE_LDX
+@deffnx {} BFD_RELOC_SPARC_TLS_IE_ADD
+@deffnx {} BFD_RELOC_SPARC_TLS_LE_HIX22
+@deffnx {} BFD_RELOC_SPARC_TLS_LE_LOX10
+@deffnx {} BFD_RELOC_SPARC_TLS_DTPMOD32
+@deffnx {} BFD_RELOC_SPARC_TLS_DTPMOD64
+@deffnx {} BFD_RELOC_SPARC_TLS_DTPOFF32
+@deffnx {} BFD_RELOC_SPARC_TLS_DTPOFF64
+@deffnx {} BFD_RELOC_SPARC_TLS_TPOFF32
+@deffnx {} BFD_RELOC_SPARC_TLS_TPOFF64
+SPARC TLS relocations
+@end deffn
+@deffn {} BFD_RELOC_SPU_IMM7
+@deffnx {} BFD_RELOC_SPU_IMM8
+@deffnx {} BFD_RELOC_SPU_IMM10
+@deffnx {} BFD_RELOC_SPU_IMM10W
+@deffnx {} BFD_RELOC_SPU_IMM16
+@deffnx {} BFD_RELOC_SPU_IMM16W
+@deffnx {} BFD_RELOC_SPU_IMM18
+@deffnx {} BFD_RELOC_SPU_PCREL9a
+@deffnx {} BFD_RELOC_SPU_PCREL9b
+@deffnx {} BFD_RELOC_SPU_PCREL16
+@deffnx {} BFD_RELOC_SPU_LO16
+@deffnx {} BFD_RELOC_SPU_HI16
+@deffnx {} BFD_RELOC_SPU_PPU32
+@deffnx {} BFD_RELOC_SPU_PPU64
+@deffnx {} BFD_RELOC_SPU_ADD_PIC
+SPU Relocations.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPDISP_HI16
+Alpha ECOFF and ELF relocations. Some of these treat the symbol or
+"addend" in some special way.
+For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when
+writing; when reading, it will be the absolute section symbol. The
+addend is the displacement in bytes of the "lda" instruction from
+the "ldah" instruction (which is at the address of this reloc).
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPDISP_LO16
+For GPDISP_LO16 ("ignore") relocations, the symbol is handled as
+with GPDISP_HI16 relocs. The addend is ignored when writing the
+relocations out, and is filled in with the file's GP value on
+reading, for convenience.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPDISP
+The ELF GPDISP relocation is exactly the same as the GPDISP_HI16
+relocation except that there is no accompanying GPDISP_LO16
+relocation.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_LITERAL
+@deffnx {} BFD_RELOC_ALPHA_ELF_LITERAL
+@deffnx {} BFD_RELOC_ALPHA_LITUSE
+The Alpha LITERAL/LITUSE relocs are produced by a symbol reference;
+the assembler turns it into a LDQ instruction to load the address of
+the symbol, and then fills in a register in the real instruction.
+
+The LITERAL reloc, at the LDQ instruction, refers to the .lita
+section symbol. The addend is ignored when writing, but is filled
+in with the file's GP value on reading, for convenience, as with the
+GPDISP_LO16 reloc.
+
+The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16.
+It should refer to the symbol to be referenced, as with 16_GOTOFF,
+but it generates output not based on the position within the .got
+section, but relative to the GP value chosen for the file during the
+final link stage.
+
+The LITUSE reloc, on the instruction using the loaded address, gives
+information to the linker that it might be able to use to optimize
+away some literal section references. The symbol is ignored (read
+as the absolute section symbol), and the "addend" indicates the type
+of instruction using the register:
+1 - "memory" fmt insn
+2 - byte-manipulation (byte offset reg)
+3 - jsr (target of branch)
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_HINT
+The HINT relocation indicates a value that should be filled into the
+"hint" field of a jmp/jsr/ret instruction, for possible branch-
+prediction logic which may be provided on some processors.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_LINKAGE
+The LINKAGE relocation outputs a linkage pair in the object file,
+which is filled by the linker.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_CODEADDR
+The CODEADDR relocation outputs a STO_CA in the object file,
+which is filled by the linker.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_GPREL_HI16
+@deffnx {} BFD_RELOC_ALPHA_GPREL_LO16
+The GPREL_HI/LO relocations together form a 32-bit offset from the
+GP register.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_BRSGP
+Like BFD_RELOC_23_PCREL_S2, except that the source and target must
+share a common GP, and the target address is adjusted for
+STO_ALPHA_STD_GPLOAD.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_NOP
+The NOP relocation outputs a NOP if the longword displacement
+between two procedure entry points is < 2^21.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_BSR
+The BSR relocation outputs a BSR if the longword displacement
+between two procedure entry points is < 2^21.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_LDA
+The LDA relocation outputs a LDA if the longword displacement
+between two procedure entry points is < 2^16.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_BOH
+The BOH relocation outputs a BSR if the longword displacement
+between two procedure entry points is < 2^21, or else a hint.
+@end deffn
+@deffn {} BFD_RELOC_ALPHA_TLSGD
+@deffnx {} BFD_RELOC_ALPHA_TLSLDM
+@deffnx {} BFD_RELOC_ALPHA_DTPMOD64
+@deffnx {} BFD_RELOC_ALPHA_GOTDTPREL16
+@deffnx {} BFD_RELOC_ALPHA_DTPREL64
+@deffnx {} BFD_RELOC_ALPHA_DTPREL_HI16
+@deffnx {} BFD_RELOC_ALPHA_DTPREL_LO16
+@deffnx {} BFD_RELOC_ALPHA_DTPREL16
+@deffnx {} BFD_RELOC_ALPHA_GOTTPREL16
+@deffnx {} BFD_RELOC_ALPHA_TPREL64
+@deffnx {} BFD_RELOC_ALPHA_TPREL_HI16
+@deffnx {} BFD_RELOC_ALPHA_TPREL_LO16
+@deffnx {} BFD_RELOC_ALPHA_TPREL16
+Alpha thread-local storage relocations.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_JMP
+Bits 27..2 of the relocation address shifted right 2 bits;
+simple reloc otherwise.
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_JMP
+The MIPS16 jump instruction.
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_GPREL
+MIPS16 GP relative reloc.
+@end deffn
+@deffn {} BFD_RELOC_HI16
+High 16 bits of 32-bit value; simple reloc.
+@end deffn
+@deffn {} BFD_RELOC_HI16_S
+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.
+@end deffn
+@deffn {} BFD_RELOC_LO16
+Low 16 bits.
+@end deffn
+@deffn {} BFD_RELOC_HI16_PCREL
+High 16 bits of 32-bit pc-relative value
+@end deffn
+@deffn {} BFD_RELOC_HI16_S_PCREL
+High 16 bits of 32-bit pc-relative value, adjusted
+@end deffn
+@deffn {} BFD_RELOC_LO16_PCREL
+Low 16 bits of pc-relative value
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_GOT16
+@deffnx {} BFD_RELOC_MIPS16_CALL16
+Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of
+16-bit immediate fields
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_HI16
+MIPS16 high 16 bits of 32-bit value.
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_HI16_S
+MIPS16 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.
+@end deffn
+@deffn {} BFD_RELOC_MIPS16_LO16
+MIPS16 low 16 bits.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_LITERAL
+Relocation against a MIPS literal section.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_GOT16
+@deffnx {} BFD_RELOC_MIPS_CALL16
+@deffnx {} BFD_RELOC_MIPS_GOT_HI16
+@deffnx {} BFD_RELOC_MIPS_GOT_LO16
+@deffnx {} BFD_RELOC_MIPS_CALL_HI16
+@deffnx {} BFD_RELOC_MIPS_CALL_LO16
+@deffnx {} BFD_RELOC_MIPS_SUB
+@deffnx {} BFD_RELOC_MIPS_GOT_PAGE
+@deffnx {} BFD_RELOC_MIPS_GOT_OFST
+@deffnx {} BFD_RELOC_MIPS_GOT_DISP
+@deffnx {} BFD_RELOC_MIPS_SHIFT5
+@deffnx {} BFD_RELOC_MIPS_SHIFT6
+@deffnx {} BFD_RELOC_MIPS_INSERT_A
+@deffnx {} BFD_RELOC_MIPS_INSERT_B
+@deffnx {} BFD_RELOC_MIPS_DELETE
+@deffnx {} BFD_RELOC_MIPS_HIGHEST
+@deffnx {} BFD_RELOC_MIPS_HIGHER
+@deffnx {} BFD_RELOC_MIPS_SCN_DISP
+@deffnx {} BFD_RELOC_MIPS_REL16
+@deffnx {} BFD_RELOC_MIPS_RELGOT
+@deffnx {} BFD_RELOC_MIPS_JALR
+@deffnx {} BFD_RELOC_MIPS_TLS_DTPMOD32
+@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL32
+@deffnx {} BFD_RELOC_MIPS_TLS_DTPMOD64
+@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL64
+@deffnx {} BFD_RELOC_MIPS_TLS_GD
+@deffnx {} BFD_RELOC_MIPS_TLS_LDM
+@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL_HI16
+@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL_LO16
+@deffnx {} BFD_RELOC_MIPS_TLS_GOTTPREL
+@deffnx {} BFD_RELOC_MIPS_TLS_TPREL32
+@deffnx {} BFD_RELOC_MIPS_TLS_TPREL64
+@deffnx {} BFD_RELOC_MIPS_TLS_TPREL_HI16
+@deffnx {} BFD_RELOC_MIPS_TLS_TPREL_LO16
+MIPS ELF relocations.
+@end deffn
+@deffn {} BFD_RELOC_MIPS_COPY
+@deffnx {} BFD_RELOC_MIPS_JUMP_SLOT
+MIPS ELF relocations (VxWorks and PLT extensions).
+@end deffn
+@deffn {} BFD_RELOC_MOXIE_10_PCREL
+Moxie ELF relocations.
+@end deffn
+@deffn {} BFD_RELOC_FRV_LABEL16
+@deffnx {} BFD_RELOC_FRV_LABEL24
+@deffnx {} BFD_RELOC_FRV_LO16
+@deffnx {} BFD_RELOC_FRV_HI16
+@deffnx {} BFD_RELOC_FRV_GPREL12
+@deffnx {} BFD_RELOC_FRV_GPRELU12
+@deffnx {} BFD_RELOC_FRV_GPREL32
+@deffnx {} BFD_RELOC_FRV_GPRELHI
+@deffnx {} BFD_RELOC_FRV_GPRELLO
+@deffnx {} BFD_RELOC_FRV_GOT12
+@deffnx {} BFD_RELOC_FRV_GOTHI
+@deffnx {} BFD_RELOC_FRV_GOTLO
+@deffnx {} BFD_RELOC_FRV_FUNCDESC
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOT12
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTHI
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTLO
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_VALUE
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTOFF12
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTOFFHI
+@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTOFFLO
+@deffnx {} BFD_RELOC_FRV_GOTOFF12
+@deffnx {} BFD_RELOC_FRV_GOTOFFHI
+@deffnx {} BFD_RELOC_FRV_GOTOFFLO
+@deffnx {} BFD_RELOC_FRV_GETTLSOFF
+@deffnx {} BFD_RELOC_FRV_TLSDESC_VALUE
+@deffnx {} BFD_RELOC_FRV_GOTTLSDESC12
+@deffnx {} BFD_RELOC_FRV_GOTTLSDESCHI
+@deffnx {} BFD_RELOC_FRV_GOTTLSDESCLO
+@deffnx {} BFD_RELOC_FRV_TLSMOFF12
+@deffnx {} BFD_RELOC_FRV_TLSMOFFHI
+@deffnx {} BFD_RELOC_FRV_TLSMOFFLO
+@deffnx {} BFD_RELOC_FRV_GOTTLSOFF12
+@deffnx {} BFD_RELOC_FRV_GOTTLSOFFHI
+@deffnx {} BFD_RELOC_FRV_GOTTLSOFFLO
+@deffnx {} BFD_RELOC_FRV_TLSOFF
+@deffnx {} BFD_RELOC_FRV_TLSDESC_RELAX
+@deffnx {} BFD_RELOC_FRV_GETTLSOFF_RELAX
+@deffnx {} BFD_RELOC_FRV_TLSOFF_RELAX
+@deffnx {} BFD_RELOC_FRV_TLSMOFF
+Fujitsu Frv Relocations.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_GOTOFF24
+This is a 24bit GOT-relative reloc for the mn10300.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_GOT32
+This is a 32bit GOT-relative reloc for the mn10300, offset by two bytes
+in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_GOT24
+This is a 24bit GOT-relative reloc for the mn10300, offset by two bytes
+in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_GOT16
+This is a 16bit GOT-relative reloc for the mn10300, offset by two bytes
+in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_COPY
+Copy symbol at runtime.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_GLOB_DAT
+Create GOT entry.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_JMP_SLOT
+Create PLT entry.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_RELATIVE
+Adjust by program base.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_SYM_DIFF
+Together with another reloc targeted at the same location,
+allows for a value that is the difference of two symbols
+in the same section.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_ALIGN
+The addend of this reloc is an alignment power that must
+be honoured at the offset's location, regardless of linker
+relaxation.
+@end deffn
+@deffn {} BFD_RELOC_386_GOT32
+@deffnx {} BFD_RELOC_386_PLT32
+@deffnx {} BFD_RELOC_386_COPY
+@deffnx {} BFD_RELOC_386_GLOB_DAT
+@deffnx {} BFD_RELOC_386_JUMP_SLOT
+@deffnx {} BFD_RELOC_386_RELATIVE
+@deffnx {} BFD_RELOC_386_GOTOFF
+@deffnx {} BFD_RELOC_386_GOTPC
+@deffnx {} BFD_RELOC_386_TLS_TPOFF
+@deffnx {} BFD_RELOC_386_TLS_IE
+@deffnx {} BFD_RELOC_386_TLS_GOTIE
+@deffnx {} BFD_RELOC_386_TLS_LE
+@deffnx {} BFD_RELOC_386_TLS_GD
+@deffnx {} BFD_RELOC_386_TLS_LDM
+@deffnx {} BFD_RELOC_386_TLS_LDO_32
+@deffnx {} BFD_RELOC_386_TLS_IE_32
+@deffnx {} BFD_RELOC_386_TLS_LE_32
+@deffnx {} BFD_RELOC_386_TLS_DTPMOD32
+@deffnx {} BFD_RELOC_386_TLS_DTPOFF32
+@deffnx {} BFD_RELOC_386_TLS_TPOFF32
+@deffnx {} BFD_RELOC_386_TLS_GOTDESC
+@deffnx {} BFD_RELOC_386_TLS_DESC_CALL
+@deffnx {} BFD_RELOC_386_TLS_DESC
+@deffnx {} BFD_RELOC_386_IRELATIVE
+i386/elf relocations
+@end deffn
+@deffn {} BFD_RELOC_X86_64_GOT32
+@deffnx {} BFD_RELOC_X86_64_PLT32
+@deffnx {} BFD_RELOC_X86_64_COPY
+@deffnx {} BFD_RELOC_X86_64_GLOB_DAT
+@deffnx {} BFD_RELOC_X86_64_JUMP_SLOT
+@deffnx {} BFD_RELOC_X86_64_RELATIVE
+@deffnx {} BFD_RELOC_X86_64_GOTPCREL
+@deffnx {} BFD_RELOC_X86_64_32S
+@deffnx {} BFD_RELOC_X86_64_DTPMOD64
+@deffnx {} BFD_RELOC_X86_64_DTPOFF64
+@deffnx {} BFD_RELOC_X86_64_TPOFF64
+@deffnx {} BFD_RELOC_X86_64_TLSGD
+@deffnx {} BFD_RELOC_X86_64_TLSLD
+@deffnx {} BFD_RELOC_X86_64_DTPOFF32
+@deffnx {} BFD_RELOC_X86_64_GOTTPOFF
+@deffnx {} BFD_RELOC_X86_64_TPOFF32
+@deffnx {} BFD_RELOC_X86_64_GOTOFF64
+@deffnx {} BFD_RELOC_X86_64_GOTPC32
+@deffnx {} BFD_RELOC_X86_64_GOT64
+@deffnx {} BFD_RELOC_X86_64_GOTPCREL64
+@deffnx {} BFD_RELOC_X86_64_GOTPC64
+@deffnx {} BFD_RELOC_X86_64_GOTPLT64
+@deffnx {} BFD_RELOC_X86_64_PLTOFF64
+@deffnx {} BFD_RELOC_X86_64_GOTPC32_TLSDESC
+@deffnx {} BFD_RELOC_X86_64_TLSDESC_CALL
+@deffnx {} BFD_RELOC_X86_64_TLSDESC
+@deffnx {} BFD_RELOC_X86_64_IRELATIVE
+x86-64/elf relocations
+@end deffn
+@deffn {} BFD_RELOC_NS32K_IMM_8
+@deffnx {} BFD_RELOC_NS32K_IMM_16
+@deffnx {} BFD_RELOC_NS32K_IMM_32
+@deffnx {} BFD_RELOC_NS32K_IMM_8_PCREL
+@deffnx {} BFD_RELOC_NS32K_IMM_16_PCREL
+@deffnx {} BFD_RELOC_NS32K_IMM_32_PCREL
+@deffnx {} BFD_RELOC_NS32K_DISP_8
+@deffnx {} BFD_RELOC_NS32K_DISP_16
+@deffnx {} BFD_RELOC_NS32K_DISP_32
+@deffnx {} BFD_RELOC_NS32K_DISP_8_PCREL
+@deffnx {} BFD_RELOC_NS32K_DISP_16_PCREL
+@deffnx {} BFD_RELOC_NS32K_DISP_32_PCREL
+ns32k relocations
+@end deffn
+@deffn {} BFD_RELOC_PDP11_DISP_8_PCREL
+@deffnx {} BFD_RELOC_PDP11_DISP_6_PCREL
+PDP11 relocations
+@end deffn
+@deffn {} BFD_RELOC_PJ_CODE_HI16
+@deffnx {} BFD_RELOC_PJ_CODE_LO16
+@deffnx {} BFD_RELOC_PJ_CODE_DIR16
+@deffnx {} BFD_RELOC_PJ_CODE_DIR32
+@deffnx {} BFD_RELOC_PJ_CODE_REL16
+@deffnx {} BFD_RELOC_PJ_CODE_REL32
+Picojava relocs. Not all of these appear in object files.
+@end deffn
+@deffn {} BFD_RELOC_PPC_B26
+@deffnx {} BFD_RELOC_PPC_BA26
+@deffnx {} BFD_RELOC_PPC_TOC16
+@deffnx {} BFD_RELOC_PPC_B16
+@deffnx {} BFD_RELOC_PPC_B16_BRTAKEN
+@deffnx {} BFD_RELOC_PPC_B16_BRNTAKEN
+@deffnx {} BFD_RELOC_PPC_BA16
+@deffnx {} BFD_RELOC_PPC_BA16_BRTAKEN
+@deffnx {} BFD_RELOC_PPC_BA16_BRNTAKEN
+@deffnx {} BFD_RELOC_PPC_COPY
+@deffnx {} BFD_RELOC_PPC_GLOB_DAT
+@deffnx {} BFD_RELOC_PPC_JMP_SLOT
+@deffnx {} BFD_RELOC_PPC_RELATIVE
+@deffnx {} BFD_RELOC_PPC_LOCAL24PC
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR32
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_LO
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HI
+@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HA
+@deffnx {} BFD_RELOC_PPC_EMB_SDAI16
+@deffnx {} BFD_RELOC_PPC_EMB_SDA2I16
+@deffnx {} BFD_RELOC_PPC_EMB_SDA2REL
+@deffnx {} BFD_RELOC_PPC_EMB_SDA21
+@deffnx {} BFD_RELOC_PPC_EMB_MRKREF
+@deffnx {} BFD_RELOC_PPC_EMB_RELSEC16
+@deffnx {} BFD_RELOC_PPC_EMB_RELST_LO
+@deffnx {} BFD_RELOC_PPC_EMB_RELST_HI
+@deffnx {} BFD_RELOC_PPC_EMB_RELST_HA
+@deffnx {} BFD_RELOC_PPC_EMB_BIT_FLD
+@deffnx {} BFD_RELOC_PPC_EMB_RELSDA
+@deffnx {} BFD_RELOC_PPC64_HIGHER
+@deffnx {} BFD_RELOC_PPC64_HIGHER_S
+@deffnx {} BFD_RELOC_PPC64_HIGHEST
+@deffnx {} BFD_RELOC_PPC64_HIGHEST_S
+@deffnx {} BFD_RELOC_PPC64_TOC16_LO
+@deffnx {} BFD_RELOC_PPC64_TOC16_HI
+@deffnx {} BFD_RELOC_PPC64_TOC16_HA
+@deffnx {} BFD_RELOC_PPC64_TOC
+@deffnx {} BFD_RELOC_PPC64_PLTGOT16
+@deffnx {} BFD_RELOC_PPC64_PLTGOT16_LO
+@deffnx {} BFD_RELOC_PPC64_PLTGOT16_HI
+@deffnx {} BFD_RELOC_PPC64_PLTGOT16_HA
+@deffnx {} BFD_RELOC_PPC64_ADDR16_DS
+@deffnx {} BFD_RELOC_PPC64_ADDR16_LO_DS
+@deffnx {} BFD_RELOC_PPC64_GOT16_DS
+@deffnx {} BFD_RELOC_PPC64_GOT16_LO_DS
+@deffnx {} BFD_RELOC_PPC64_PLT16_LO_DS
+@deffnx {} BFD_RELOC_PPC64_SECTOFF_DS
+@deffnx {} BFD_RELOC_PPC64_SECTOFF_LO_DS
+@deffnx {} BFD_RELOC_PPC64_TOC16_DS
+@deffnx {} BFD_RELOC_PPC64_TOC16_LO_DS
+@deffnx {} BFD_RELOC_PPC64_PLTGOT16_DS
+@deffnx {} BFD_RELOC_PPC64_PLTGOT16_LO_DS
+Power(rs6000) and PowerPC relocations.
+@end deffn
+@deffn {} BFD_RELOC_PPC_TLS
+@deffnx {} BFD_RELOC_PPC_TLSGD
+@deffnx {} BFD_RELOC_PPC_TLSLD
+@deffnx {} BFD_RELOC_PPC_DTPMOD
+@deffnx {} BFD_RELOC_PPC_TPREL16
+@deffnx {} BFD_RELOC_PPC_TPREL16_LO
+@deffnx {} BFD_RELOC_PPC_TPREL16_HI
+@deffnx {} BFD_RELOC_PPC_TPREL16_HA
+@deffnx {} BFD_RELOC_PPC_TPREL
+@deffnx {} BFD_RELOC_PPC_DTPREL16
+@deffnx {} BFD_RELOC_PPC_DTPREL16_LO
+@deffnx {} BFD_RELOC_PPC_DTPREL16_HI
+@deffnx {} BFD_RELOC_PPC_DTPREL16_HA
+@deffnx {} BFD_RELOC_PPC_DTPREL
+@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16
+@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16_LO
+@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16_HI
+@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16_HA
+@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16
+@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16_LO
+@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16_HI
+@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16_HA
+@deffnx {} BFD_RELOC_PPC_GOT_TPREL16
+@deffnx {} BFD_RELOC_PPC_GOT_TPREL16_LO
+@deffnx {} BFD_RELOC_PPC_GOT_TPREL16_HI
+@deffnx {} BFD_RELOC_PPC_GOT_TPREL16_HA
+@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16
+@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16_LO
+@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16_HI
+@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16_HA
+@deffnx {} BFD_RELOC_PPC64_TPREL16_DS
+@deffnx {} BFD_RELOC_PPC64_TPREL16_LO_DS
+@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHER
+@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHERA
+@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHEST
+@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHESTA
+@deffnx {} BFD_RELOC_PPC64_DTPREL16_DS
+@deffnx {} BFD_RELOC_PPC64_DTPREL16_LO_DS
+@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHER
+@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHERA
+@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHEST
+@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHESTA
+PowerPC and PowerPC64 thread-local storage relocations.
+@end deffn
+@deffn {} BFD_RELOC_I370_D12
+IBM 370/390 relocations
+@end deffn
+@deffn {} BFD_RELOC_CTOR
+The type of reloc used to build a constructor table - at the moment
+probably a 32 bit wide absolute relocation, but the target can choose.
+It generally does map to one of the other relocation types.
+@end deffn
+@deffn {} BFD_RELOC_ARM_PCREL_BRANCH
+ARM 26 bit pc-relative branch. The lowest two bits must be zero and are
+not stored in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_ARM_PCREL_BLX
+ARM 26 bit pc-relative branch. The lowest bit must be zero and is
+not stored in the instruction. The 2nd lowest bit comes from a 1 bit
+field in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_THUMB_PCREL_BLX
+Thumb 22 bit pc-relative branch. The lowest bit must be zero and is
+not stored in the instruction. The 2nd lowest bit comes from a 1 bit
+field in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_ARM_PCREL_CALL
+ARM 26-bit pc-relative branch for an unconditional BL or BLX instruction.
+@end deffn
+@deffn {} BFD_RELOC_ARM_PCREL_JUMP
+ARM 26-bit pc-relative branch for B or conditional BL instruction.
+@end deffn
+@deffn {} BFD_RELOC_THUMB_PCREL_BRANCH7
+@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH9
+@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH12
+@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH20
+@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH23
+@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH25
+Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches.
+The lowest bit must be zero and is not stored in the instruction.
+Note that the corresponding ELF R_ARM_THM_JUMPnn constant has an
+"nn" one smaller in all cases. Note further that BRANCH23
+corresponds to R_ARM_THM_CALL.
+@end deffn
+@deffn {} BFD_RELOC_ARM_OFFSET_IMM
+12-bit immediate offset, used in ARM-format ldr and str instructions.
+@end deffn
+@deffn {} BFD_RELOC_ARM_THUMB_OFFSET
+5-bit immediate offset, used in Thumb-format ldr and str instructions.
+@end deffn
+@deffn {} BFD_RELOC_ARM_TARGET1
+Pc-relative or absolute relocation depending on target. Used for
+entries in .init_array sections.
+@end deffn
+@deffn {} BFD_RELOC_ARM_ROSEGREL32
+Read-only segment base relative address.
+@end deffn
+@deffn {} BFD_RELOC_ARM_SBREL32
+Data segment base relative address.
+@end deffn
+@deffn {} BFD_RELOC_ARM_TARGET2
+This reloc is used for references to RTTI data from exception handling
+tables. The actual definition depends on the target. It may be a
+pc-relative or some form of GOT-indirect relocation.
+@end deffn
+@deffn {} BFD_RELOC_ARM_PREL31
+31-bit PC relative address.
+@end deffn
+@deffn {} BFD_RELOC_ARM_MOVW
+@deffnx {} BFD_RELOC_ARM_MOVT
+@deffnx {} BFD_RELOC_ARM_MOVW_PCREL
+@deffnx {} BFD_RELOC_ARM_MOVT_PCREL
+@deffnx {} BFD_RELOC_ARM_THUMB_MOVW
+@deffnx {} BFD_RELOC_ARM_THUMB_MOVT
+@deffnx {} BFD_RELOC_ARM_THUMB_MOVW_PCREL
+@deffnx {} BFD_RELOC_ARM_THUMB_MOVT_PCREL
+Low and High halfword relocations for MOVW and MOVT instructions.
+@end deffn
+@deffn {} BFD_RELOC_ARM_JUMP_SLOT
+@deffnx {} BFD_RELOC_ARM_GLOB_DAT
+@deffnx {} BFD_RELOC_ARM_GOT32
+@deffnx {} BFD_RELOC_ARM_PLT32
+@deffnx {} BFD_RELOC_ARM_RELATIVE
+@deffnx {} BFD_RELOC_ARM_GOTOFF
+@deffnx {} BFD_RELOC_ARM_GOTPC
+Relocations for setting up GOTs and PLTs for shared libraries.
+@end deffn
+@deffn {} BFD_RELOC_ARM_TLS_GD32
+@deffnx {} BFD_RELOC_ARM_TLS_LDO32
+@deffnx {} BFD_RELOC_ARM_TLS_LDM32
+@deffnx {} BFD_RELOC_ARM_TLS_DTPOFF32
+@deffnx {} BFD_RELOC_ARM_TLS_DTPMOD32
+@deffnx {} BFD_RELOC_ARM_TLS_TPOFF32
+@deffnx {} BFD_RELOC_ARM_TLS_IE32
+@deffnx {} BFD_RELOC_ARM_TLS_LE32
+ARM thread-local storage relocations.
+@end deffn
+@deffn {} BFD_RELOC_ARM_ALU_PC_G0_NC
+@deffnx {} BFD_RELOC_ARM_ALU_PC_G0
+@deffnx {} BFD_RELOC_ARM_ALU_PC_G1_NC
+@deffnx {} BFD_RELOC_ARM_ALU_PC_G1
+@deffnx {} BFD_RELOC_ARM_ALU_PC_G2
+@deffnx {} BFD_RELOC_ARM_LDR_PC_G0
+@deffnx {} BFD_RELOC_ARM_LDR_PC_G1
+@deffnx {} BFD_RELOC_ARM_LDR_PC_G2
+@deffnx {} BFD_RELOC_ARM_LDRS_PC_G0
+@deffnx {} BFD_RELOC_ARM_LDRS_PC_G1
+@deffnx {} BFD_RELOC_ARM_LDRS_PC_G2
+@deffnx {} BFD_RELOC_ARM_LDC_PC_G0
+@deffnx {} BFD_RELOC_ARM_LDC_PC_G1
+@deffnx {} BFD_RELOC_ARM_LDC_PC_G2
+@deffnx {} BFD_RELOC_ARM_ALU_SB_G0_NC
+@deffnx {} BFD_RELOC_ARM_ALU_SB_G0
+@deffnx {} BFD_RELOC_ARM_ALU_SB_G1_NC
+@deffnx {} BFD_RELOC_ARM_ALU_SB_G1
+@deffnx {} BFD_RELOC_ARM_ALU_SB_G2
+@deffnx {} BFD_RELOC_ARM_LDR_SB_G0
+@deffnx {} BFD_RELOC_ARM_LDR_SB_G1
+@deffnx {} BFD_RELOC_ARM_LDR_SB_G2
+@deffnx {} BFD_RELOC_ARM_LDRS_SB_G0
+@deffnx {} BFD_RELOC_ARM_LDRS_SB_G1
+@deffnx {} BFD_RELOC_ARM_LDRS_SB_G2
+@deffnx {} BFD_RELOC_ARM_LDC_SB_G0
+@deffnx {} BFD_RELOC_ARM_LDC_SB_G1
+@deffnx {} BFD_RELOC_ARM_LDC_SB_G2
+ARM group relocations.
+@end deffn
+@deffn {} BFD_RELOC_ARM_V4BX
+Annotation of BX instructions.
+@end deffn
+@deffn {} BFD_RELOC_ARM_IMMEDIATE
+@deffnx {} BFD_RELOC_ARM_ADRL_IMMEDIATE
+@deffnx {} BFD_RELOC_ARM_T32_IMMEDIATE
+@deffnx {} BFD_RELOC_ARM_T32_ADD_IMM
+@deffnx {} BFD_RELOC_ARM_T32_IMM12
+@deffnx {} BFD_RELOC_ARM_T32_ADD_PC12
+@deffnx {} BFD_RELOC_ARM_SHIFT_IMM
+@deffnx {} BFD_RELOC_ARM_SMC
+@deffnx {} BFD_RELOC_ARM_SWI
+@deffnx {} BFD_RELOC_ARM_MULTI
+@deffnx {} BFD_RELOC_ARM_CP_OFF_IMM
+@deffnx {} BFD_RELOC_ARM_CP_OFF_IMM_S2
+@deffnx {} BFD_RELOC_ARM_T32_CP_OFF_IMM
+@deffnx {} BFD_RELOC_ARM_T32_CP_OFF_IMM_S2
+@deffnx {} BFD_RELOC_ARM_ADR_IMM
+@deffnx {} BFD_RELOC_ARM_LDR_IMM
+@deffnx {} BFD_RELOC_ARM_LITERAL
+@deffnx {} BFD_RELOC_ARM_IN_POOL
+@deffnx {} BFD_RELOC_ARM_OFFSET_IMM8
+@deffnx {} BFD_RELOC_ARM_T32_OFFSET_U8
+@deffnx {} BFD_RELOC_ARM_T32_OFFSET_IMM
+@deffnx {} BFD_RELOC_ARM_HWLITERAL
+@deffnx {} BFD_RELOC_ARM_THUMB_ADD
+@deffnx {} BFD_RELOC_ARM_THUMB_IMM
+@deffnx {} BFD_RELOC_ARM_THUMB_SHIFT
+These relocs are only used within the ARM assembler. They are not
+(at present) written to any object files.
+@end deffn
+@deffn {} BFD_RELOC_SH_PCDISP8BY2
+@deffnx {} BFD_RELOC_SH_PCDISP12BY2
+@deffnx {} BFD_RELOC_SH_IMM3
+@deffnx {} BFD_RELOC_SH_IMM3U
+@deffnx {} BFD_RELOC_SH_DISP12
+@deffnx {} BFD_RELOC_SH_DISP12BY2
+@deffnx {} BFD_RELOC_SH_DISP12BY4
+@deffnx {} BFD_RELOC_SH_DISP12BY8
+@deffnx {} BFD_RELOC_SH_DISP20
+@deffnx {} BFD_RELOC_SH_DISP20BY8
+@deffnx {} BFD_RELOC_SH_IMM4
+@deffnx {} BFD_RELOC_SH_IMM4BY2
+@deffnx {} BFD_RELOC_SH_IMM4BY4
+@deffnx {} BFD_RELOC_SH_IMM8
+@deffnx {} BFD_RELOC_SH_IMM8BY2
+@deffnx {} BFD_RELOC_SH_IMM8BY4
+@deffnx {} BFD_RELOC_SH_PCRELIMM8BY2
+@deffnx {} BFD_RELOC_SH_PCRELIMM8BY4
+@deffnx {} BFD_RELOC_SH_SWITCH16
+@deffnx {} BFD_RELOC_SH_SWITCH32
+@deffnx {} BFD_RELOC_SH_USES
+@deffnx {} BFD_RELOC_SH_COUNT
+@deffnx {} BFD_RELOC_SH_ALIGN
+@deffnx {} BFD_RELOC_SH_CODE
+@deffnx {} BFD_RELOC_SH_DATA
+@deffnx {} BFD_RELOC_SH_LABEL
+@deffnx {} BFD_RELOC_SH_LOOP_START
+@deffnx {} BFD_RELOC_SH_LOOP_END
+@deffnx {} BFD_RELOC_SH_COPY
+@deffnx {} BFD_RELOC_SH_GLOB_DAT
+@deffnx {} BFD_RELOC_SH_JMP_SLOT
+@deffnx {} BFD_RELOC_SH_RELATIVE
+@deffnx {} BFD_RELOC_SH_GOTPC
+@deffnx {} BFD_RELOC_SH_GOT_LOW16
+@deffnx {} BFD_RELOC_SH_GOT_MEDLOW16
+@deffnx {} BFD_RELOC_SH_GOT_MEDHI16
+@deffnx {} BFD_RELOC_SH_GOT_HI16
+@deffnx {} BFD_RELOC_SH_GOTPLT_LOW16
+@deffnx {} BFD_RELOC_SH_GOTPLT_MEDLOW16
+@deffnx {} BFD_RELOC_SH_GOTPLT_MEDHI16
+@deffnx {} BFD_RELOC_SH_GOTPLT_HI16
+@deffnx {} BFD_RELOC_SH_PLT_LOW16
+@deffnx {} BFD_RELOC_SH_PLT_MEDLOW16
+@deffnx {} BFD_RELOC_SH_PLT_MEDHI16
+@deffnx {} BFD_RELOC_SH_PLT_HI16
+@deffnx {} BFD_RELOC_SH_GOTOFF_LOW16
+@deffnx {} BFD_RELOC_SH_GOTOFF_MEDLOW16
+@deffnx {} BFD_RELOC_SH_GOTOFF_MEDHI16
+@deffnx {} BFD_RELOC_SH_GOTOFF_HI16
+@deffnx {} BFD_RELOC_SH_GOTPC_LOW16
+@deffnx {} BFD_RELOC_SH_GOTPC_MEDLOW16
+@deffnx {} BFD_RELOC_SH_GOTPC_MEDHI16
+@deffnx {} BFD_RELOC_SH_GOTPC_HI16
+@deffnx {} BFD_RELOC_SH_COPY64
+@deffnx {} BFD_RELOC_SH_GLOB_DAT64
+@deffnx {} BFD_RELOC_SH_JMP_SLOT64
+@deffnx {} BFD_RELOC_SH_RELATIVE64
+@deffnx {} BFD_RELOC_SH_GOT10BY4
+@deffnx {} BFD_RELOC_SH_GOT10BY8
+@deffnx {} BFD_RELOC_SH_GOTPLT10BY4
+@deffnx {} BFD_RELOC_SH_GOTPLT10BY8
+@deffnx {} BFD_RELOC_SH_GOTPLT32
+@deffnx {} BFD_RELOC_SH_SHMEDIA_CODE
+@deffnx {} BFD_RELOC_SH_IMMU5
+@deffnx {} BFD_RELOC_SH_IMMS6
+@deffnx {} BFD_RELOC_SH_IMMS6BY32
+@deffnx {} BFD_RELOC_SH_IMMU6
+@deffnx {} BFD_RELOC_SH_IMMS10
+@deffnx {} BFD_RELOC_SH_IMMS10BY2
+@deffnx {} BFD_RELOC_SH_IMMS10BY4
+@deffnx {} BFD_RELOC_SH_IMMS10BY8
+@deffnx {} BFD_RELOC_SH_IMMS16
+@deffnx {} BFD_RELOC_SH_IMMU16
+@deffnx {} BFD_RELOC_SH_IMM_LOW16
+@deffnx {} BFD_RELOC_SH_IMM_LOW16_PCREL
+@deffnx {} BFD_RELOC_SH_IMM_MEDLOW16
+@deffnx {} BFD_RELOC_SH_IMM_MEDLOW16_PCREL
+@deffnx {} BFD_RELOC_SH_IMM_MEDHI16
+@deffnx {} BFD_RELOC_SH_IMM_MEDHI16_PCREL
+@deffnx {} BFD_RELOC_SH_IMM_HI16
+@deffnx {} BFD_RELOC_SH_IMM_HI16_PCREL
+@deffnx {} BFD_RELOC_SH_PT_16
+@deffnx {} BFD_RELOC_SH_TLS_GD_32
+@deffnx {} BFD_RELOC_SH_TLS_LD_32
+@deffnx {} BFD_RELOC_SH_TLS_LDO_32
+@deffnx {} BFD_RELOC_SH_TLS_IE_32
+@deffnx {} BFD_RELOC_SH_TLS_LE_32
+@deffnx {} BFD_RELOC_SH_TLS_DTPMOD32
+@deffnx {} BFD_RELOC_SH_TLS_DTPOFF32
+@deffnx {} BFD_RELOC_SH_TLS_TPOFF32
+Renesas / SuperH SH relocs. Not all of these appear in object files.
+@end deffn
+@deffn {} BFD_RELOC_ARC_B22_PCREL
+ARC Cores relocs.
+ARC 22 bit pc-relative branch. The lowest two bits must be zero and are
+not stored in the instruction. The high 20 bits are installed in bits 26
+through 7 of the instruction.
+@end deffn
+@deffn {} BFD_RELOC_ARC_B26
+ARC 26 bit absolute branch. The lowest two bits must be zero and are not
+stored in the instruction. The high 24 bits are installed in bits 23
+through 0.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_16_IMM
+ADI Blackfin 16 bit immediate absolute reloc.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_16_HIGH
+ADI Blackfin 16 bit immediate absolute reloc higher 16 bits.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_4_PCREL
+ADI Blackfin 'a' part of LSETUP.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_5_PCREL
+ADI Blackfin.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_16_LOW
+ADI Blackfin 16 bit immediate absolute reloc lower 16 bits.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_10_PCREL
+ADI Blackfin.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_11_PCREL
+ADI Blackfin 'b' part of LSETUP.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_12_PCREL_JUMP
+ADI Blackfin.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_12_PCREL_JUMP_S
+ADI Blackfin Short jump, pcrel.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_24_PCREL_CALL_X
+ADI Blackfin Call.x not implemented.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_24_PCREL_JUMP_L
+ADI Blackfin Long Jump pcrel.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_GOT17M4
+@deffnx {} BFD_RELOC_BFIN_GOTHI
+@deffnx {} BFD_RELOC_BFIN_GOTLO
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOT17M4
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTHI
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTLO
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_VALUE
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI
+@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO
+@deffnx {} BFD_RELOC_BFIN_GOTOFF17M4
+@deffnx {} BFD_RELOC_BFIN_GOTOFFHI
+@deffnx {} BFD_RELOC_BFIN_GOTOFFLO
+ADI Blackfin FD-PIC relocations.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_GOT
+ADI Blackfin GOT relocation.
+@end deffn
+@deffn {} BFD_RELOC_BFIN_PLTPC
+ADI Blackfin PLTPC relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_PUSH
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_CONST
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_ADD
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_SUB
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_MULT
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_DIV
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_MOD
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_LSHIFT
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_RSHIFT
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_AND
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_OR
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_XOR
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_LAND
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_LOR
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_LEN
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_NEG
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_COMP
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_PAGE
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_HWPAGE
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_ARELOC_BFIN_ADDR
+ADI Blackfin arithmetic relocation.
+@end deffn
+@deffn {} BFD_RELOC_D10V_10_PCREL_R
+Mitsubishi D10V relocs.
+This is a 10-bit reloc with the right 2 bits
+assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D10V_10_PCREL_L
+Mitsubishi D10V relocs.
+This is a 10-bit reloc with the right 2 bits
+assumed to be 0. This is the same as the previous reloc
+except it is in the left container, i.e.,
+shifted left 15 bits.
+@end deffn
+@deffn {} BFD_RELOC_D10V_18
+This is an 18-bit reloc with the right 2 bits
+assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D10V_18_PCREL
+This is an 18-bit reloc with the right 2 bits
+assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D30V_6
+Mitsubishi D30V relocs.
+This is a 6-bit absolute reloc.
+@end deffn
+@deffn {} BFD_RELOC_D30V_9_PCREL
+This is a 6-bit pc-relative reloc with
+the right 3 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D30V_9_PCREL_R
+This is a 6-bit pc-relative reloc with
+the right 3 bits assumed to be 0. Same
+as the previous reloc but on the right side
+of the container.
+@end deffn
+@deffn {} BFD_RELOC_D30V_15
+This is a 12-bit absolute reloc with the
+right 3 bitsassumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D30V_15_PCREL
+This is a 12-bit pc-relative reloc with
+the right 3 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D30V_15_PCREL_R
+This is a 12-bit pc-relative reloc with
+the right 3 bits assumed to be 0. Same
+as the previous reloc but on the right side
+of the container.
+@end deffn
+@deffn {} BFD_RELOC_D30V_21
+This is an 18-bit absolute reloc with
+the right 3 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D30V_21_PCREL
+This is an 18-bit pc-relative reloc with
+the right 3 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_D30V_21_PCREL_R
+This is an 18-bit pc-relative reloc with
+the right 3 bits assumed to be 0. Same
+as the previous reloc but on the right side
+of the container.
+@end deffn
+@deffn {} BFD_RELOC_D30V_32
+This is a 32-bit absolute reloc.
+@end deffn
+@deffn {} BFD_RELOC_D30V_32_PCREL
+This is a 32-bit pc-relative reloc.
+@end deffn
+@deffn {} BFD_RELOC_DLX_HI16_S
+DLX relocs
+@end deffn
+@deffn {} BFD_RELOC_DLX_LO16
+DLX relocs
+@end deffn
+@deffn {} BFD_RELOC_DLX_JMP26
+DLX relocs
+@end deffn
+@deffn {} BFD_RELOC_M32C_HI8
+@deffnx {} BFD_RELOC_M32C_RL_JUMP
+@deffnx {} BFD_RELOC_M32C_RL_1ADDR
+@deffnx {} BFD_RELOC_M32C_RL_2ADDR
+Renesas M16C/M32C Relocations.
+@end deffn
+@deffn {} BFD_RELOC_M32R_24
+Renesas M32R (formerly Mitsubishi M32R) relocs.
+This is a 24 bit absolute address.
+@end deffn
+@deffn {} BFD_RELOC_M32R_10_PCREL
+This is a 10-bit pc-relative reloc with the right 2 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_18_PCREL
+This is an 18-bit reloc with the right 2 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_26_PCREL
+This is a 26-bit reloc with the right 2 bits assumed to be 0.
+@end deffn
+@deffn {} BFD_RELOC_M32R_HI16_ULO
+This is a 16-bit reloc containing the high 16 bits of an address
+used when the lower 16 bits are treated as unsigned.
+@end deffn
+@deffn {} BFD_RELOC_M32R_HI16_SLO
+This is a 16-bit reloc containing the high 16 bits of an address
+used when the lower 16 bits are treated as signed.
+@end deffn
+@deffn {} BFD_RELOC_M32R_LO16
+This is a 16-bit reloc containing the lower 16 bits of an address.
+@end deffn
+@deffn {} BFD_RELOC_M32R_SDA16
+This is a 16-bit reloc containing the small data area offset for use in
+add3, load, and store instructions.
+@end deffn
+@deffn {} BFD_RELOC_M32R_GOT24
+@deffnx {} BFD_RELOC_M32R_26_PLTREL
+@deffnx {} BFD_RELOC_M32R_COPY
+@deffnx {} BFD_RELOC_M32R_GLOB_DAT
+@deffnx {} BFD_RELOC_M32R_JMP_SLOT
+@deffnx {} BFD_RELOC_M32R_RELATIVE
+@deffnx {} BFD_RELOC_M32R_GOTOFF
+@deffnx {} BFD_RELOC_M32R_GOTOFF_HI_ULO
+@deffnx {} BFD_RELOC_M32R_GOTOFF_HI_SLO
+@deffnx {} BFD_RELOC_M32R_GOTOFF_LO
+@deffnx {} BFD_RELOC_M32R_GOTPC24
+@deffnx {} BFD_RELOC_M32R_GOT16_HI_ULO
+@deffnx {} BFD_RELOC_M32R_GOT16_HI_SLO
+@deffnx {} BFD_RELOC_M32R_GOT16_LO
+@deffnx {} BFD_RELOC_M32R_GOTPC_HI_ULO
+@deffnx {} BFD_RELOC_M32R_GOTPC_HI_SLO
+@deffnx {} BFD_RELOC_M32R_GOTPC_LO
+For PIC.
+@end deffn
+@deffn {} BFD_RELOC_V850_9_PCREL
+This is a 9-bit reloc
+@end deffn
+@deffn {} BFD_RELOC_V850_22_PCREL
+This is a 22-bit reloc
+@end deffn
+@deffn {} BFD_RELOC_V850_SDA_16_16_OFFSET
+This is a 16 bit offset from the short data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_SDA_15_16_OFFSET
+This is a 16 bit offset (of which only 15 bits are used) from the
+short data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_ZDA_16_16_OFFSET
+This is a 16 bit offset from the zero data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_ZDA_15_16_OFFSET
+This is a 16 bit offset (of which only 15 bits are used) from the
+zero data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_TDA_6_8_OFFSET
+This is an 8 bit offset (of which only 6 bits are used) from the
+tiny data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_TDA_7_8_OFFSET
+This is an 8bit offset (of which only 7 bits are used) from the tiny
+data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_TDA_7_7_OFFSET
+This is a 7 bit offset from the tiny data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_TDA_16_16_OFFSET
+This is a 16 bit offset from the tiny data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_TDA_4_5_OFFSET
+This is a 5 bit offset (of which only 4 bits are used) from the tiny
+data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_TDA_4_4_OFFSET
+This is a 4 bit offset from the tiny data area pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET
+This is a 16 bit offset from the short data area pointer, with the
+bits placed non-contiguously in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET
+This is a 16 bit offset from the zero data area pointer, with the
+bits placed non-contiguously in the instruction.
+@end deffn
+@deffn {} BFD_RELOC_V850_CALLT_6_7_OFFSET
+This is a 6 bit offset from the call table base pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_CALLT_16_16_OFFSET
+This is a 16 bit offset from the call table base pointer.
+@end deffn
+@deffn {} BFD_RELOC_V850_LONGCALL
+Used for relaxing indirect function calls.
+@end deffn
+@deffn {} BFD_RELOC_V850_LONGJUMP
+Used for relaxing indirect jumps.
+@end deffn
+@deffn {} BFD_RELOC_V850_ALIGN
+Used to maintain alignment whilst relaxing.
+@end deffn
+@deffn {} BFD_RELOC_V850_LO16_SPLIT_OFFSET
+This is a variation of BFD_RELOC_LO16 that can be used in v850e ld.bu
+instructions.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_32_PCREL
+This is a 32bit pcrel reloc for the mn10300, offset by two bytes in the
+instruction.
+@end deffn
+@deffn {} BFD_RELOC_MN10300_16_PCREL
+This is a 16bit pcrel reloc for the mn10300, offset by two bytes in the
+instruction.
+@end deffn
+@deffn {} BFD_RELOC_TIC30_LDP
+This is a 8bit DP reloc for the tms320c30, where the most
+significant 8 bits of a 24 bit word are placed into the least
+significant 8 bits of the opcode.
+@end deffn
+@deffn {} BFD_RELOC_TIC54X_PARTLS7
+This is a 7bit reloc for the tms320c54x, where the least
+significant 7 bits of a 16 bit word are placed into the least
+significant 7 bits of the opcode.
+@end deffn
+@deffn {} BFD_RELOC_TIC54X_PARTMS9
+This is a 9bit DP reloc for the tms320c54x, where the most
+significant 9 bits of a 16 bit word are placed into the least
+significant 9 bits of the opcode.
+@end deffn
+@deffn {} BFD_RELOC_TIC54X_23
+This is an extended address 23-bit reloc for the tms320c54x.
+@end deffn
+@deffn {} BFD_RELOC_TIC54X_16_OF_23
+This is a 16-bit reloc for the tms320c54x, where the least
+significant 16 bits of a 23-bit extended address are placed into
+the opcode.
+@end deffn
+@deffn {} BFD_RELOC_TIC54X_MS7_OF_23
+This is a reloc for the tms320c54x, where the most
+significant 7 bits of a 23-bit extended address are placed into
+the opcode.
+@end deffn
+@deffn {} BFD_RELOC_FR30_48
+This is a 48 bit reloc for the FR30 that stores 32 bits.
+@end deffn
+@deffn {} BFD_RELOC_FR30_20
+This is a 32 bit reloc for the FR30 that stores 20 bits split up into
+two sections.
+@end deffn
+@deffn {} BFD_RELOC_FR30_6_IN_4
+This is a 16 bit reloc for the FR30 that stores a 6 bit word offset in
+4 bits.
+@end deffn
+@deffn {} BFD_RELOC_FR30_8_IN_8
+This is a 16 bit reloc for the FR30 that stores an 8 bit byte offset
+into 8 bits.
+@end deffn
+@deffn {} BFD_RELOC_FR30_9_IN_8
+This is a 16 bit reloc for the FR30 that stores a 9 bit short offset
+into 8 bits.
+@end deffn
+@deffn {} BFD_RELOC_FR30_10_IN_8
+This is a 16 bit reloc for the FR30 that stores a 10 bit word offset
+into 8 bits.
+@end deffn
+@deffn {} BFD_RELOC_FR30_9_PCREL
+This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative
+short offset into 8 bits.
+@end deffn
+@deffn {} BFD_RELOC_FR30_12_PCREL
+This is a 16 bit reloc for the FR30 that stores a 12 bit pc relative
+short offset into 11 bits.
+@end deffn
+@deffn {} BFD_RELOC_MCORE_PCREL_IMM8BY4
+@deffnx {} BFD_RELOC_MCORE_PCREL_IMM11BY2
+@deffnx {} BFD_RELOC_MCORE_PCREL_IMM4BY2
+@deffnx {} BFD_RELOC_MCORE_PCREL_32
+@deffnx {} BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2
+@deffnx {} BFD_RELOC_MCORE_RVA
+Motorola Mcore relocations.
+@end deffn
+@deffn {} BFD_RELOC_MEP_8
+@deffnx {} BFD_RELOC_MEP_16
+@deffnx {} BFD_RELOC_MEP_32
+@deffnx {} BFD_RELOC_MEP_PCREL8A2
+@deffnx {} BFD_RELOC_MEP_PCREL12A2
+@deffnx {} BFD_RELOC_MEP_PCREL17A2
+@deffnx {} BFD_RELOC_MEP_PCREL24A2
+@deffnx {} BFD_RELOC_MEP_PCABS24A2
+@deffnx {} BFD_RELOC_MEP_LOW16
+@deffnx {} BFD_RELOC_MEP_HI16U
+@deffnx {} BFD_RELOC_MEP_HI16S
+@deffnx {} BFD_RELOC_MEP_GPREL
+@deffnx {} BFD_RELOC_MEP_TPREL
+@deffnx {} BFD_RELOC_MEP_TPREL7
+@deffnx {} BFD_RELOC_MEP_TPREL7A2
+@deffnx {} BFD_RELOC_MEP_TPREL7A4
+@deffnx {} BFD_RELOC_MEP_UIMM24
+@deffnx {} BFD_RELOC_MEP_ADDR24A4
+@deffnx {} BFD_RELOC_MEP_GNU_VTINHERIT
+@deffnx {} BFD_RELOC_MEP_GNU_VTENTRY
+Toshiba Media Processor Relocations.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_GETA
+@deffnx {} BFD_RELOC_MMIX_GETA_1
+@deffnx {} BFD_RELOC_MMIX_GETA_2
+@deffnx {} BFD_RELOC_MMIX_GETA_3
+These are relocations for the GETA instruction.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_CBRANCH
+@deffnx {} BFD_RELOC_MMIX_CBRANCH_J
+@deffnx {} BFD_RELOC_MMIX_CBRANCH_1
+@deffnx {} BFD_RELOC_MMIX_CBRANCH_2
+@deffnx {} BFD_RELOC_MMIX_CBRANCH_3
+These are relocations for a conditional branch instruction.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_PUSHJ
+@deffnx {} BFD_RELOC_MMIX_PUSHJ_1
+@deffnx {} BFD_RELOC_MMIX_PUSHJ_2
+@deffnx {} BFD_RELOC_MMIX_PUSHJ_3
+@deffnx {} BFD_RELOC_MMIX_PUSHJ_STUBBABLE
+These are relocations for the PUSHJ instruction.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_JMP
+@deffnx {} BFD_RELOC_MMIX_JMP_1
+@deffnx {} BFD_RELOC_MMIX_JMP_2
+@deffnx {} BFD_RELOC_MMIX_JMP_3
+These are relocations for the JMP instruction.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_ADDR19
+This is a relocation for a relative address as in a GETA instruction or
+a branch.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_ADDR27
+This is a relocation for a relative address as in a JMP instruction.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_REG_OR_BYTE
+This is a relocation for an instruction field that may be a general
+register or a value 0..255.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_REG
+This is a relocation for an instruction field that may be a general
+register.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_BASE_PLUS_OFFSET
+This is a relocation for two instruction fields holding a register and
+an offset, the equivalent of the relocation.
+@end deffn
+@deffn {} BFD_RELOC_MMIX_LOCAL
+This relocation is an assertion that the expression is not allocated as
+a global register. It does not modify contents.
+@end deffn
+@deffn {} BFD_RELOC_AVR_7_PCREL
+This is a 16 bit reloc for the AVR that stores 8 bit pc relative
+short offset into 7 bits.
+@end deffn
+@deffn {} BFD_RELOC_AVR_13_PCREL
+This is a 16 bit reloc for the AVR that stores 13 bit pc relative
+short offset into 12 bits.
+@end deffn
+@deffn {} BFD_RELOC_AVR_16_PM
+This is a 16 bit reloc for the AVR that stores 17 bit value (usually
+program memory address) into 16 bits.
+@end deffn
+@deffn {} BFD_RELOC_AVR_LO8_LDI
+This is a 16 bit reloc for the AVR that stores 8 bit value (usually
+data memory address) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HI8_LDI
+This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit
+of data memory address) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HH8_LDI
+This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit
+of program memory address) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_MS8_LDI
+This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit
+of 32 bit value) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_LO8_LDI_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value
+(usually data memory address) into 8 bit immediate value of SUBI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HI8_LDI_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value
+(high 8 bit of data memory address) into 8 bit immediate value of
+SUBI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HH8_LDI_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value
+(most high 8 bit of program memory address) into 8 bit immediate value
+of LDI or SUBI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_MS8_LDI_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value (msb
+of 32 bit value) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_LO8_LDI_PM
+This is a 16 bit reloc for the AVR that stores 8 bit value (usually
+command address) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_LO8_LDI_GS
+This is a 16 bit reloc for the AVR that stores 8 bit value
+(command address) into 8 bit immediate value of LDI insn. If the address
+is beyond the 128k boundary, the linker inserts a jump stub for this reloc
+in the lower 128k.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HI8_LDI_PM
+This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit
+of command address) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HI8_LDI_GS
+This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit
+of command address) into 8 bit immediate value of LDI insn. If the address
+is beyond the 128k boundary, the linker inserts a jump stub for this reloc
+below 128k.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HH8_LDI_PM
+This is a 16 bit reloc for the AVR that stores 8 bit value (most high 8 bit
+of command address) into 8 bit immediate value of LDI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_LO8_LDI_PM_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value
+(usually command address) into 8 bit immediate value of SUBI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HI8_LDI_PM_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value
+(high 8 bit of 16 bit command address) into 8 bit immediate value
+of SUBI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_HH8_LDI_PM_NEG
+This is a 16 bit reloc for the AVR that stores negated 8 bit value
+(high 6 bit of 22 bit command address) into 8 bit immediate
+value of SUBI insn.
+@end deffn
+@deffn {} BFD_RELOC_AVR_CALL
+This is a 32 bit reloc for the AVR that stores 23 bit value
+into 22 bits.
+@end deffn
+@deffn {} BFD_RELOC_AVR_LDI
+This is a 16 bit reloc for the AVR that stores all needed bits
+for absolute addressing with ldi with overflow check to linktime
+@end deffn
+@deffn {} BFD_RELOC_AVR_6
+This is a 6 bit reloc for the AVR that stores offset for ldd/std
+instructions
+@end deffn
+@deffn {} BFD_RELOC_AVR_6_ADIW
+This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw
+instructions
+@end deffn
+@deffn {} BFD_RELOC_390_12
+Direct 12 bit.
+@end deffn
+@deffn {} BFD_RELOC_390_GOT12
+12 bit GOT offset.
+@end deffn
+@deffn {} BFD_RELOC_390_PLT32
+32 bit PC relative PLT address.
+@end deffn
+@deffn {} BFD_RELOC_390_COPY
+Copy symbol at runtime.
+@end deffn
+@deffn {} BFD_RELOC_390_GLOB_DAT
+Create GOT entry.
+@end deffn
+@deffn {} BFD_RELOC_390_JMP_SLOT
+Create PLT entry.
+@end deffn
+@deffn {} BFD_RELOC_390_RELATIVE
+Adjust by program base.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPC
+32 bit PC relative offset to GOT.
+@end deffn
+@deffn {} BFD_RELOC_390_GOT16
+16 bit GOT offset.
+@end deffn
+@deffn {} BFD_RELOC_390_PC16DBL
+PC relative 16 bit shifted by 1.
+@end deffn
+@deffn {} BFD_RELOC_390_PLT16DBL
+16 bit PC rel. PLT shifted by 1.
+@end deffn
+@deffn {} BFD_RELOC_390_PC32DBL
+PC relative 32 bit shifted by 1.
+@end deffn
+@deffn {} BFD_RELOC_390_PLT32DBL
+32 bit PC rel. PLT shifted by 1.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPCDBL
+32 bit PC rel. GOT shifted by 1.
+@end deffn
+@deffn {} BFD_RELOC_390_GOT64
+64 bit GOT offset.
+@end deffn
+@deffn {} BFD_RELOC_390_PLT64
+64 bit PC relative PLT address.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTENT
+32 bit rel. offset to GOT entry.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTOFF64
+64 bit offset to GOT.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPLT12
+12-bit offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPLT16
+16-bit offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPLT32
+32-bit offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPLT64
+64-bit offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_390_GOTPLTENT
+32-bit rel. offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_390_PLTOFF16
+16-bit rel. offset from the GOT to a PLT entry.
+@end deffn
+@deffn {} BFD_RELOC_390_PLTOFF32
+32-bit rel. offset from the GOT to a PLT entry.
+@end deffn
+@deffn {} BFD_RELOC_390_PLTOFF64
+64-bit rel. offset from the GOT to a PLT entry.
+@end deffn
+@deffn {} BFD_RELOC_390_TLS_LOAD
+@deffnx {} BFD_RELOC_390_TLS_GDCALL
+@deffnx {} BFD_RELOC_390_TLS_LDCALL
+@deffnx {} BFD_RELOC_390_TLS_GD32
+@deffnx {} BFD_RELOC_390_TLS_GD64
+@deffnx {} BFD_RELOC_390_TLS_GOTIE12
+@deffnx {} BFD_RELOC_390_TLS_GOTIE32
+@deffnx {} BFD_RELOC_390_TLS_GOTIE64
+@deffnx {} BFD_RELOC_390_TLS_LDM32
+@deffnx {} BFD_RELOC_390_TLS_LDM64
+@deffnx {} BFD_RELOC_390_TLS_IE32
+@deffnx {} BFD_RELOC_390_TLS_IE64
+@deffnx {} BFD_RELOC_390_TLS_IEENT
+@deffnx {} BFD_RELOC_390_TLS_LE32
+@deffnx {} BFD_RELOC_390_TLS_LE64
+@deffnx {} BFD_RELOC_390_TLS_LDO32
+@deffnx {} BFD_RELOC_390_TLS_LDO64
+@deffnx {} BFD_RELOC_390_TLS_DTPMOD
+@deffnx {} BFD_RELOC_390_TLS_DTPOFF
+@deffnx {} BFD_RELOC_390_TLS_TPOFF
+s390 tls relocations.
+@end deffn
+@deffn {} BFD_RELOC_390_20
+@deffnx {} BFD_RELOC_390_GOT20
+@deffnx {} BFD_RELOC_390_GOTPLT20
+@deffnx {} BFD_RELOC_390_TLS_GOTIE20
+Long displacement extension.
+@end deffn
+@deffn {} BFD_RELOC_SCORE_GPREL15
+Score relocations
+Low 16 bit for load/store
+@end deffn
+@deffn {} BFD_RELOC_SCORE_DUMMY2
+@deffnx {} BFD_RELOC_SCORE_JMP
+This is a 24-bit reloc with the right 1 bit assumed to be 0
+@end deffn
+@deffn {} BFD_RELOC_SCORE_BRANCH
+This is a 19-bit reloc with the right 1 bit assumed to be 0
+@end deffn
+@deffn {} BFD_RELOC_SCORE_IMM30
+This is a 32-bit reloc for 48-bit instructions.
+@end deffn
+@deffn {} BFD_RELOC_SCORE_IMM32
+This is a 32-bit reloc for 48-bit instructions.
+@end deffn
+@deffn {} BFD_RELOC_SCORE16_JMP
+This is a 11-bit reloc with the right 1 bit assumed to be 0
+@end deffn
+@deffn {} BFD_RELOC_SCORE16_BRANCH
+This is a 8-bit reloc with the right 1 bit assumed to be 0
+@end deffn
+@deffn {} BFD_RELOC_SCORE_BCMP
+This is a 9-bit reloc with the right 1 bit assumed to be 0
+@end deffn
+@deffn {} BFD_RELOC_SCORE_GOT15
+@deffnx {} BFD_RELOC_SCORE_GOT_LO16
+@deffnx {} BFD_RELOC_SCORE_CALL15
+@deffnx {} BFD_RELOC_SCORE_DUMMY_HI16
+Undocumented Score relocs
+@end deffn
+@deffn {} BFD_RELOC_IP2K_FR9
+Scenix IP2K - 9-bit register number / data address
+@end deffn
+@deffn {} BFD_RELOC_IP2K_BANK
+Scenix IP2K - 4-bit register/data bank number
+@end deffn
+@deffn {} BFD_RELOC_IP2K_ADDR16CJP
+Scenix IP2K - low 13 bits of instruction word address
+@end deffn
+@deffn {} BFD_RELOC_IP2K_PAGE3
+Scenix IP2K - high 3 bits of instruction word address
+@end deffn
+@deffn {} BFD_RELOC_IP2K_LO8DATA
+@deffnx {} BFD_RELOC_IP2K_HI8DATA
+@deffnx {} BFD_RELOC_IP2K_EX8DATA
+Scenix IP2K - ext/low/high 8 bits of data address
+@end deffn
+@deffn {} BFD_RELOC_IP2K_LO8INSN
+@deffnx {} BFD_RELOC_IP2K_HI8INSN
+Scenix IP2K - low/high 8 bits of instruction word address
+@end deffn
+@deffn {} BFD_RELOC_IP2K_PC_SKIP
+Scenix IP2K - even/odd PC modifier to modify snb pcl.0
+@end deffn
+@deffn {} BFD_RELOC_IP2K_TEXT
+Scenix IP2K - 16 bit word address in text section.
+@end deffn
+@deffn {} BFD_RELOC_IP2K_FR_OFFSET
+Scenix IP2K - 7-bit sp or dp offset
+@end deffn
+@deffn {} BFD_RELOC_VPE4KMATH_DATA
+@deffnx {} BFD_RELOC_VPE4KMATH_INSN
+Scenix VPE4K coprocessor - data/insn-space addressing
+@end deffn
+@deffn {} BFD_RELOC_VTABLE_INHERIT
+@deffnx {} BFD_RELOC_VTABLE_ENTRY
+These two relocations are used by the linker to determine which of
+the entries in a C++ virtual function table are actually used. When
+the --gc-sections option is given, the linker will zero out the entries
+that are not used, so that the code for those functions need not be
+included in the output.
+
+VTABLE_INHERIT is a zero-space relocation used to describe to the
+linker the inheritance tree of a C++ virtual function table. The
+relocation's symbol should be the parent class' vtable, and the
+relocation should be located at the child vtable.
+
+VTABLE_ENTRY is a zero-space relocation that describes the use of a
+virtual function table entry. The reloc's symbol should refer to the
+table of the class mentioned in the code. Off of that base, an offset
+describes the entry that is being used. For Rela hosts, this offset
+is stored in the reloc's addend. For Rel hosts, we are forced to put
+this offset in the reloc's section offset.
+@end deffn
+@deffn {} BFD_RELOC_IA64_IMM14
+@deffnx {} BFD_RELOC_IA64_IMM22
+@deffnx {} BFD_RELOC_IA64_IMM64
+@deffnx {} BFD_RELOC_IA64_DIR32MSB
+@deffnx {} BFD_RELOC_IA64_DIR32LSB
+@deffnx {} BFD_RELOC_IA64_DIR64MSB
+@deffnx {} BFD_RELOC_IA64_DIR64LSB
+@deffnx {} BFD_RELOC_IA64_GPREL22
+@deffnx {} BFD_RELOC_IA64_GPREL64I
+@deffnx {} BFD_RELOC_IA64_GPREL32MSB
+@deffnx {} BFD_RELOC_IA64_GPREL32LSB
+@deffnx {} BFD_RELOC_IA64_GPREL64MSB
+@deffnx {} BFD_RELOC_IA64_GPREL64LSB
+@deffnx {} BFD_RELOC_IA64_LTOFF22
+@deffnx {} BFD_RELOC_IA64_LTOFF64I
+@deffnx {} BFD_RELOC_IA64_PLTOFF22
+@deffnx {} BFD_RELOC_IA64_PLTOFF64I
+@deffnx {} BFD_RELOC_IA64_PLTOFF64MSB
+@deffnx {} BFD_RELOC_IA64_PLTOFF64LSB
+@deffnx {} BFD_RELOC_IA64_FPTR64I
+@deffnx {} BFD_RELOC_IA64_FPTR32MSB
+@deffnx {} BFD_RELOC_IA64_FPTR32LSB
+@deffnx {} BFD_RELOC_IA64_FPTR64MSB
+@deffnx {} BFD_RELOC_IA64_FPTR64LSB
+@deffnx {} BFD_RELOC_IA64_PCREL21B
+@deffnx {} BFD_RELOC_IA64_PCREL21BI
+@deffnx {} BFD_RELOC_IA64_PCREL21M
+@deffnx {} BFD_RELOC_IA64_PCREL21F
+@deffnx {} BFD_RELOC_IA64_PCREL22
+@deffnx {} BFD_RELOC_IA64_PCREL60B
+@deffnx {} BFD_RELOC_IA64_PCREL64I
+@deffnx {} BFD_RELOC_IA64_PCREL32MSB
+@deffnx {} BFD_RELOC_IA64_PCREL32LSB
+@deffnx {} BFD_RELOC_IA64_PCREL64MSB
+@deffnx {} BFD_RELOC_IA64_PCREL64LSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR22
+@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR64I
+@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR32MSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR32LSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR64MSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR64LSB
+@deffnx {} BFD_RELOC_IA64_SEGREL32MSB
+@deffnx {} BFD_RELOC_IA64_SEGREL32LSB
+@deffnx {} BFD_RELOC_IA64_SEGREL64MSB
+@deffnx {} BFD_RELOC_IA64_SEGREL64LSB
+@deffnx {} BFD_RELOC_IA64_SECREL32MSB
+@deffnx {} BFD_RELOC_IA64_SECREL32LSB
+@deffnx {} BFD_RELOC_IA64_SECREL64MSB
+@deffnx {} BFD_RELOC_IA64_SECREL64LSB
+@deffnx {} BFD_RELOC_IA64_REL32MSB
+@deffnx {} BFD_RELOC_IA64_REL32LSB
+@deffnx {} BFD_RELOC_IA64_REL64MSB
+@deffnx {} BFD_RELOC_IA64_REL64LSB
+@deffnx {} BFD_RELOC_IA64_LTV32MSB
+@deffnx {} BFD_RELOC_IA64_LTV32LSB
+@deffnx {} BFD_RELOC_IA64_LTV64MSB
+@deffnx {} BFD_RELOC_IA64_LTV64LSB
+@deffnx {} BFD_RELOC_IA64_IPLTMSB
+@deffnx {} BFD_RELOC_IA64_IPLTLSB
+@deffnx {} BFD_RELOC_IA64_COPY
+@deffnx {} BFD_RELOC_IA64_LTOFF22X
+@deffnx {} BFD_RELOC_IA64_LDXMOV
+@deffnx {} BFD_RELOC_IA64_TPREL14
+@deffnx {} BFD_RELOC_IA64_TPREL22
+@deffnx {} BFD_RELOC_IA64_TPREL64I
+@deffnx {} BFD_RELOC_IA64_TPREL64MSB
+@deffnx {} BFD_RELOC_IA64_TPREL64LSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_TPREL22
+@deffnx {} BFD_RELOC_IA64_DTPMOD64MSB
+@deffnx {} BFD_RELOC_IA64_DTPMOD64LSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_DTPMOD22
+@deffnx {} BFD_RELOC_IA64_DTPREL14
+@deffnx {} BFD_RELOC_IA64_DTPREL22
+@deffnx {} BFD_RELOC_IA64_DTPREL64I
+@deffnx {} BFD_RELOC_IA64_DTPREL32MSB
+@deffnx {} BFD_RELOC_IA64_DTPREL32LSB
+@deffnx {} BFD_RELOC_IA64_DTPREL64MSB
+@deffnx {} BFD_RELOC_IA64_DTPREL64LSB
+@deffnx {} BFD_RELOC_IA64_LTOFF_DTPREL22
+Intel IA64 Relocations.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_HI8
+Motorola 68HC11 reloc.
+This is the 8 bit high part of an absolute address.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_LO8
+Motorola 68HC11 reloc.
+This is the 8 bit low part of an absolute address.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_3B
+Motorola 68HC11 reloc.
+This is the 3 bit of a value.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_RL_JUMP
+Motorola 68HC11 reloc.
+This reloc marks the beginning of a jump/call instruction.
+It is used for linker relaxation to correctly identify beginning
+of instruction and change some branches to use PC-relative
+addressing mode.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_RL_GROUP
+Motorola 68HC11 reloc.
+This reloc marks a group of several instructions that gcc generates
+and for which the linker relaxation pass can modify and/or remove
+some of them.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_LO16
+Motorola 68HC11 reloc.
+This is the 16-bit lower part of an address. It is used for 'call'
+instruction to specify the symbol address without any special
+transformation (due to memory bank window).
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_PAGE
+Motorola 68HC11 reloc.
+This is a 8-bit reloc that specifies the page number of an address.
+It is used by 'call' instruction to specify the page number of
+the symbol.
+@end deffn
+@deffn {} BFD_RELOC_M68HC11_24
+Motorola 68HC11 reloc.
+This is a 24-bit reloc that represents the address with a 16-bit
+value and a 8-bit page number. The symbol address is transformed
+to follow the 16K memory bank of 68HC12 (seen as mapped in the window).
+@end deffn
+@deffn {} BFD_RELOC_M68HC12_5B
+Motorola 68HC12 reloc.
+This is the 5 bits of a value.
+@end deffn
+@deffn {} BFD_RELOC_16C_NUM08
+@deffnx {} BFD_RELOC_16C_NUM08_C
+@deffnx {} BFD_RELOC_16C_NUM16
+@deffnx {} BFD_RELOC_16C_NUM16_C
+@deffnx {} BFD_RELOC_16C_NUM32
+@deffnx {} BFD_RELOC_16C_NUM32_C
+@deffnx {} BFD_RELOC_16C_DISP04
+@deffnx {} BFD_RELOC_16C_DISP04_C
+@deffnx {} BFD_RELOC_16C_DISP08
+@deffnx {} BFD_RELOC_16C_DISP08_C
+@deffnx {} BFD_RELOC_16C_DISP16
+@deffnx {} BFD_RELOC_16C_DISP16_C
+@deffnx {} BFD_RELOC_16C_DISP24
+@deffnx {} BFD_RELOC_16C_DISP24_C
+@deffnx {} BFD_RELOC_16C_DISP24a
+@deffnx {} BFD_RELOC_16C_DISP24a_C
+@deffnx {} BFD_RELOC_16C_REG04
+@deffnx {} BFD_RELOC_16C_REG04_C
+@deffnx {} BFD_RELOC_16C_REG04a
+@deffnx {} BFD_RELOC_16C_REG04a_C
+@deffnx {} BFD_RELOC_16C_REG14
+@deffnx {} BFD_RELOC_16C_REG14_C
+@deffnx {} BFD_RELOC_16C_REG16
+@deffnx {} BFD_RELOC_16C_REG16_C
+@deffnx {} BFD_RELOC_16C_REG20
+@deffnx {} BFD_RELOC_16C_REG20_C
+@deffnx {} BFD_RELOC_16C_ABS20
+@deffnx {} BFD_RELOC_16C_ABS20_C
+@deffnx {} BFD_RELOC_16C_ABS24
+@deffnx {} BFD_RELOC_16C_ABS24_C
+@deffnx {} BFD_RELOC_16C_IMM04
+@deffnx {} BFD_RELOC_16C_IMM04_C
+@deffnx {} BFD_RELOC_16C_IMM16
+@deffnx {} BFD_RELOC_16C_IMM16_C
+@deffnx {} BFD_RELOC_16C_IMM20
+@deffnx {} BFD_RELOC_16C_IMM20_C
+@deffnx {} BFD_RELOC_16C_IMM24
+@deffnx {} BFD_RELOC_16C_IMM24_C
+@deffnx {} BFD_RELOC_16C_IMM32
+@deffnx {} BFD_RELOC_16C_IMM32_C
+NS CR16C Relocations.
+@end deffn
+@deffn {} BFD_RELOC_CR16_NUM8
+@deffnx {} BFD_RELOC_CR16_NUM16
+@deffnx {} BFD_RELOC_CR16_NUM32
+@deffnx {} BFD_RELOC_CR16_NUM32a
+@deffnx {} BFD_RELOC_CR16_REGREL0
+@deffnx {} BFD_RELOC_CR16_REGREL4
+@deffnx {} BFD_RELOC_CR16_REGREL4a
+@deffnx {} BFD_RELOC_CR16_REGREL14
+@deffnx {} BFD_RELOC_CR16_REGREL14a
+@deffnx {} BFD_RELOC_CR16_REGREL16
+@deffnx {} BFD_RELOC_CR16_REGREL20
+@deffnx {} BFD_RELOC_CR16_REGREL20a
+@deffnx {} BFD_RELOC_CR16_ABS20
+@deffnx {} BFD_RELOC_CR16_ABS24
+@deffnx {} BFD_RELOC_CR16_IMM4
+@deffnx {} BFD_RELOC_CR16_IMM8
+@deffnx {} BFD_RELOC_CR16_IMM16
+@deffnx {} BFD_RELOC_CR16_IMM20
+@deffnx {} BFD_RELOC_CR16_IMM24
+@deffnx {} BFD_RELOC_CR16_IMM32
+@deffnx {} BFD_RELOC_CR16_IMM32a
+@deffnx {} BFD_RELOC_CR16_DISP4
+@deffnx {} BFD_RELOC_CR16_DISP8
+@deffnx {} BFD_RELOC_CR16_DISP16
+@deffnx {} BFD_RELOC_CR16_DISP20
+@deffnx {} BFD_RELOC_CR16_DISP24
+@deffnx {} BFD_RELOC_CR16_DISP24a
+@deffnx {} BFD_RELOC_CR16_SWITCH8
+@deffnx {} BFD_RELOC_CR16_SWITCH16
+@deffnx {} BFD_RELOC_CR16_SWITCH32
+@deffnx {} BFD_RELOC_CR16_GOT_REGREL20
+@deffnx {} BFD_RELOC_CR16_GOTC_REGREL20
+@deffnx {} BFD_RELOC_CR16_GLOB_DAT
+NS CR16 Relocations.
+@end deffn
+@deffn {} BFD_RELOC_CRX_REL4
+@deffnx {} BFD_RELOC_CRX_REL8
+@deffnx {} BFD_RELOC_CRX_REL8_CMP
+@deffnx {} BFD_RELOC_CRX_REL16
+@deffnx {} BFD_RELOC_CRX_REL24
+@deffnx {} BFD_RELOC_CRX_REL32
+@deffnx {} BFD_RELOC_CRX_REGREL12
+@deffnx {} BFD_RELOC_CRX_REGREL22
+@deffnx {} BFD_RELOC_CRX_REGREL28
+@deffnx {} BFD_RELOC_CRX_REGREL32
+@deffnx {} BFD_RELOC_CRX_ABS16
+@deffnx {} BFD_RELOC_CRX_ABS32
+@deffnx {} BFD_RELOC_CRX_NUM8
+@deffnx {} BFD_RELOC_CRX_NUM16
+@deffnx {} BFD_RELOC_CRX_NUM32
+@deffnx {} BFD_RELOC_CRX_IMM16
+@deffnx {} BFD_RELOC_CRX_IMM32
+@deffnx {} BFD_RELOC_CRX_SWITCH8
+@deffnx {} BFD_RELOC_CRX_SWITCH16
+@deffnx {} BFD_RELOC_CRX_SWITCH32
+NS CRX Relocations.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_BDISP8
+@deffnx {} BFD_RELOC_CRIS_UNSIGNED_5
+@deffnx {} BFD_RELOC_CRIS_SIGNED_6
+@deffnx {} BFD_RELOC_CRIS_UNSIGNED_6
+@deffnx {} BFD_RELOC_CRIS_SIGNED_8
+@deffnx {} BFD_RELOC_CRIS_UNSIGNED_8
+@deffnx {} BFD_RELOC_CRIS_SIGNED_16
+@deffnx {} BFD_RELOC_CRIS_UNSIGNED_16
+@deffnx {} BFD_RELOC_CRIS_LAPCQ_OFFSET
+@deffnx {} BFD_RELOC_CRIS_UNSIGNED_4
+These relocs are only used within the CRIS assembler. They are not
+(at present) written to any object files.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_COPY
+@deffnx {} BFD_RELOC_CRIS_GLOB_DAT
+@deffnx {} BFD_RELOC_CRIS_JUMP_SLOT
+@deffnx {} BFD_RELOC_CRIS_RELATIVE
+Relocs used in ELF shared libraries for CRIS.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_32_GOT
+32-bit offset to symbol-entry within GOT.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_16_GOT
+16-bit offset to symbol-entry within GOT.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_32_GOTPLT
+32-bit offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_16_GOTPLT
+16-bit offset to symbol-entry within GOT, with PLT handling.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_32_GOTREL
+32-bit offset to symbol, relative to GOT.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_32_PLT_GOTREL
+32-bit offset to symbol with PLT entry, relative to GOT.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_32_PLT_PCREL
+32-bit offset to symbol with PLT entry, relative to this relocation.
+@end deffn
+@deffn {} BFD_RELOC_CRIS_32_GOT_GD
+@deffnx {} BFD_RELOC_CRIS_16_GOT_GD
+@deffnx {} BFD_RELOC_CRIS_32_GD
+@deffnx {} BFD_RELOC_CRIS_DTP
+@deffnx {} BFD_RELOC_CRIS_32_DTPREL
+@deffnx {} BFD_RELOC_CRIS_16_DTPREL
+@deffnx {} BFD_RELOC_CRIS_32_GOT_TPREL
+@deffnx {} BFD_RELOC_CRIS_16_GOT_TPREL
+@deffnx {} BFD_RELOC_CRIS_32_TPREL
+@deffnx {} BFD_RELOC_CRIS_16_TPREL
+@deffnx {} BFD_RELOC_CRIS_DTPMOD
+@deffnx {} BFD_RELOC_CRIS_32_IE
+Relocs used in TLS code for CRIS.
+@end deffn
+@deffn {} BFD_RELOC_860_COPY
+@deffnx {} BFD_RELOC_860_GLOB_DAT
+@deffnx {} BFD_RELOC_860_JUMP_SLOT
+@deffnx {} BFD_RELOC_860_RELATIVE
+@deffnx {} BFD_RELOC_860_PC26
+@deffnx {} BFD_RELOC_860_PLT26
+@deffnx {} BFD_RELOC_860_PC16
+@deffnx {} BFD_RELOC_860_LOW0
+@deffnx {} BFD_RELOC_860_SPLIT0
+@deffnx {} BFD_RELOC_860_LOW1
+@deffnx {} BFD_RELOC_860_SPLIT1
+@deffnx {} BFD_RELOC_860_LOW2
+@deffnx {} BFD_RELOC_860_SPLIT2
+@deffnx {} BFD_RELOC_860_LOW3
+@deffnx {} BFD_RELOC_860_LOGOT0
+@deffnx {} BFD_RELOC_860_SPGOT0
+@deffnx {} BFD_RELOC_860_LOGOT1
+@deffnx {} BFD_RELOC_860_SPGOT1
+@deffnx {} BFD_RELOC_860_LOGOTOFF0
+@deffnx {} BFD_RELOC_860_SPGOTOFF0
+@deffnx {} BFD_RELOC_860_LOGOTOFF1
+@deffnx {} BFD_RELOC_860_SPGOTOFF1
+@deffnx {} BFD_RELOC_860_LOGOTOFF2
+@deffnx {} BFD_RELOC_860_LOGOTOFF3
+@deffnx {} BFD_RELOC_860_LOPC
+@deffnx {} BFD_RELOC_860_HIGHADJ
+@deffnx {} BFD_RELOC_860_HAGOT
+@deffnx {} BFD_RELOC_860_HAGOTOFF
+@deffnx {} BFD_RELOC_860_HAPC
+@deffnx {} BFD_RELOC_860_HIGH
+@deffnx {} BFD_RELOC_860_HIGOT
+@deffnx {} BFD_RELOC_860_HIGOTOFF
+Intel i860 Relocations.
+@end deffn
+@deffn {} BFD_RELOC_OPENRISC_ABS_26
+@deffnx {} BFD_RELOC_OPENRISC_REL_26
+OpenRISC Relocations.
+@end deffn
+@deffn {} BFD_RELOC_H8_DIR16A8
+@deffnx {} BFD_RELOC_H8_DIR16R8
+@deffnx {} BFD_RELOC_H8_DIR24A8
+@deffnx {} BFD_RELOC_H8_DIR24R8
+@deffnx {} BFD_RELOC_H8_DIR32A16
+H8 elf Relocations.
+@end deffn
+@deffn {} BFD_RELOC_XSTORMY16_REL_12
+@deffnx {} BFD_RELOC_XSTORMY16_12
+@deffnx {} BFD_RELOC_XSTORMY16_24
+@deffnx {} BFD_RELOC_XSTORMY16_FPTR16
+Sony Xstormy16 Relocations.
+@end deffn
+@deffn {} BFD_RELOC_RELC
+Self-describing complex relocations.
+@end deffn
+@deffn {} BFD_RELOC_XC16X_PAG
+@deffnx {} BFD_RELOC_XC16X_POF
+@deffnx {} BFD_RELOC_XC16X_SEG
+@deffnx {} BFD_RELOC_XC16X_SOF
+Infineon Relocations.
+@end deffn
+@deffn {} BFD_RELOC_VAX_GLOB_DAT
+@deffnx {} BFD_RELOC_VAX_JMP_SLOT
+@deffnx {} BFD_RELOC_VAX_RELATIVE
+Relocations used by VAX ELF.
+@end deffn
+@deffn {} BFD_RELOC_MT_PC16
+Morpho MT - 16 bit immediate relocation.
+@end deffn
+@deffn {} BFD_RELOC_MT_HI16
+Morpho MT - Hi 16 bits of an address.
+@end deffn
+@deffn {} BFD_RELOC_MT_LO16
+Morpho MT - Low 16 bits of an address.
+@end deffn
+@deffn {} BFD_RELOC_MT_GNU_VTINHERIT
+Morpho MT - Used to tell the linker which vtable entries are used.
+@end deffn
+@deffn {} BFD_RELOC_MT_GNU_VTENTRY
+Morpho MT - Used to tell the linker which vtable entries are used.
+@end deffn
+@deffn {} BFD_RELOC_MT_PCINSN8
+Morpho MT - 8 bit immediate relocation.
+@end deffn
+@deffn {} BFD_RELOC_MSP430_10_PCREL
+@deffnx {} BFD_RELOC_MSP430_16_PCREL
+@deffnx {} BFD_RELOC_MSP430_16
+@deffnx {} BFD_RELOC_MSP430_16_PCREL_BYTE
+@deffnx {} BFD_RELOC_MSP430_16_BYTE
+@deffnx {} BFD_RELOC_MSP430_2X_PCREL
+@deffnx {} BFD_RELOC_MSP430_RL_PCREL
+msp430 specific relocation codes
+@end deffn
+@deffn {} BFD_RELOC_IQ2000_OFFSET_16
+@deffnx {} BFD_RELOC_IQ2000_OFFSET_21
+@deffnx {} BFD_RELOC_IQ2000_UHI16
+IQ2000 Relocations.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_RTLD
+Special Xtensa relocation used only by PLT entries in ELF shared
+objects to indicate that the runtime linker should set the value
+to one of its own internal functions or data structures.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_GLOB_DAT
+@deffnx {} BFD_RELOC_XTENSA_JMP_SLOT
+@deffnx {} BFD_RELOC_XTENSA_RELATIVE
+Xtensa relocations for ELF shared objects.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_PLT
+Xtensa relocation used in ELF object files for symbols that may require
+PLT entries. Otherwise, this is just a generic 32-bit relocation.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_DIFF8
+@deffnx {} BFD_RELOC_XTENSA_DIFF16
+@deffnx {} BFD_RELOC_XTENSA_DIFF32
+Xtensa relocations to mark the difference of two local symbols.
+These are only needed to support linker relaxation and can be ignored
+when not relaxing. The field is set to the value of the difference
+assuming no relaxation. The relocation encodes the position of the
+first symbol so the linker can determine whether to adjust the field
+value.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_SLOT0_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT1_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT2_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT3_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT4_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT5_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT6_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT7_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT8_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT9_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT10_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT11_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT12_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT13_OP
+@deffnx {} BFD_RELOC_XTENSA_SLOT14_OP
+Generic Xtensa relocations for instruction operands. Only the slot
+number is encoded in the relocation. The relocation applies to the
+last PC-relative immediate operand, or if there are no PC-relative
+immediates, to the last immediate operand.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_SLOT0_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT1_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT2_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT3_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT4_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT5_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT6_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT7_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT8_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT9_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT10_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT11_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT12_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT13_ALT
+@deffnx {} BFD_RELOC_XTENSA_SLOT14_ALT
+Alternate Xtensa relocations. Only the slot is encoded in the
+relocation. The meaning of these relocations is opcode-specific.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_OP0
+@deffnx {} BFD_RELOC_XTENSA_OP1
+@deffnx {} BFD_RELOC_XTENSA_OP2
+Xtensa relocations for backward compatibility. These have all been
+replaced by BFD_RELOC_XTENSA_SLOT0_OP.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_ASM_EXPAND
+Xtensa relocation to mark that the assembler expanded the
+instructions from an original target. The expansion size is
+encoded in the reloc size.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_ASM_SIMPLIFY
+Xtensa relocation to mark that the linker should simplify
+assembler-expanded instructions. This is commonly used
+internally by the linker after analysis of a
+BFD_RELOC_XTENSA_ASM_EXPAND.
+@end deffn
+@deffn {} BFD_RELOC_XTENSA_TLSDESC_FN
+@deffnx {} BFD_RELOC_XTENSA_TLSDESC_ARG
+@deffnx {} BFD_RELOC_XTENSA_TLS_DTPOFF
+@deffnx {} BFD_RELOC_XTENSA_TLS_TPOFF
+@deffnx {} BFD_RELOC_XTENSA_TLS_FUNC
+@deffnx {} BFD_RELOC_XTENSA_TLS_ARG
+@deffnx {} BFD_RELOC_XTENSA_TLS_CALL
+Xtensa TLS relocations.
+@end deffn
+@deffn {} BFD_RELOC_Z80_DISP8
+8 bit signed offset in (ix+d) or (iy+d).
+@end deffn
+@deffn {} BFD_RELOC_Z8K_DISP7
+DJNZ offset.
+@end deffn
+@deffn {} BFD_RELOC_Z8K_CALLR
+CALR offset.
+@end deffn
+@deffn {} BFD_RELOC_Z8K_IMM4L
+4 bit value.
+@end deffn
+@deffn {} BFD_RELOC_LM32_CALL
+@deffnx {} BFD_RELOC_LM32_BRANCH
+@deffnx {} BFD_RELOC_LM32_16_GOT
+@deffnx {} BFD_RELOC_LM32_GOTOFF_HI16
+@deffnx {} BFD_RELOC_LM32_GOTOFF_LO16
+@deffnx {} BFD_RELOC_LM32_COPY
+@deffnx {} BFD_RELOC_LM32_GLOB_DAT
+@deffnx {} BFD_RELOC_LM32_JMP_SLOT
+@deffnx {} BFD_RELOC_LM32_RELATIVE
+Lattice Mico32 relocations.
+@end deffn
+@deffn {} BFD_RELOC_MACH_O_SECTDIFF
+Difference between two section addreses. Must be followed by a
+BFD_RELOC_MACH_O_PAIR.
+@end deffn
+@deffn {} BFD_RELOC_MACH_O_PAIR
+Mach-O generic relocations.
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_32_LO
+This is a 32 bit reloc for the microblaze that stores the
+low 16 bits of a value
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_32_LO_PCREL
+This is a 32 bit pc-relative reloc for the microblaze that
+stores the low 16 bits of a value
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_32_ROSDA
+This is a 32 bit reloc for the microblaze that stores a
+value relative to the read-only small data area anchor
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_32_RWSDA
+This is a 32 bit reloc for the microblaze that stores a
+value relative to the read-write small data area anchor
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM
+This is a 32 bit reloc for the microblaze to handle
+expressions of the form "Symbol Op Symbol"
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_64_NONE
+This is a 64 bit reloc that stores the 32 bit pc relative
+value in two words (with an imm instruction). No relocation is
+done here - only used for relaxing
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_64_GOTPC
+This is a 64 bit reloc that stores the 32 bit pc relative
+value in two words (with an imm instruction). The relocation is
+PC-relative GOT offset
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_64_GOT
+This is a 64 bit reloc that stores the 32 bit pc relative
+value in two words (with an imm instruction). The relocation is
+GOT offset
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_64_PLT
+This is a 64 bit reloc that stores the 32 bit pc relative
+value in two words (with an imm instruction). The relocation is
+PC-relative offset into PLT
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_64_GOTOFF
+This is a 64 bit reloc that stores the 32 bit GOT relative
+value in two words (with an imm instruction). The relocation is
+relative offset from _GLOBAL_OFFSET_TABLE_
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_32_GOTOFF
+This is a 32 bit reloc that stores the 32 bit GOT relative
+value in a word. The relocation is relative offset from
+@end deffn
+@deffn {} BFD_RELOC_MICROBLAZE_COPY
+This is used to tell the dynamic linker to copy the value out of
+the dynamic object into the runtime process image.
+@end deffn
+
+@example
+
+typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
+@end example
+@findex bfd_reloc_type_lookup
+@subsubsection @code{bfd_reloc_type_lookup}
+@strong{Synopsis}
+@example
+reloc_howto_type *bfd_reloc_type_lookup
+ (bfd *abfd, bfd_reloc_code_real_type code);
+reloc_howto_type *bfd_reloc_name_lookup
+ (bfd *abfd, const char *reloc_name);
+@end example
+@strong{Description}@*
+Return a pointer to a howto structure which, when
+invoked, will perform the relocation @var{code} on data from the
+architecture noted.
+
+@findex bfd_default_reloc_type_lookup
+@subsubsection @code{bfd_default_reloc_type_lookup}
+@strong{Synopsis}
+@example
+reloc_howto_type *bfd_default_reloc_type_lookup
+ (bfd *abfd, bfd_reloc_code_real_type code);
+@end example
+@strong{Description}@*
+Provides a default relocation lookup routine for any architecture.
+
+@findex bfd_get_reloc_code_name
+@subsubsection @code{bfd_get_reloc_code_name}
+@strong{Synopsis}
+@example
+const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code);
+@end example
+@strong{Description}@*
+Provides a printable name for the supplied relocation code.
+Useful mainly for printing error messages.
+
+@findex bfd_generic_relax_section
+@subsubsection @code{bfd_generic_relax_section}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_generic_relax_section
+ (bfd *abfd,
+ asection *section,
+ struct bfd_link_info *,
+ bfd_boolean *);
+@end example
+@strong{Description}@*
+Provides default handling for relaxing for back ends which
+don't do relaxing.
+
+@findex bfd_generic_gc_sections
+@subsubsection @code{bfd_generic_gc_sections}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_generic_gc_sections
+ (bfd *, struct bfd_link_info *);
+@end example
+@strong{Description}@*
+Provides default handling for relaxing for back ends which
+don't do section gc -- i.e., does nothing.
+
+@findex bfd_generic_merge_sections
+@subsubsection @code{bfd_generic_merge_sections}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_generic_merge_sections
+ (bfd *, struct bfd_link_info *);
+@end example
+@strong{Description}@*
+Provides default handling for SEC_MERGE section merging for back ends
+which don't have SEC_MERGE support -- i.e., does nothing.
+
+@findex bfd_generic_get_relocated_section_contents
+@subsubsection @code{bfd_generic_get_relocated_section_contents}
+@strong{Synopsis}
+@example
+bfd_byte *bfd_generic_get_relocated_section_contents
+ (bfd *abfd,
+ struct bfd_link_info *link_info,
+ struct bfd_link_order *link_order,
+ bfd_byte *data,
+ bfd_boolean relocatable,
+ asymbol **symbols);
+@end example
+@strong{Description}@*
+Provides default handling of relocation effort for back ends
+which can't be bothered to do it efficiently.
+
diff --git a/bfd/doc/section.texi b/bfd/doc/section.texi
new file mode 100644
index 00000000000..51a9e198982
--- /dev/null
+++ b/bfd/doc/section.texi
@@ -0,0 +1,1007 @@
+@section Sections
+The raw data contained within a BFD is maintained through the
+section abstraction. A single BFD may have any number of
+sections. It keeps hold of them by pointing to the first;
+each one points to the next in the list.
+
+Sections are supported in BFD in @code{section.c}.
+
+@menu
+* Section Input::
+* Section Output::
+* typedef asection::
+* section prototypes::
+@end menu
+
+@node Section Input, Section Output, Sections, Sections
+@subsection Section input
+When a BFD is opened for reading, the section structures are
+created and attached to the BFD.
+
+Each section has a name which describes the section in the
+outside world---for example, @code{a.out} would contain at least
+three sections, called @code{.text}, @code{.data} and @code{.bss}.
+
+Names need not be unique; for example a COFF file may have several
+sections named @code{.data}.
+
+Sometimes a BFD will contain more than the ``natural'' number of
+sections. A back end may attach other sections containing
+constructor data, or an application may add a section (using
+@code{bfd_make_section}) to the sections attached to an already open
+BFD. For example, the linker creates an extra section
+@code{COMMON} for each input file's BFD to hold information about
+common storage.
+
+The raw data is not necessarily read in when
+the section descriptor is created. Some targets may leave the
+data in place until a @code{bfd_get_section_contents} call is
+made. Other back ends may read in all the data at once. For
+example, an S-record file has to be read once to determine the
+size of the data. An IEEE-695 file doesn't contain raw data in
+sections, but data and relocation expressions intermixed, so
+the data area has to be parsed to get out the data and
+relocations.
+
+@node Section Output, typedef asection, Section Input, Sections
+@subsection Section output
+To write a new object style BFD, the various sections to be
+written have to be created. They are attached to the BFD in
+the same way as input sections; data is written to the
+sections using @code{bfd_set_section_contents}.
+
+Any program that creates or combines sections (e.g., the assembler
+and linker) must use the @code{asection} fields @code{output_section} and
+@code{output_offset} to indicate the file sections to which each
+section must be written. (If the section is being created from
+scratch, @code{output_section} should probably point to the section
+itself and @code{output_offset} should probably be zero.)
+
+The data to be written comes from input sections attached
+(via @code{output_section} pointers) to
+the output sections. The output section structure can be
+considered a filter for the input section: the output section
+determines the vma of the output data and the name, but the
+input section determines the offset into the output section of
+the data to be written.
+
+E.g., to create a section "O", starting at 0x100, 0x123 long,
+containing two subsections, "A" at offset 0x0 (i.e., at vma
+0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the @code{asection}
+structures would look like:
+
+@example
+ section name "A"
+ output_offset 0x00
+ size 0x20
+ output_section -----------> section name "O"
+ | vma 0x100
+ section name "B" | size 0x123
+ output_offset 0x20 |
+ size 0x103 |
+ output_section --------|
+@end example
+
+@subsection Link orders
+The data within a section is stored in a @dfn{link_order}.
+These are much like the fixups in @code{gas}. The link_order
+abstraction allows a section to grow and shrink within itself.
+
+A link_order knows how big it is, and which is the next
+link_order and where the raw data for it is; it also points to
+a list of relocations which apply to it.
+
+The link_order is used by the linker to perform relaxing on
+final code. The compiler creates code which is as big as
+necessary to make it work without relaxing, and the user can
+select whether to relax. Sometimes relaxing takes a lot of
+time. The linker runs around the relocations to see if any
+are attached to data which can be shrunk, if so it does it on
+a link_order by link_order basis.
+
+
+@node typedef asection, section prototypes, Section Output, Sections
+@subsection typedef asection
+Here is the section structure:
+
+
+@example
+
+typedef struct bfd_section
+@{
+ /* The name of the section; the name isn't a copy, the pointer is
+ the same as that passed to bfd_make_section. */
+ const char *name;
+
+ /* A unique sequence number. */
+ int id;
+
+ /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */
+ int index;
+
+ /* The next section in the list belonging to the BFD, or NULL. */
+ struct bfd_section *next;
+
+ /* The previous section in the list belonging to the BFD, or NULL. */
+ struct bfd_section *prev;
+
+ /* The field flags contains attributes of the section. Some
+ flags are read in from the object file, and some are
+ synthesized from other information. */
+ flagword flags;
+
+#define SEC_NO_FLAGS 0x000
+
+ /* Tells the OS to allocate space for this section when loading.
+ This is clear for a section containing debug information only. */
+#define SEC_ALLOC 0x001
+
+ /* Tells the OS to load the section from the file when loading.
+ This is clear for a .bss section. */
+#define SEC_LOAD 0x002
+
+ /* The section contains data still to be relocated, so there is
+ some relocation information too. */
+#define SEC_RELOC 0x004
+
+ /* A signal to the OS that the section contains read only data. */
+#define SEC_READONLY 0x008
+
+ /* The section contains code only. */
+#define SEC_CODE 0x010
+
+ /* The section contains data only. */
+#define SEC_DATA 0x020
+
+ /* The section will reside in ROM. */
+#define SEC_ROM 0x040
+
+ /* The section contains constructor information. This section
+ type is used by the linker to create lists of constructors and
+ destructors used by @code{g++}. When a back end sees a symbol
+ which should be used in a constructor list, it creates a new
+ section for the type of name (e.g., @code{__CTOR_LIST__}), attaches
+ the symbol to it, and builds a relocation. To build the lists
+ of constructors, all the linker has to do is catenate all the
+ sections called @code{__CTOR_LIST__} and relocate the data
+ contained within - exactly the operations it would peform on
+ standard data. */
+#define SEC_CONSTRUCTOR 0x080
+
+ /* The section has contents - a data section could be
+ @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be
+ @code{SEC_HAS_CONTENTS} */
+#define SEC_HAS_CONTENTS 0x100
+
+ /* An instruction to the linker to not output the section
+ even if it has information which would normally be written. */
+#define SEC_NEVER_LOAD 0x200
+
+ /* The section contains thread local data. */
+#define SEC_THREAD_LOCAL 0x400
+
+ /* The section has GOT references. This flag is only for the
+ linker, and is currently only used by the elf32-hppa back end.
+ It will be set if global offset table references were detected
+ in this section, which indicate to the linker that the section
+ contains PIC code, and must be handled specially when doing a
+ static link. */
+#define SEC_HAS_GOT_REF 0x800
+
+ /* The section contains common symbols (symbols may be defined
+ multiple times, the value of a symbol is the amount of
+ space it requires, and the largest symbol value is the one
+ used). Most targets have exactly one of these (which we
+ translate to bfd_com_section_ptr), but ECOFF has two. */
+#define SEC_IS_COMMON 0x1000
+
+ /* The section contains only debugging information. For
+ example, this is set for ELF .debug and .stab sections.
+ strip tests this flag to see if a section can be
+ discarded. */
+#define SEC_DEBUGGING 0x2000
+
+ /* The contents of this section are held in memory pointed to
+ by the contents field. This is checked by bfd_get_section_contents,
+ and the data is retrieved from memory if appropriate. */
+#define SEC_IN_MEMORY 0x4000
+
+ /* The contents of this section are to be excluded by the
+ linker for executable and shared objects unless those
+ objects are to be further relocated. */
+#define SEC_EXCLUDE 0x8000
+
+ /* The contents of this section are to be sorted based on the sum of
+ the symbol and addend values specified by the associated relocation
+ entries. Entries without associated relocation entries will be
+ appended to the end of the section in an unspecified order. */
+#define SEC_SORT_ENTRIES 0x10000
+
+ /* When linking, duplicate sections of the same name should be
+ discarded, rather than being combined into a single section as
+ is usually done. This is similar to how common symbols are
+ handled. See SEC_LINK_DUPLICATES below. */
+#define SEC_LINK_ONCE 0x20000
+
+ /* If SEC_LINK_ONCE is set, this bitfield describes how the linker
+ should handle duplicate sections. */
+#define SEC_LINK_DUPLICATES 0xc0000
+
+ /* This value for SEC_LINK_DUPLICATES means that duplicate
+ sections with the same name should simply be discarded. */
+#define SEC_LINK_DUPLICATES_DISCARD 0x0
+
+ /* This value for SEC_LINK_DUPLICATES means that the linker
+ should warn if there are any duplicate sections, although
+ it should still only link one copy. */
+#define SEC_LINK_DUPLICATES_ONE_ONLY 0x40000
+
+ /* This value for SEC_LINK_DUPLICATES means that the linker
+ should warn if any duplicate sections are a different size. */
+#define SEC_LINK_DUPLICATES_SAME_SIZE 0x80000
+
+ /* This value for SEC_LINK_DUPLICATES means that the linker
+ should warn if any duplicate sections contain different
+ contents. */
+#define SEC_LINK_DUPLICATES_SAME_CONTENTS \
+ (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE)
+
+ /* This section was created by the linker as part of dynamic
+ relocation or other arcane processing. It is skipped when
+ going through the first-pass output, trusting that someone
+ else up the line will take care of it later. */
+#define SEC_LINKER_CREATED 0x100000
+
+ /* This section should not be subject to garbage collection.
+ Also set to inform the linker that this section should not be
+ listed in the link map as discarded. */
+#define SEC_KEEP 0x200000
+
+ /* This section contains "short" data, and should be placed
+ "near" the GP. */
+#define SEC_SMALL_DATA 0x400000
+
+ /* Attempt to merge identical entities in the section.
+ Entity size is given in the entsize field. */
+#define SEC_MERGE 0x800000
+
+ /* If given with SEC_MERGE, entities to merge are zero terminated
+ strings where entsize specifies character size instead of fixed
+ size entries. */
+#define SEC_STRINGS 0x1000000
+
+ /* This section contains data about section groups. */
+#define SEC_GROUP 0x2000000
+
+ /* The section is a COFF shared library section. This flag is
+ only for the linker. If this type of section appears in
+ the input file, the linker must copy it to the output file
+ without changing the vma or size. FIXME: Although this
+ was originally intended to be general, it really is COFF
+ specific (and the flag was renamed to indicate this). It
+ might be cleaner to have some more general mechanism to
+ allow the back end to control what the linker does with
+ sections. */
+#define SEC_COFF_SHARED_LIBRARY 0x4000000
+
+ /* This section contains data which may be shared with other
+ executables or shared objects. This is for COFF only. */
+#define SEC_COFF_SHARED 0x8000000
+
+ /* When a section with this flag is being linked, then if the size of
+ the input section is less than a page, it should not cross a page
+ boundary. If the size of the input section is one page or more,
+ it should be aligned on a page boundary. This is for TI
+ TMS320C54X only. */
+#define SEC_TIC54X_BLOCK 0x10000000
+
+ /* Conditionally link this section; do not link if there are no
+ references found to any symbol in the section. This is for TI
+ TMS320C54X only. */
+#define SEC_TIC54X_CLINK 0x20000000
+
+ /* Indicate that section has the no read flag set. This happens
+ when memory read flag isn't set. */
+#define SEC_COFF_NOREAD 0x40000000
+
+ /* End of section flags. */
+
+ /* Some internal packed boolean fields. */
+
+ /* See the vma field. */
+ unsigned int user_set_vma : 1;
+
+ /* A mark flag used by some of the linker backends. */
+ unsigned int linker_mark : 1;
+
+ /* Another mark flag used by some of the linker backends. Set for
+ output sections that have an input section. */
+ unsigned int linker_has_input : 1;
+
+ /* Mark flag used by some linker backends for garbage collection. */
+ unsigned int gc_mark : 1;
+
+ /* The following flags are used by the ELF linker. */
+
+ /* Mark sections which have been allocated to segments. */
+ unsigned int segment_mark : 1;
+
+ /* Type of sec_info information. */
+ unsigned int sec_info_type:3;
+#define ELF_INFO_TYPE_NONE 0
+#define ELF_INFO_TYPE_STABS 1
+#define ELF_INFO_TYPE_MERGE 2
+#define ELF_INFO_TYPE_EH_FRAME 3
+#define ELF_INFO_TYPE_JUST_SYMS 4
+
+ /* Nonzero if this section uses RELA relocations, rather than REL. */
+ unsigned int use_rela_p:1;
+
+ /* Bits used by various backends. The generic code doesn't touch
+ these fields. */
+
+ /* Nonzero if this section has TLS related relocations. */
+ unsigned int has_tls_reloc:1;
+
+ /* Nonzero if this section has a call to __tls_get_addr. */
+ unsigned int has_tls_get_addr_call:1;
+
+ /* Nonzero if this section has a gp reloc. */
+ unsigned int has_gp_reloc:1;
+
+ /* Nonzero if this section needs the relax finalize pass. */
+ unsigned int need_finalize_relax:1;
+
+ /* Whether relocations have been processed. */
+ unsigned int reloc_done : 1;
+
+ /* End of internal packed boolean fields. */
+
+ /* The virtual memory address of the section - where it will be
+ at run time. The symbols are relocated against this. The
+ user_set_vma flag is maintained by bfd; if it's not set, the
+ backend can assign addresses (for example, in @code{a.out}, where
+ the default address for @code{.data} is dependent on the specific
+ target and various flags). */
+ bfd_vma vma;
+
+ /* The load address of the section - where it would be in a
+ rom image; really only used for writing section header
+ information. */
+ bfd_vma lma;
+
+ /* The size of the section in octets, as it will be output.
+ Contains a value even if the section has no contents (e.g., the
+ size of @code{.bss}). */
+ bfd_size_type size;
+
+ /* For input sections, the original size on disk of the section, in
+ octets. This field should be set for any section whose size is
+ changed by linker relaxation. It is required for sections where
+ the linker relaxation scheme doesn't cache altered section and
+ reloc contents (stabs, eh_frame, SEC_MERGE, some coff relaxing
+ targets), and thus the original size needs to be kept to read the
+ section multiple times. For output sections, rawsize holds the
+ section size calculated on a previous linker relaxation pass. */
+ bfd_size_type rawsize;
+
+ /* Relaxation table. */
+ struct relax_table *relax;
+
+ /* Count of used relaxation table entries. */
+ int relax_count;
+
+
+ /* If this section is going to be output, then this value is the
+ offset in *bytes* into the output section of the first byte in the
+ input section (byte ==> smallest addressable unit on the
+ target). In most cases, if this was going to start at the
+ 100th octet (8-bit quantity) in the output section, this value
+ would be 100. However, if the target byte size is 16 bits
+ (bfd_octets_per_byte is "2"), this value would be 50. */
+ bfd_vma output_offset;
+
+ /* The output section through which to map on output. */
+ struct bfd_section *output_section;
+
+ /* The alignment requirement of the section, as an exponent of 2 -
+ e.g., 3 aligns to 2^3 (or 8). */
+ unsigned int alignment_power;
+
+ /* If an input section, a pointer to a vector of relocation
+ records for the data in this section. */
+ struct reloc_cache_entry *relocation;
+
+ /* If an output section, a pointer to a vector of pointers to
+ relocation records for the data in this section. */
+ struct reloc_cache_entry **orelocation;
+
+ /* The number of relocation records in one of the above. */
+ unsigned reloc_count;
+
+ /* Information below is back end specific - and not always used
+ or updated. */
+
+ /* File position of section data. */
+ file_ptr filepos;
+
+ /* File position of relocation info. */
+ file_ptr rel_filepos;
+
+ /* File position of line data. */
+ file_ptr line_filepos;
+
+ /* Pointer to data for applications. */
+ void *userdata;
+
+ /* If the SEC_IN_MEMORY flag is set, this points to the actual
+ contents. */
+ unsigned char *contents;
+
+ /* Attached line number information. */
+ alent *lineno;
+
+ /* Number of line number records. */
+ unsigned int lineno_count;
+
+ /* Entity size for merging purposes. */
+ unsigned int entsize;
+
+ /* Points to the kept section if this section is a link-once section,
+ and is discarded. */
+ struct bfd_section *kept_section;
+
+ /* When a section is being output, this value changes as more
+ linenumbers are written out. */
+ file_ptr moving_line_filepos;
+
+ /* What the section number is in the target world. */
+ int target_index;
+
+ void *used_by_bfd;
+
+ /* If this is a constructor section then here is a list of the
+ relocations created to relocate items within it. */
+ struct relent_chain *constructor_chain;
+
+ /* The BFD which owns the section. */
+ bfd *owner;
+
+ /* A symbol which points at this section only. */
+ struct bfd_symbol *symbol;
+ struct bfd_symbol **symbol_ptr_ptr;
+
+ /* Early in the link process, map_head and map_tail are used to build
+ a list of input sections attached to an output section. Later,
+ output sections use these fields for a list of bfd_link_order
+ structs. */
+ union @{
+ struct bfd_link_order *link_order;
+ struct bfd_section *s;
+ @} map_head, map_tail;
+@} asection;
+
+/* Relax table contains information about instructions which can
+ be removed by relaxation -- replacing a long address with a
+ short address. */
+struct relax_table @{
+ /* Address where bytes may be deleted. */
+ bfd_vma addr;
+
+ /* Number of bytes to be deleted. */
+ int size;
+@};
+
+/* These sections are global, and are managed by BFD. The application
+ and target back end are not permitted to change the values in
+ these sections. New code should use the section_ptr macros rather
+ than referring directly to the const sections. The const sections
+ may eventually vanish. */
+#define BFD_ABS_SECTION_NAME "*ABS*"
+#define BFD_UND_SECTION_NAME "*UND*"
+#define BFD_COM_SECTION_NAME "*COM*"
+#define BFD_IND_SECTION_NAME "*IND*"
+
+/* The absolute section. */
+extern asection bfd_abs_section;
+#define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
+#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
+/* Pointer to the undefined section. */
+extern asection bfd_und_section;
+#define bfd_und_section_ptr ((asection *) &bfd_und_section)
+#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
+/* Pointer to the common section. */
+extern asection bfd_com_section;
+#define bfd_com_section_ptr ((asection *) &bfd_com_section)
+/* Pointer to the indirect section. */
+extern asection bfd_ind_section;
+#define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
+#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)
+
+#define bfd_is_const_section(SEC) \
+ ( ((SEC) == bfd_abs_section_ptr) \
+ || ((SEC) == bfd_und_section_ptr) \
+ || ((SEC) == bfd_com_section_ptr) \
+ || ((SEC) == bfd_ind_section_ptr))
+
+/* Macros to handle insertion and deletion of a bfd's sections. These
+ only handle the list pointers, ie. do not adjust section_count,
+ target_index etc. */
+#define bfd_section_list_remove(ABFD, S) \
+ do \
+ @{ \
+ asection *_s = S; \
+ asection *_next = _s->next; \
+ asection *_prev = _s->prev; \
+ if (_prev) \
+ _prev->next = _next; \
+ else \
+ (ABFD)->sections = _next; \
+ if (_next) \
+ _next->prev = _prev; \
+ else \
+ (ABFD)->section_last = _prev; \
+ @} \
+ while (0)
+#define bfd_section_list_append(ABFD, S) \
+ do \
+ @{ \
+ asection *_s = S; \
+ bfd *_abfd = ABFD; \
+ _s->next = NULL; \
+ if (_abfd->section_last) \
+ @{ \
+ _s->prev = _abfd->section_last; \
+ _abfd->section_last->next = _s; \
+ @} \
+ else \
+ @{ \
+ _s->prev = NULL; \
+ _abfd->sections = _s; \
+ @} \
+ _abfd->section_last = _s; \
+ @} \
+ while (0)
+#define bfd_section_list_prepend(ABFD, S) \
+ do \
+ @{ \
+ asection *_s = S; \
+ bfd *_abfd = ABFD; \
+ _s->prev = NULL; \
+ if (_abfd->sections) \
+ @{ \
+ _s->next = _abfd->sections; \
+ _abfd->sections->prev = _s; \
+ @} \
+ else \
+ @{ \
+ _s->next = NULL; \
+ _abfd->section_last = _s; \
+ @} \
+ _abfd->sections = _s; \
+ @} \
+ while (0)
+#define bfd_section_list_insert_after(ABFD, A, S) \
+ do \
+ @{ \
+ asection *_a = A; \
+ asection *_s = S; \
+ asection *_next = _a->next; \
+ _s->next = _next; \
+ _s->prev = _a; \
+ _a->next = _s; \
+ if (_next) \
+ _next->prev = _s; \
+ else \
+ (ABFD)->section_last = _s; \
+ @} \
+ while (0)
+#define bfd_section_list_insert_before(ABFD, B, S) \
+ do \
+ @{ \
+ asection *_b = B; \
+ asection *_s = S; \
+ asection *_prev = _b->prev; \
+ _s->prev = _prev; \
+ _s->next = _b; \
+ _b->prev = _s; \
+ if (_prev) \
+ _prev->next = _s; \
+ else \
+ (ABFD)->sections = _s; \
+ @} \
+ while (0)
+#define bfd_section_removed_from_list(ABFD, S) \
+ ((S)->next == NULL ? (ABFD)->section_last != (S) : (S)->next->prev != (S))
+
+#define BFD_FAKE_SECTION(SEC, FLAGS, SYM, NAME, IDX) \
+ /* name, id, index, next, prev, flags, user_set_vma, */ \
+ @{ NAME, IDX, 0, NULL, NULL, FLAGS, 0, \
+ \
+ /* linker_mark, linker_has_input, gc_mark, */ \
+ 0, 0, 1, \
+ \
+ /* segment_mark, sec_info_type, use_rela_p, has_tls_reloc, */ \
+ 0, 0, 0, 0, \
+ \
+ /* has_tls_get_addr_call, has_gp_reloc, need_finalize_relax, */ \
+ 0, 0, 0, \
+ \
+ /* reloc_done, vma, lma, size, rawsize, relax, relax_count, */ \
+ 0, 0, 0, 0, 0, 0, 0, \
+ \
+ /* output_offset, output_section, alignment_power, */ \
+ 0, (struct bfd_section *) &SEC, 0, \
+ \
+ /* relocation, orelocation, reloc_count, filepos, rel_filepos, */ \
+ NULL, NULL, 0, 0, 0, \
+ \
+ /* line_filepos, userdata, contents, lineno, lineno_count, */ \
+ 0, NULL, NULL, NULL, 0, \
+ \
+ /* entsize, kept_section, moving_line_filepos, */ \
+ 0, NULL, 0, \
+ \
+ /* target_index, used_by_bfd, constructor_chain, owner, */ \
+ 0, NULL, NULL, NULL, \
+ \
+ /* symbol, symbol_ptr_ptr, */ \
+ (struct bfd_symbol *) SYM, &SEC.symbol, \
+ \
+ /* map_head, map_tail */ \
+ @{ NULL @}, @{ NULL @} \
+ @}
+
+@end example
+
+@node section prototypes, , typedef asection, Sections
+@subsection Section prototypes
+These are the functions exported by the section handling part of BFD.
+
+@findex bfd_section_list_clear
+@subsubsection @code{bfd_section_list_clear}
+@strong{Synopsis}
+@example
+void bfd_section_list_clear (bfd *);
+@end example
+@strong{Description}@*
+Clears the section list, and also resets the section count and
+hash table entries.
+
+@findex bfd_get_section_by_name
+@subsubsection @code{bfd_get_section_by_name}
+@strong{Synopsis}
+@example
+asection *bfd_get_section_by_name (bfd *abfd, const char *name);
+@end example
+@strong{Description}@*
+Run through @var{abfd} and return the one of the
+@code{asection}s whose name matches @var{name}, otherwise @code{NULL}.
+@xref{Sections}, for more information.
+
+This should only be used in special cases; the normal way to process
+all sections of a given name is to use @code{bfd_map_over_sections} and
+@code{strcmp} on the name (or better yet, base it on the section flags
+or something else) for each section.
+
+@findex bfd_get_section_by_name_if
+@subsubsection @code{bfd_get_section_by_name_if}
+@strong{Synopsis}
+@example
+asection *bfd_get_section_by_name_if
+ (bfd *abfd,
+ const char *name,
+ bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj),
+ void *obj);
+@end example
+@strong{Description}@*
+Call the provided function @var{func} for each section
+attached to the BFD @var{abfd} whose name matches @var{name},
+passing @var{obj} as an argument. The function will be called
+as if by
+
+@example
+ func (abfd, the_section, obj);
+@end example
+
+It returns the first section for which @var{func} returns true,
+otherwise @code{NULL}.
+
+@findex bfd_get_unique_section_name
+@subsubsection @code{bfd_get_unique_section_name}
+@strong{Synopsis}
+@example
+char *bfd_get_unique_section_name
+ (bfd *abfd, const char *templat, int *count);
+@end example
+@strong{Description}@*
+Invent a section name that is unique in @var{abfd} by tacking
+a dot and a digit suffix onto the original @var{templat}. If
+@var{count} is non-NULL, then it specifies the first number
+tried as a suffix to generate a unique name. The value
+pointed to by @var{count} will be incremented in this case.
+
+@findex bfd_make_section_old_way
+@subsubsection @code{bfd_make_section_old_way}
+@strong{Synopsis}
+@example
+asection *bfd_make_section_old_way (bfd *abfd, const char *name);
+@end example
+@strong{Description}@*
+Create a new empty section called @var{name}
+and attach it to the end of the chain of sections for the
+BFD @var{abfd}. An attempt to create a section with a name which
+is already in use returns its pointer without changing the
+section chain.
+
+It has the funny name since this is the way it used to be
+before it was rewritten....
+
+Possible errors are:
+@itemize @bullet
+
+@item
+@code{bfd_error_invalid_operation} -
+If output has already started for this BFD.
+@item
+@code{bfd_error_no_memory} -
+If memory allocation fails.
+@end itemize
+
+@findex bfd_make_section_anyway_with_flags
+@subsubsection @code{bfd_make_section_anyway_with_flags}
+@strong{Synopsis}
+@example
+asection *bfd_make_section_anyway_with_flags
+ (bfd *abfd, const char *name, flagword flags);
+@end example
+@strong{Description}@*
+Create a new empty section called @var{name} and attach it to the end of
+the chain of sections for @var{abfd}. Create a new section even if there
+is already a section with that name. Also set the attributes of the
+new section to the value @var{flags}.
+
+Return @code{NULL} and set @code{bfd_error} on error; possible errors are:
+@itemize @bullet
+
+@item
+@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}.
+@item
+@code{bfd_error_no_memory} - If memory allocation fails.
+@end itemize
+
+@findex bfd_make_section_anyway
+@subsubsection @code{bfd_make_section_anyway}
+@strong{Synopsis}
+@example
+asection *bfd_make_section_anyway (bfd *abfd, const char *name);
+@end example
+@strong{Description}@*
+Create a new empty section called @var{name} and attach it to the end of
+the chain of sections for @var{abfd}. Create a new section even if there
+is already a section with that name.
+
+Return @code{NULL} and set @code{bfd_error} on error; possible errors are:
+@itemize @bullet
+
+@item
+@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}.
+@item
+@code{bfd_error_no_memory} - If memory allocation fails.
+@end itemize
+
+@findex bfd_make_section_with_flags
+@subsubsection @code{bfd_make_section_with_flags}
+@strong{Synopsis}
+@example
+asection *bfd_make_section_with_flags
+ (bfd *, const char *name, flagword flags);
+@end example
+@strong{Description}@*
+Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling
+bfd_set_error ()) without changing the section chain if there is already a
+section named @var{name}. Also set the attributes of the new section to
+the value @var{flags}. If there is an error, return @code{NULL} and set
+@code{bfd_error}.
+
+@findex bfd_make_section
+@subsubsection @code{bfd_make_section}
+@strong{Synopsis}
+@example
+asection *bfd_make_section (bfd *, const char *name);
+@end example
+@strong{Description}@*
+Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling
+bfd_set_error ()) without changing the section chain if there is already a
+section named @var{name}. If there is an error, return @code{NULL} and set
+@code{bfd_error}.
+
+@findex bfd_set_section_flags
+@subsubsection @code{bfd_set_section_flags}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_section_flags
+ (bfd *abfd, asection *sec, flagword flags);
+@end example
+@strong{Description}@*
+Set the attributes of the section @var{sec} in the BFD
+@var{abfd} to the value @var{flags}. Return @code{TRUE} on success,
+@code{FALSE} on error. Possible error returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_invalid_operation} -
+The section cannot have one or more of the attributes
+requested. For example, a .bss section in @code{a.out} may not
+have the @code{SEC_HAS_CONTENTS} field set.
+@end itemize
+
+@findex bfd_map_over_sections
+@subsubsection @code{bfd_map_over_sections}
+@strong{Synopsis}
+@example
+void bfd_map_over_sections
+ (bfd *abfd,
+ void (*func) (bfd *abfd, asection *sect, void *obj),
+ void *obj);
+@end example
+@strong{Description}@*
+Call the provided function @var{func} for each section
+attached to the BFD @var{abfd}, passing @var{obj} as an
+argument. The function will be called as if by
+
+@example
+ func (abfd, the_section, obj);
+@end example
+
+This is the preferred method for iterating over sections; an
+alternative would be to use a loop:
+
+@example
+ section *p;
+ for (p = abfd->sections; p != NULL; p = p->next)
+ func (abfd, p, ...)
+@end example
+
+@findex bfd_sections_find_if
+@subsubsection @code{bfd_sections_find_if}
+@strong{Synopsis}
+@example
+asection *bfd_sections_find_if
+ (bfd *abfd,
+ bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj),
+ void *obj);
+@end example
+@strong{Description}@*
+Call the provided function @var{operation} for each section
+attached to the BFD @var{abfd}, passing @var{obj} as an
+argument. The function will be called as if by
+
+@example
+ operation (abfd, the_section, obj);
+@end example
+
+It returns the first section for which @var{operation} returns true.
+
+@findex bfd_set_section_size
+@subsubsection @code{bfd_set_section_size}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_section_size
+ (bfd *abfd, asection *sec, bfd_size_type val);
+@end example
+@strong{Description}@*
+Set @var{sec} to the size @var{val}. If the operation is
+ok, then @code{TRUE} is returned, else @code{FALSE}.
+
+Possible error returns:
+@itemize @bullet
+
+@item
+@code{bfd_error_invalid_operation} -
+Writing has started to the BFD, so setting the size is invalid.
+@end itemize
+
+@findex bfd_set_section_contents
+@subsubsection @code{bfd_set_section_contents}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_section_contents
+ (bfd *abfd, asection *section, const void *data,
+ file_ptr offset, bfd_size_type count);
+@end example
+@strong{Description}@*
+Sets the contents of the section @var{section} in BFD
+@var{abfd} to the data starting in memory at @var{data}. The
+data is written to the output section starting at offset
+@var{offset} for @var{count} octets.
+
+Normally @code{TRUE} is returned, else @code{FALSE}. Possible error
+returns are:
+@itemize @bullet
+
+@item
+@code{bfd_error_no_contents} -
+The output section does not have the @code{SEC_HAS_CONTENTS}
+attribute, so nothing can be written to it.
+@item
+and some more too
+@end itemize
+This routine is front end to the back end function
+@code{_bfd_set_section_contents}.
+
+@findex bfd_get_section_contents
+@subsubsection @code{bfd_get_section_contents}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_get_section_contents
+ (bfd *abfd, asection *section, void *location, file_ptr offset,
+ bfd_size_type count);
+@end example
+@strong{Description}@*
+Read data from @var{section} in BFD @var{abfd}
+into memory starting at @var{location}. The data is read at an
+offset of @var{offset} from the start of the input section,
+and is read for @var{count} bytes.
+
+If the contents of a constructor with the @code{SEC_CONSTRUCTOR}
+flag set are requested or if the section does not have the
+@code{SEC_HAS_CONTENTS} flag set, then the @var{location} is filled
+with zeroes. If no errors occur, @code{TRUE} is returned, else
+@code{FALSE}.
+
+@findex bfd_malloc_and_get_section
+@subsubsection @code{bfd_malloc_and_get_section}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_malloc_and_get_section
+ (bfd *abfd, asection *section, bfd_byte **buf);
+@end example
+@strong{Description}@*
+Read all data from @var{section} in BFD @var{abfd}
+into a buffer, *@var{buf}, malloc'd by this function.
+
+@findex bfd_copy_private_section_data
+@subsubsection @code{bfd_copy_private_section_data}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_copy_private_section_data
+ (bfd *ibfd, asection *isec, bfd *obfd, asection *osec);
+@end example
+@strong{Description}@*
+Copy private section information from @var{isec} in the BFD
+@var{ibfd} to the section @var{osec} in the BFD @var{obfd}.
+Return @code{TRUE} on success, @code{FALSE} on error. Possible error
+returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_no_memory} -
+Not enough memory exists to create private data for @var{osec}.
+@end itemize
+@example
+#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
+ BFD_SEND (obfd, _bfd_copy_private_section_data, \
+ (ibfd, isection, obfd, osection))
+@end example
+
+@findex bfd_generic_is_group_section
+@subsubsection @code{bfd_generic_is_group_section}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec);
+@end example
+@strong{Description}@*
+Returns TRUE if @var{sec} is a member of a group.
+
+@findex bfd_generic_discard_group
+@subsubsection @code{bfd_generic_discard_group}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group);
+@end example
+@strong{Description}@*
+Remove all members of @var{group} from the output.
+
diff --git a/bfd/doc/syms.texi b/bfd/doc/syms.texi
new file mode 100644
index 00000000000..d5dc6599f2a
--- /dev/null
+++ b/bfd/doc/syms.texi
@@ -0,0 +1,479 @@
+@section Symbols
+BFD tries to maintain as much symbol information as it can when
+it moves information from file to file. BFD passes information
+to applications though the @code{asymbol} structure. When the
+application requests the symbol table, BFD reads the table in
+the native form and translates parts of it into the internal
+format. To maintain more than the information passed to
+applications, some targets keep some information ``behind the
+scenes'' in a structure only the particular back end knows
+about. For example, the coff back end keeps the original
+symbol table structure as well as the canonical structure when
+a BFD is read in. On output, the coff back end can reconstruct
+the output symbol table so that no information is lost, even
+information unique to coff which BFD doesn't know or
+understand. If a coff symbol table were read, but were written
+through an a.out back end, all the coff specific information
+would be lost. The symbol table of a BFD
+is not necessarily read in until a canonicalize request is
+made. Then the BFD back end fills in a table provided by the
+application with pointers to the canonical information. To
+output symbols, the application provides BFD with a table of
+pointers to pointers to @code{asymbol}s. This allows applications
+like the linker to output a symbol as it was read, since the ``behind
+the scenes'' information will be still available.
+@menu
+* Reading Symbols::
+* Writing Symbols::
+* Mini Symbols::
+* typedef asymbol::
+* symbol handling functions::
+@end menu
+
+@node Reading Symbols, Writing Symbols, Symbols, Symbols
+@subsection Reading symbols
+There are two stages to reading a symbol table from a BFD:
+allocating storage, and the actual reading process. This is an
+excerpt from an application which reads the symbol table:
+
+@example
+ long storage_needed;
+ asymbol **symbol_table;
+ long number_of_symbols;
+ long i;
+
+ storage_needed = bfd_get_symtab_upper_bound (abfd);
+
+ if (storage_needed < 0)
+ FAIL
+
+ if (storage_needed == 0)
+ return;
+
+ symbol_table = xmalloc (storage_needed);
+ ...
+ number_of_symbols =
+ bfd_canonicalize_symtab (abfd, symbol_table);
+
+ if (number_of_symbols < 0)
+ FAIL
+
+ for (i = 0; i < number_of_symbols; i++)
+ process_symbol (symbol_table[i]);
+@end example
+
+All storage for the symbols themselves is in an objalloc
+connected to the BFD; it is freed when the BFD is closed.
+
+@node Writing Symbols, Mini Symbols, Reading Symbols, Symbols
+@subsection Writing symbols
+Writing of a symbol table is automatic when a BFD open for
+writing is closed. The application attaches a vector of
+pointers to pointers to symbols to the BFD being written, and
+fills in the symbol count. The close and cleanup code reads
+through the table provided and performs all the necessary
+operations. The BFD output code must always be provided with an
+``owned'' symbol: one which has come from another BFD, or one
+which has been created using @code{bfd_make_empty_symbol}. Here is an
+example showing the creation of a symbol table with only one element:
+
+@example
+ #include "bfd.h"
+ int main (void)
+ @{
+ bfd *abfd;
+ asymbol *ptrs[2];
+ asymbol *new;
+
+ abfd = bfd_openw ("foo","a.out-sunos-big");
+ bfd_set_format (abfd, bfd_object);
+ new = bfd_make_empty_symbol (abfd);
+ new->name = "dummy_symbol";
+ new->section = bfd_make_section_old_way (abfd, ".text");
+ new->flags = BSF_GLOBAL;
+ new->value = 0x12345;
+
+ ptrs[0] = new;
+ ptrs[1] = 0;
+
+ bfd_set_symtab (abfd, ptrs, 1);
+ bfd_close (abfd);
+ return 0;
+ @}
+
+ ./makesym
+ nm foo
+ 00012345 A dummy_symbol
+@end example
+
+Many formats cannot represent arbitrary symbol information; for
+instance, the @code{a.out} object format does not allow an
+arbitrary number of sections. A symbol pointing to a section
+which is not one of @code{.text}, @code{.data} or @code{.bss} cannot
+be described.
+
+@node Mini Symbols, typedef asymbol, Writing Symbols, Symbols
+@subsection Mini Symbols
+Mini symbols provide read-only access to the symbol table.
+They use less memory space, but require more time to access.
+They can be useful for tools like nm or objdump, which may
+have to handle symbol tables of extremely large executables.
+
+The @code{bfd_read_minisymbols} function will read the symbols
+into memory in an internal form. It will return a @code{void *}
+pointer to a block of memory, a symbol count, and the size of
+each symbol. The pointer is allocated using @code{malloc}, and
+should be freed by the caller when it is no longer needed.
+
+The function @code{bfd_minisymbol_to_symbol} will take a pointer
+to a minisymbol, and a pointer to a structure returned by
+@code{bfd_make_empty_symbol}, and return a @code{asymbol} structure.
+The return value may or may not be the same as the value from
+@code{bfd_make_empty_symbol} which was passed in.
+
+
+@node typedef asymbol, symbol handling functions, Mini Symbols, Symbols
+@subsection typedef asymbol
+An @code{asymbol} has the form:
+
+
+@example
+
+typedef struct bfd_symbol
+@{
+ /* 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; @code{static} in @code{C}. The value
+ is the offset into the section of the data. */
+#define BSF_LOCAL (1 << 0)
+
+ /* The symbol has global scope; initialized data in @code{C}. The
+ value is the offset into the section of the data. */
+#define BSF_GLOBAL (1 << 1)
+
+ /* 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:
+ @code{BSF_LOCAL}, @code{BSF_COMMON}, @code{BSF_UNDEFINED} or
+ @code{BSF_GLOBAL}. */
+
+ /* The symbol is a debugging record. The value has an arbitrary
+ meaning, unless BSF_DEBUGGING_RELOC is also set. */
+#define BSF_DEBUGGING (1 << 2)
+
+ /* The symbol denotes a function entry point. Used in ELF,
+ perhaps others someday. */
+#define BSF_FUNCTION (1 << 3)
+
+ /* Used by the linker. */
+#define BSF_KEEP (1 << 5)
+#define BSF_KEEP_G (1 << 6)
+
+ /* A weak global symbol, overridable without warnings by
+ a regular global symbol of the same name. */
+#define BSF_WEAK (1 << 7)
+
+ /* This symbol was created to point to a section, e.g. ELF's
+ STT_SECTION symbols. */
+#define BSF_SECTION_SYM (1 << 8)
+
+ /* The symbol used to be a common symbol, but now it is
+ allocated. */
+#define BSF_OLD_COMMON (1 << 9)
+
+ /* In some files the type of a symbol sometimes alters its
+ location in an output file - ie in coff a @code{ISFCN} symbol
+ which is also @code{C_EXT} symbol appears where it was
+ declared and not at the end of a section. This bit is set
+ by the target BFD part to convey this information. */
+#define BSF_NOT_AT_END (1 << 10)
+
+ /* Signal that the symbol is the label of constructor section. */
+#define BSF_CONSTRUCTOR (1 << 11)
+
+ /* Signal that the symbol is a warning symbol. The name is a
+ warning. The name of the next symbol is the one to warn about;
+ if a reference is made to a symbol with the same name as the next
+ symbol, a warning is issued by the linker. */
+#define BSF_WARNING (1 << 12)
+
+ /* Signal that the symbol is indirect. This symbol is an indirect
+ pointer to the symbol with the same name as the next symbol. */
+#define BSF_INDIRECT (1 << 13)
+
+ /* BSF_FILE marks symbols that contain a file name. This is used
+ for ELF STT_FILE symbols. */
+#define BSF_FILE (1 << 14)
+
+ /* Symbol is from dynamic linking information. */
+#define BSF_DYNAMIC (1 << 15)
+
+ /* The symbol denotes a data object. Used in ELF, and perhaps
+ others someday. */
+#define BSF_OBJECT (1 << 16)
+
+ /* This symbol is a debugging symbol. The value is the offset
+ into the section of the data. BSF_DEBUGGING should be set
+ as well. */
+#define BSF_DEBUGGING_RELOC (1 << 17)
+
+ /* This symbol is thread local. Used in ELF. */
+#define BSF_THREAD_LOCAL (1 << 18)
+
+ /* This symbol represents a complex relocation expression,
+ with the expression tree serialized in the symbol name. */
+#define BSF_RELC (1 << 19)
+
+ /* This symbol represents a signed complex relocation expression,
+ with the expression tree serialized in the symbol name. */
+#define BSF_SRELC (1 << 20)
+
+ /* This symbol was created by bfd_get_synthetic_symtab. */
+#define BSF_SYNTHETIC (1 << 21)
+
+ /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT.
+ The dynamic linker will compute the value of this symbol by
+ calling the function that it points to. BSF_FUNCTION must
+ also be also set. */
+#define BSF_GNU_INDIRECT_FUNCTION (1 << 22)
+ /* This symbol is a globally unique data object. The dynamic linker
+ will make sure that in the entire process there is just one symbol
+ with this name and type in use. BSF_OBJECT must also be set. */
+#define BSF_GNU_UNIQUE (1 << 23)
+
+ 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 bfd_section *section;
+
+ /* Back end special data. */
+ union
+ @{
+ void *p;
+ bfd_vma i;
+ @}
+ udata;
+@}
+asymbol;
+
+@end example
+
+@node symbol handling functions, , typedef asymbol, Symbols
+@subsection Symbol handling functions
+
+
+@findex bfd_get_symtab_upper_bound
+@subsubsection @code{bfd_get_symtab_upper_bound}
+@strong{Description}@*
+Return the number of bytes required to store a vector of pointers
+to @code{asymbols} for all the symbols in the BFD @var{abfd},
+including a terminal NULL pointer. If there are no symbols in
+the BFD, then return 0. If an error occurs, return -1.
+@example
+#define bfd_get_symtab_upper_bound(abfd) \
+ BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))
+
+@end example
+
+@findex bfd_is_local_label
+@subsubsection @code{bfd_is_local_label}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym);
+@end example
+@strong{Description}@*
+Return TRUE if the given symbol @var{sym} in the BFD @var{abfd} is
+a compiler generated local label, else return FALSE.
+
+@findex bfd_is_local_label_name
+@subsubsection @code{bfd_is_local_label_name}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name);
+@end example
+@strong{Description}@*
+Return TRUE if a symbol with the name @var{name} in the BFD
+@var{abfd} is a compiler generated local label, else return
+FALSE. This just checks whether the name has the form of a
+local label.
+@example
+#define bfd_is_local_label_name(abfd, name) \
+ BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))
+
+@end example
+
+@findex bfd_is_target_special_symbol
+@subsubsection @code{bfd_is_target_special_symbol}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym);
+@end example
+@strong{Description}@*
+Return TRUE iff a symbol @var{sym} in the BFD @var{abfd} is something
+special to the particular target represented by the BFD. Such symbols
+should normally not be mentioned to the user.
+@example
+#define bfd_is_target_special_symbol(abfd, sym) \
+ BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym))
+
+@end example
+
+@findex bfd_canonicalize_symtab
+@subsubsection @code{bfd_canonicalize_symtab}
+@strong{Description}@*
+Read the symbols from the BFD @var{abfd}, and fills in
+the vector @var{location} with pointers to the symbols and
+a trailing NULL.
+Return the actual number of symbol pointers, not
+including the NULL.
+@example
+#define bfd_canonicalize_symtab(abfd, location) \
+ BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location))
+
+@end example
+
+@findex bfd_set_symtab
+@subsubsection @code{bfd_set_symtab}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_symtab
+ (bfd *abfd, asymbol **location, unsigned int count);
+@end example
+@strong{Description}@*
+Arrange that when the output BFD @var{abfd} is closed,
+the table @var{location} of @var{count} pointers to symbols
+will be written.
+
+@findex bfd_print_symbol_vandf
+@subsubsection @code{bfd_print_symbol_vandf}
+@strong{Synopsis}
+@example
+void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol);
+@end example
+@strong{Description}@*
+Print the value and flags of the @var{symbol} supplied to the
+stream @var{file}.
+
+@findex bfd_make_empty_symbol
+@subsubsection @code{bfd_make_empty_symbol}
+@strong{Description}@*
+Create a new @code{asymbol} structure for the BFD @var{abfd}
+and return a pointer to it.
+
+This routine is necessary because each back end has private
+information surrounding the @code{asymbol}. Building your own
+@code{asymbol} and pointing to it will not create the private
+information, and will cause problems later on.
+@example
+#define bfd_make_empty_symbol(abfd) \
+ BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
+
+@end example
+
+@findex _bfd_generic_make_empty_symbol
+@subsubsection @code{_bfd_generic_make_empty_symbol}
+@strong{Synopsis}
+@example
+asymbol *_bfd_generic_make_empty_symbol (bfd *);
+@end example
+@strong{Description}@*
+Create a new @code{asymbol} structure for the BFD @var{abfd}
+and return a pointer to it. Used by core file routines,
+binary back-end and anywhere else where no private info
+is needed.
+
+@findex bfd_make_debug_symbol
+@subsubsection @code{bfd_make_debug_symbol}
+@strong{Description}@*
+Create a new @code{asymbol} structure for the BFD @var{abfd},
+to be used as a debugging symbol. Further details of its use have
+yet to be worked out.
+@example
+#define bfd_make_debug_symbol(abfd,ptr,size) \
+ BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))
+
+@end example
+
+@findex bfd_decode_symclass
+@subsubsection @code{bfd_decode_symclass}
+@strong{Description}@*
+Return a character corresponding to the symbol
+class of @var{symbol}, or '?' for an unknown class.
+
+@strong{Synopsis}
+@example
+int bfd_decode_symclass (asymbol *symbol);
+@end example
+@findex bfd_is_undefined_symclass
+@subsubsection @code{bfd_is_undefined_symclass}
+@strong{Description}@*
+Returns non-zero if the class symbol returned by
+bfd_decode_symclass represents an undefined symbol.
+Returns zero otherwise.
+
+@strong{Synopsis}
+@example
+bfd_boolean bfd_is_undefined_symclass (int symclass);
+@end example
+@findex bfd_symbol_info
+@subsubsection @code{bfd_symbol_info}
+@strong{Description}@*
+Fill in the basic info about symbol that nm needs.
+Additional info may be added by the back-ends after
+calling this function.
+
+@strong{Synopsis}
+@example
+void bfd_symbol_info (asymbol *symbol, symbol_info *ret);
+@end example
+@findex bfd_copy_private_symbol_data
+@subsubsection @code{bfd_copy_private_symbol_data}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_copy_private_symbol_data
+ (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);
+@end example
+@strong{Description}@*
+Copy private symbol information from @var{isym} in the BFD
+@var{ibfd} to the symbol @var{osym} in the BFD @var{obfd}.
+Return @code{TRUE} on success, @code{FALSE} on error. Possible error
+returns are:
+
+@itemize @bullet
+
+@item
+@code{bfd_error_no_memory} -
+Not enough memory exists to create private data for @var{osec}.
+@end itemize
+@example
+#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
+ BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
+ (ibfd, isymbol, obfd, osymbol))
+
+@end example
+
diff --git a/bfd/doc/targets.texi b/bfd/doc/targets.texi
new file mode 100644
index 00000000000..542de046589
--- /dev/null
+++ b/bfd/doc/targets.texi
@@ -0,0 +1,563 @@
+@section Targets
+
+
+@strong{Description}@*
+Each port of BFD to a different machine requires 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 @code{bfd_openr}, its format and
+target are unknown. BFD uses various mechanisms to determine
+how to interpret the file. The operations performed are:
+
+@itemize @bullet
+
+@item
+Create a BFD by calling the internal routine
+@code{_bfd_new_bfd}, then call @code{bfd_find_target} with the
+target string supplied to @code{bfd_openr} and the new BFD pointer.
+
+@item
+If a null target string was provided to @code{bfd_find_target},
+look up the environment variable @code{GNUTARGET} and use
+that as the target string.
+
+@item
+If the target string is still @code{NULL}, or the target string is
+@code{default}, then use the first item in the target vector
+as the target type, and set @code{target_defaulted} in the BFD to
+cause @code{bfd_check_format} to loop through all the targets.
+@xref{bfd_target}. @xref{Formats}.
+
+@item
+Otherwise, inspect the elements in the target vector
+one by one, until a match on target name is found. When found,
+use it.
+
+@item
+Otherwise return the error @code{bfd_error_invalid_target} to
+@code{bfd_openr}.
+
+@item
+@code{bfd_openr} attempts to open the file using
+@code{bfd_open_file}, and returns the BFD.
+@end itemize
+Once the BFD has been opened and the target selected, the file
+format may be determined. This is done by calling
+@code{bfd_check_format} on the BFD with a suggested format.
+If @code{target_defaulted} has been set, each possible target
+type is tried to see if it recognizes the specified format.
+@code{bfd_check_format} returns @code{TRUE} when the caller guesses right.
+@menu
+* bfd_target::
+@end menu
+
+@node bfd_target, , Targets, Targets
+
+@subsection bfd_target
+
+
+@strong{Description}@*
+This structure contains everything that BFD knows about a
+target. It includes things like its byte order, name, and which
+routines to call to do various operations.
+
+Every BFD points to a target structure with its @code{xvec}
+member.
+
+The macros below are used to dispatch to functions through the
+@code{bfd_target} vector. They are used in a number of macros further
+down in @file{bfd.h}, and are also used when calling various
+routines by hand inside the BFD implementation. The @var{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.
+@example
+#define BFD_SEND(bfd, message, arglist) \
+ ((*((bfd)->xvec->message)) arglist)
+
+#ifdef DEBUG_BFD_SEND
+#undef BFD_SEND
+#define BFD_SEND(bfd, message, arglist) \
+ (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
+ ((*((bfd)->xvec->message)) arglist) : \
+ (bfd_assert (__FILE__,__LINE__), NULL))
+#endif
+@end example
+For operations which index on the BFD format:
+@example
+#define BFD_SEND_FMT(bfd, message, arglist) \
+ (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist)
+
+#ifdef DEBUG_BFD_SEND
+#undef BFD_SEND_FMT
+#define BFD_SEND_FMT(bfd, message, arglist) \
+ (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
+ (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \
+ (bfd_assert (__FILE__,__LINE__), NULL))
+#endif
+
+@end example
+This is the structure which defines the type of BFD this is. The
+@code{xvec} member of the struct @code{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!
+@example
+enum bfd_flavour
+@{
+ bfd_target_unknown_flavour,
+ bfd_target_aout_flavour,
+ bfd_target_coff_flavour,
+ bfd_target_ecoff_flavour,
+ bfd_target_xcoff_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_verilog_flavour,
+ bfd_target_ihex_flavour,
+ bfd_target_som_flavour,
+ bfd_target_os9k_flavour,
+ bfd_target_versados_flavour,
+ bfd_target_msdos_flavour,
+ bfd_target_ovax_flavour,
+ bfd_target_evax_flavour,
+ bfd_target_mmo_flavour,
+ bfd_target_mach_o_flavour,
+ bfd_target_pef_flavour,
+ bfd_target_pef_xlib_flavour,
+ bfd_target_sym_flavour
+@};
+
+enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
+
+/* Forward declaration. */
+typedef struct bfd_link_info _bfd_link_info;
+
+typedef struct bfd_target
+@{
+ /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */
+ char *name;
+
+ /* The "flavour" of a back end is a general indication about
+ the contents of a file. */
+ enum bfd_flavour flavour;
+
+ /* The order of bytes within the data area of a file. */
+ enum bfd_endian byteorder;
+
+ /* The order of bytes within the header parts of a file. */
+ enum bfd_endian header_byteorder;
+
+ /* A mask of all the flags which an executable may have set -
+ from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}. */
+ flagword object_flags;
+
+ /* A mask of all the flags which a section may have set - from
+ the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{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 file names within an archive header. */
+ char ar_pad_char;
+
+ /* The maximum number of characters in an archive header. */
+ unsigned short ar_max_namelen;
+
+ /* Entries for byte swapping for data. These are different from the
+ other entry points, since they don't take a BFD as the first argument.
+ Certain other handlers could do the same. */
+ bfd_uint64_t (*bfd_getx64) (const void *);
+ bfd_int64_t (*bfd_getx_signed_64) (const void *);
+ void (*bfd_putx64) (bfd_uint64_t, void *);
+ bfd_vma (*bfd_getx32) (const void *);
+ bfd_signed_vma (*bfd_getx_signed_32) (const void *);
+ void (*bfd_putx32) (bfd_vma, void *);
+ bfd_vma (*bfd_getx16) (const void *);
+ bfd_signed_vma (*bfd_getx_signed_16) (const void *);
+ void (*bfd_putx16) (bfd_vma, void *);
+
+ /* Byte swapping for the headers. */
+ bfd_uint64_t (*bfd_h_getx64) (const void *);
+ bfd_int64_t (*bfd_h_getx_signed_64) (const void *);
+ void (*bfd_h_putx64) (bfd_uint64_t, void *);
+ bfd_vma (*bfd_h_getx32) (const void *);
+ bfd_signed_vma (*bfd_h_getx_signed_32) (const void *);
+ void (*bfd_h_putx32) (bfd_vma, void *);
+ bfd_vma (*bfd_h_getx16) (const void *);
+ bfd_signed_vma (*bfd_h_getx_signed_16) (const void *);
+ void (*bfd_h_putx16) (bfd_vma, void *);
+
+ /* 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 a @code{bfd_target *} or zero. */
+ const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *);
+
+ /* Set the format of a file being written. */
+ bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *);
+
+ /* Write cached information into a file being written, at @code{bfd_close}. */
+ bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *);
+
+@end example
+The general target vector. These vectors are initialized using the
+BFD_JUMP_TABLE macros.
+@example
+
+ /* Generic entry points. */
+#define BFD_JUMP_TABLE_GENERIC(NAME) \
+ NAME##_close_and_cleanup, \
+ NAME##_bfd_free_cached_info, \
+ NAME##_new_section_hook, \
+ NAME##_get_section_contents, \
+ NAME##_get_section_contents_in_window
+
+ /* Called when the BFD is being closed to do any necessary cleanup. */
+ bfd_boolean (*_close_and_cleanup) (bfd *);
+ /* Ask the BFD to free all cached information. */
+ bfd_boolean (*_bfd_free_cached_info) (bfd *);
+ /* Called when a new section is created. */
+ bfd_boolean (*_new_section_hook) (bfd *, sec_ptr);
+ /* Read the contents of a section. */
+ bfd_boolean (*_bfd_get_section_contents)
+ (bfd *, sec_ptr, void *, file_ptr, bfd_size_type);
+ bfd_boolean (*_bfd_get_section_contents_in_window)
+ (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type);
+
+ /* Entry points to copy private data. */
+#define BFD_JUMP_TABLE_COPY(NAME) \
+ NAME##_bfd_copy_private_bfd_data, \
+ NAME##_bfd_merge_private_bfd_data, \
+ _bfd_generic_init_private_section_data, \
+ NAME##_bfd_copy_private_section_data, \
+ NAME##_bfd_copy_private_symbol_data, \
+ NAME##_bfd_copy_private_header_data, \
+ NAME##_bfd_set_private_flags, \
+ NAME##_bfd_print_private_bfd_data
+
+ /* Called to copy BFD general private data from one object file
+ to another. */
+ bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
+ /* Called to merge BFD general private data from one object file
+ to a common output file when linking. */
+ bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
+ /* Called to initialize BFD private section data from one object file
+ to another. */
+#define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \
+ BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info))
+ bfd_boolean (*_bfd_init_private_section_data)
+ (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *);
+ /* Called to copy BFD private section data from one object file
+ to another. */
+ bfd_boolean (*_bfd_copy_private_section_data)
+ (bfd *, sec_ptr, bfd *, sec_ptr);
+ /* Called to copy BFD private symbol data from one symbol
+ to another. */
+ bfd_boolean (*_bfd_copy_private_symbol_data)
+ (bfd *, asymbol *, bfd *, asymbol *);
+ /* Called to copy BFD private header data from one object file
+ to another. */
+ bfd_boolean (*_bfd_copy_private_header_data)
+ (bfd *, bfd *);
+ /* Called to set private backend flags. */
+ bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
+
+ /* Called to print private BFD data. */
+ bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
+
+ /* Core file entry points. */
+#define BFD_JUMP_TABLE_CORE(NAME) \
+ NAME##_core_file_failing_command, \
+ NAME##_core_file_failing_signal, \
+ NAME##_core_file_matches_executable_p
+
+ char * (*_core_file_failing_command) (bfd *);
+ int (*_core_file_failing_signal) (bfd *);
+ bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
+
+ /* Archive entry points. */
+#define BFD_JUMP_TABLE_ARCHIVE(NAME) \
+ NAME##_slurp_armap, \
+ NAME##_slurp_extended_name_table, \
+ NAME##_construct_extended_name_table, \
+ NAME##_truncate_arname, \
+ NAME##_write_armap, \
+ NAME##_read_ar_hdr, \
+ NAME##_openr_next_archived_file, \
+ NAME##_get_elt_at_index, \
+ NAME##_generic_stat_arch_elt, \
+ NAME##_update_armap_timestamp
+
+ bfd_boolean (*_bfd_slurp_armap) (bfd *);
+ bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
+ bfd_boolean (*_bfd_construct_extended_name_table)
+ (bfd *, char **, bfd_size_type *, const char **);
+ void (*_bfd_truncate_arname) (bfd *, const char *, char *);
+ bfd_boolean (*write_armap)
+ (bfd *, unsigned int, struct orl *, unsigned int, int);
+ void * (*_bfd_read_ar_hdr_fn) (bfd *);
+ bfd * (*openr_next_archived_file) (bfd *, bfd *);
+#define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
+ bfd * (*_bfd_get_elt_at_index) (bfd *, symindex);
+ int (*_bfd_stat_arch_elt) (bfd *, struct stat *);
+ bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
+
+ /* Entry points used for symbols. */
+#define BFD_JUMP_TABLE_SYMBOLS(NAME) \
+ NAME##_get_symtab_upper_bound, \
+ NAME##_canonicalize_symtab, \
+ NAME##_make_empty_symbol, \
+ NAME##_print_symbol, \
+ NAME##_get_symbol_info, \
+ NAME##_bfd_is_local_label_name, \
+ NAME##_bfd_is_target_special_symbol, \
+ NAME##_get_lineno, \
+ NAME##_find_nearest_line, \
+ _bfd_generic_find_line, \
+ NAME##_find_inliner_info, \
+ NAME##_bfd_make_debug_symbol, \
+ NAME##_read_minisymbols, \
+ NAME##_minisymbol_to_symbol
+
+ long (*_bfd_get_symtab_upper_bound) (bfd *);
+ long (*_bfd_canonicalize_symtab)
+ (bfd *, struct bfd_symbol **);
+ struct bfd_symbol *
+ (*_bfd_make_empty_symbol) (bfd *);
+ void (*_bfd_print_symbol)
+ (bfd *, void *, struct bfd_symbol *, 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)
+ (bfd *, struct bfd_symbol *, symbol_info *);
+#define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
+ bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
+ bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *);
+ alent * (*_get_lineno) (bfd *, struct bfd_symbol *);
+ bfd_boolean (*_bfd_find_nearest_line)
+ (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
+ const char **, const char **, unsigned int *);
+ bfd_boolean (*_bfd_find_line)
+ (bfd *, struct bfd_symbol **, struct bfd_symbol *,
+ const char **, unsigned int *);
+ bfd_boolean (*_bfd_find_inliner_info)
+ (bfd *, const char **, const char **, unsigned int *);
+ /* 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)
+ (bfd *, void *, unsigned long size);
+#define bfd_read_minisymbols(b, d, m, s) \
+ BFD_SEND (b, _read_minisymbols, (b, d, m, s))
+ long (*_read_minisymbols)
+ (bfd *, bfd_boolean, void **, unsigned int *);
+#define bfd_minisymbol_to_symbol(b, d, m, f) \
+ BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
+ asymbol * (*_minisymbol_to_symbol)
+ (bfd *, bfd_boolean, const void *, asymbol *);
+
+ /* Routines for relocs. */
+#define BFD_JUMP_TABLE_RELOCS(NAME) \
+ NAME##_get_reloc_upper_bound, \
+ NAME##_canonicalize_reloc, \
+ NAME##_bfd_reloc_type_lookup, \
+ NAME##_bfd_reloc_name_lookup
+
+ long (*_get_reloc_upper_bound) (bfd *, sec_ptr);
+ long (*_bfd_canonicalize_reloc)
+ (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
+ /* See documentation on reloc types. */
+ reloc_howto_type *
+ (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
+ reloc_howto_type *
+ (*reloc_name_lookup) (bfd *, const char *);
+
+
+ /* Routines used when writing an object file. */
+#define BFD_JUMP_TABLE_WRITE(NAME) \
+ NAME##_set_arch_mach, \
+ NAME##_set_section_contents
+
+ bfd_boolean (*_bfd_set_arch_mach)
+ (bfd *, enum bfd_architecture, unsigned long);
+ bfd_boolean (*_bfd_set_section_contents)
+ (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
+
+ /* Routines used by the linker. */
+#define BFD_JUMP_TABLE_LINK(NAME) \
+ NAME##_sizeof_headers, \
+ NAME##_bfd_get_relocated_section_contents, \
+ NAME##_bfd_relax_section, \
+ NAME##_bfd_link_hash_table_create, \
+ NAME##_bfd_link_hash_table_free, \
+ NAME##_bfd_link_add_symbols, \
+ NAME##_bfd_link_just_syms, \
+ NAME##_bfd_final_link, \
+ NAME##_bfd_link_split_section, \
+ NAME##_bfd_gc_sections, \
+ NAME##_bfd_merge_sections, \
+ NAME##_bfd_is_group_section, \
+ NAME##_bfd_discard_group, \
+ NAME##_section_already_linked, \
+ NAME##_bfd_define_common_symbol
+
+ int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *);
+ bfd_byte * (*_bfd_get_relocated_section_contents)
+ (bfd *, struct bfd_link_info *, struct bfd_link_order *,
+ bfd_byte *, bfd_boolean, struct bfd_symbol **);
+
+ bfd_boolean (*_bfd_relax_section)
+ (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
+
+ /* Create a hash table for the linker. Different backends store
+ different information in this table. */
+ struct bfd_link_hash_table *
+ (*_bfd_link_hash_table_create) (bfd *);
+
+ /* Release the memory associated with the linker hash table. */
+ void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
+
+ /* Add symbols from this object file into the hash table. */
+ bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
+
+ /* Indicate that we are only retrieving symbol values from this section. */
+ void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
+
+ /* Do a link based on the link_order structures attached to each
+ section of the BFD. */
+ bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
+
+ /* Should this section be split up into smaller pieces during linking. */
+ bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
+
+ /* Remove sections that are not referenced from the output. */
+ bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
+
+ /* Attempt to merge SEC_MERGE sections. */
+ bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
+
+ /* Is this section a member of a group? */
+ bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *);
+
+ /* Discard members of a group. */
+ bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
+
+ /* Check if SEC has been already linked during a reloceatable or
+ final link. */
+ void (*_section_already_linked) (bfd *, struct bfd_section *,
+ struct bfd_link_info *);
+
+ /* Define a common symbol. */
+ bfd_boolean (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *,
+ struct bfd_link_hash_entry *);
+
+ /* Routines to handle dynamic symbols and relocs. */
+#define BFD_JUMP_TABLE_DYNAMIC(NAME) \
+ NAME##_get_dynamic_symtab_upper_bound, \
+ NAME##_canonicalize_dynamic_symtab, \
+ NAME##_get_synthetic_symtab, \
+ NAME##_get_dynamic_reloc_upper_bound, \
+ NAME##_canonicalize_dynamic_reloc
+
+ /* Get the amount of memory required to hold the dynamic symbols. */
+ long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
+ /* Read in the dynamic symbols. */
+ long (*_bfd_canonicalize_dynamic_symtab)
+ (bfd *, struct bfd_symbol **);
+ /* Create synthetized symbols. */
+ long (*_bfd_get_synthetic_symtab)
+ (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **,
+ struct bfd_symbol **);
+ /* Get the amount of memory required to hold the dynamic relocs. */
+ long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
+ /* Read in the dynamic relocs. */
+ long (*_bfd_canonicalize_dynamic_reloc)
+ (bfd *, arelent **, struct bfd_symbol **);
+
+@end example
+A pointer to an alternative bfd_target in case the current one is not
+satisfactory. This can happen when the target cpu supports both big
+and little endian code, and target chosen by the linker has the wrong
+endianness. The function open_output() in ld/ldlang.c uses this field
+to find an alternative output format that is suitable.
+@example
+ /* Opposite endian version of this target. */
+ const struct bfd_target * alternative_target;
+
+ /* Data for use by back-end routines, which isn't
+ generic enough to belong in this structure. */
+ const void *backend_data;
+
+@} bfd_target;
+
+@end example
+
+@findex bfd_set_default_target
+@subsubsection @code{bfd_set_default_target}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_set_default_target (const char *name);
+@end example
+@strong{Description}@*
+Set the default target vector to use when recognizing a BFD.
+This takes the name of the target, which may be a BFD target
+name or a configuration triplet.
+
+@findex bfd_find_target
+@subsubsection @code{bfd_find_target}
+@strong{Synopsis}
+@example
+const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
+@end example
+@strong{Description}@*
+Return a pointer to the transfer vector for the object target
+named @var{target_name}. If @var{target_name} is @code{NULL},
+choose the one in the environment variable @code{GNUTARGET}; if
+that is null or not defined, then choose the first entry in the
+target list. 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 if @var{abfd} isn't @code{NULL}. This causes
+@code{bfd_check_format} to loop over all the targets to find the
+one that matches the file being read.
+
+@findex bfd_target_list
+@subsubsection @code{bfd_target_list}
+@strong{Synopsis}
+@example
+const char ** bfd_target_list (void);
+@end example
+@strong{Description}@*
+Return a freshly malloced NULL-terminated
+vector of the names of all the valid BFD targets. Do not
+modify the names.
+
+@findex bfd_seach_for_target
+@subsubsection @code{bfd_seach_for_target}
+@strong{Synopsis}
+@example
+const bfd_target *bfd_search_for_target
+ (int (*search_func) (const bfd_target *, void *),
+ void *);
+@end example
+@strong{Description}@*
+Return a pointer to the first transfer vector in the list of
+transfer vectors maintained by BFD that produces a non-zero
+result when passed to the function @var{search_func}. The
+parameter @var{data} is passed, unexamined, to the search
+function.
+
diff --git a/etc/configure.info b/etc/configure.info
new file mode 100644
index 00000000000..cee206aa6a8
--- /dev/null
+++ b/etc/configure.info
@@ -0,0 +1,2773 @@
+This is configure.info, produced by makeinfo version 4.8 from
+./configure.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* configure: (configure). The GNU configure and build system
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU configure and build system.
+
+ Copyright (C) 1998 Cygnus Solutions.
+
+ 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, provided 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, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: configure.info, Node: Top, Next: Introduction, Up: (dir)
+
+GNU configure and build system
+******************************
+
+The GNU configure and build system.
+
+* Menu:
+
+* Introduction:: Introduction.
+* Getting Started:: Getting Started.
+* Files:: Files.
+* Configuration Names:: Configuration Names.
+* Cross Compilation Tools:: Cross Compilation Tools.
+* Canadian Cross:: Canadian Cross.
+* Cygnus Configure:: Cygnus Configure.
+* Multilibs:: Multilibs.
+* FAQ:: Frequently Asked Questions.
+* Index:: Index.
+
+
+File: configure.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+This document describes the GNU configure and build systems. It
+describes how autoconf, automake, libtool, and make fit together. It
+also includes a discussion of the older Cygnus configure system.
+
+ This document does not describe in detail how to use each of the
+tools; see the respective manuals for that. Instead, it describes
+which files the developer must write, which files are machine generated
+and how they are generated, and where certain common problems should be
+addressed.
+
+ This document draws on several sources, including the autoconf
+manual by David MacKenzie (*note autoconf overview: (autoconf)Top.),
+the automake manual by David MacKenzie and Tom Tromey (*note automake
+overview: (automake)Top.), the libtool manual by Gordon Matzigkeit
+(*note libtool overview: (libtool)Top.), and the Cygnus configure
+manual by K. Richard Pixley.
+
+* Menu:
+
+* Goals:: Goals.
+* Tools:: The tools.
+* History:: History.
+* Building:: Building.
+
+
+File: configure.info, Node: Goals, Next: Tools, Up: Introduction
+
+1.1 Goals
+=========
+
+The GNU configure and build system has two main goals.
+
+ The first is to simplify the development of portable programs. The
+system permits the developer to concentrate on writing the program,
+simplifying many details of portability across Unix and even Windows
+systems, and permitting the developer to describe how to build the
+program using simple rules rather than complex Makefiles.
+
+ The second is to simplify the building of programs distributed as
+source code. All programs are built using a simple, standardized, two
+step process. The program builder need not install any special tools in
+order to build the program.
+
+
+File: configure.info, Node: Tools, Next: History, Prev: Goals, Up: Introduction
+
+1.2 Tools
+=========
+
+The GNU configure and build system is comprised of several different
+tools. Program developers must build and install all of these tools.
+
+ People who just want to build programs from distributed sources
+normally do not need any special tools beyond a Unix shell, a make
+program, and a C compiler.
+
+autoconf
+ provides a general portability framework, based on testing the
+ features of the host system at build time.
+
+automake
+ a system for describing how to build a program, permitting the
+ developer to write a simplified `Makefile'.
+
+libtool
+ a standardized approach to building shared libraries.
+
+gettext
+ provides a framework for translation of text messages into other
+ languages; not really discussed in this document.
+
+m4
+ autoconf requires the GNU version of m4; the standard Unix m4 does
+ not suffice.
+
+perl
+ automake requires perl.
+
+
+File: configure.info, Node: History, Next: Building, Prev: Tools, Up: Introduction
+
+1.3 History
+===========
+
+This is a very brief and probably inaccurate history.
+
+ As the number of Unix variants increased during the 1980s, it became
+harder to write programs which could run on all variants. While it was
+often possible to use `#ifdef' to identify particular systems,
+developers frequently did not have access to every system, and the
+characteristics of some systems changed from version to version.
+
+ By 1992, at least three different approaches had been developed:
+ * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
+ Manfredi.
+
+ * The Cygnus configure script, by K. Richard Pixley, and the gcc
+ configure script, by Richard Stallman. These use essentially the
+ same approach, and the developers communicated regularly.
+
+ * The autoconf program, by David MacKenzie.
+
+ The Metaconfig program is still used for Perl and a few other
+programs. It is part of the Dist package. I do not know if it is
+being developed.
+
+ In 1994, David MacKenzie and others modified autoconf to incorporate
+all the features of Cygnus configure. Since then, there has been a
+slow but steady conversion of GNU programs from Cygnus configure to
+autoconf. gcc has been converted, eliminating the gcc configure script.
+
+ GNU autoconf was regularly maintained until late 1996. As of this
+writing in June, 1998, it has no public maintainer.
+
+ Most programs are built using the make program, which requires the
+developer to write Makefiles describing how to build the programs.
+Since most programs are built in pretty much the same way, this led to a
+lot of duplication.
+
+ The X Window system is built using the imake tool, which uses a
+database of rules to eliminate the duplication. However, building a
+tool which was developed using imake requires that the builder have
+imake installed, violating one of the goals of the GNU system.
+
+ The new BSD make provides a standard library of Makefile fragments,
+which permits developers to write very simple Makefiles. However, this
+requires that the builder install the new BSD make program.
+
+ In 1994, David MacKenzie wrote the first version of automake, which
+permitted writing a simple build description which was converted into a
+Makefile which could be used by the standard make program. In 1995, Tom
+Tromey completely rewrote automake in Perl, and he continues to enhance
+it.
+
+ Various free packages built libraries, and by around 1995 several
+included support to build shared libraries on various platforms.
+However, there was no consistent approach. In early 1996, Gordon
+Matzigkeit began working on libtool, which provided a standardized
+approach to building shared libraries. This was integrated into
+automake from the start.
+
+ The development of automake and libtool was driven by the GNITS
+project, a group of GNU maintainers who designed standardized tools to
+help meet the GNU coding standards.
+
+
+File: configure.info, Node: Building, Prev: History, Up: Introduction
+
+1.4 Building
+============
+
+Most readers of this document should already know how to build a tool by
+running `configure' and `make'. This section may serve as a quick
+introduction or reminder.
+
+ Building a tool is normally as simple as running `configure'
+followed by `make'. You should normally run `configure' from an empty
+directory, using some path to refer to the `configure' script in the
+source directory. The directory in which you run `configure' is called
+the "object directory".
+
+ In order to use a object directory which is different from the source
+directory, you must be using the GNU version of `make', which has the
+required `VPATH' support. Despite this restriction, using a different
+object directory is highly recommended:
+ * It keeps the files generated during the build from cluttering up
+ your sources.
+
+ * It permits you to remove the built files by simply removing the
+ entire build directory.
+
+ * It permits you to build from the same sources with several sets of
+ configure options simultaneously.
+
+ If you don't have GNU `make', you will have to run `configure' in
+the source directory. All GNU packages should support this; in
+particular, GNU packages should not assume the presence of GNU `make'.
+
+ After running `configure', you can build the tools by running `make'.
+
+ To install the tools, run `make install'. Installing the tools will
+copy the programs and any required support files to the "installation
+directory". The location of the installation directory is controlled
+by `configure' options, as described below.
+
+ In the Cygnus tree at present, the info files are built and
+installed as a separate step. To build them, run `make info'. To
+install them, run `make install-info'. The equivalent html files are
+also built and installed in a separate step. To build the html files,
+run `make html'. To install the html files run `make install-html'.
+
+ All `configure' scripts support a wide variety of options. The most
+interesting ones are `--with' and `--enable' options which are
+generally specific to particular tools. You can usually use the
+`--help' option to get a list of interesting options for a particular
+configure script.
+
+ The only generic options you are likely to use are the `--prefix'
+and `--exec-prefix' options. These options are used to specify the
+installation directory.
+
+ The directory named by the `--prefix' option will hold machine
+independent files such as info files.
+
+ The directory named by the `--exec-prefix' option, which is normally
+a subdirectory of the `--prefix' directory, will hold machine dependent
+files such as executables.
+
+ The default for `--prefix' is `/usr/local'. The default for
+`--exec-prefix' is the value used for `--prefix'.
+
+ The convention used in Cygnus releases is to use a `--prefix' option
+of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and
+to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where
+HOST is the configuration name of the host system (*note Configuration
+Names::).
+
+ Do not use either the source or the object directory as the
+installation directory. That will just lead to confusion.
+
+
+File: configure.info, Node: Getting Started, Next: Files, Prev: Introduction, Up: Top
+
+2 Getting Started
+*****************
+
+To start using the GNU configure and build system with your software
+package, you must write three files, and you must run some tools to
+manually generate additional files.
+
+* Menu:
+
+* Write configure.in:: Write configure.in.
+* Write Makefile.am:: Write Makefile.am.
+* Write acconfig.h:: Write acconfig.h.
+* Generate files:: Generate files.
+* Getting Started Example:: Example.
+
+
+File: configure.info, Node: Write configure.in, Next: Write Makefile.am, Up: Getting Started
+
+2.1 Write configure.in
+======================
+
+You must first write the file `configure.in'. This is an autoconf
+input file, and the autoconf manual describes in detail what this file
+should look like.
+
+ You will write tests in your `configure.in' file to check for
+conditions that may change from one system to another, such as the
+presence of particular header files or functions.
+
+ For example, not all systems support the `gettimeofday' function.
+If you want to use the `gettimeofday' function when it is available,
+and to use some other function when it is not, you would check for this
+by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'.
+
+ When the configure script is run at build time, this will arrange to
+define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the
+`gettimeofday' function is available, and to not define the macro at
+all if the function is not available. Your code can then use `#ifdef'
+to test whether it is safe to call `gettimeofday'.
+
+ If you have an existing body of code, the `autoscan' program may
+help identify potential portability problems, and hence configure tests
+that you will want to use. *Note Invoking autoscan: (autoconf)Invoking
+autoscan.
+
+ Another handy tool for an existing body of code is `ifnames'. This
+will show you all the preprocessor conditionals that the code already
+uses. *Note Invoking ifnames: (autoconf)Invoking ifnames.
+
+ Besides the portability tests which are specific to your particular
+package, every `configure.in' file should contain the following macros.
+
+`AC_INIT'
+ This macro takes a single argument, which is the name of a file in
+ your package. For example, `AC_INIT(foo.c)'.
+
+`AC_PREREQ(VERSION)'
+ This macro is optional. It may be used to indicate the version of
+ `autoconf' that you are using. This will prevent users from
+ running an earlier version of `autoconf' and perhaps getting an
+ invalid `configure' script. For example, `AC_PREREQ(2.12)'.
+
+`AM_INIT_AUTOMAKE'
+ This macro takes two arguments: the name of the package, and a
+ version number. For example, `AM_INIT_AUTOMAKE(foo, 1.0)'. (This
+ macro is not needed if you are not using automake).
+
+`AM_CONFIG_HEADER'
+ This macro names the header file which will hold the preprocessor
+ macro definitions at run time. Normally this should be
+ `config.h'. Your sources would then use `#include "config.h"' to
+ include it.
+
+ This macro may optionally name the input file for that header
+ file; by default, this is `config.h.in', but that file name works
+ poorly on DOS filesystems. Therefore, it is often better to name
+ it explicitly as `config.in'.
+
+ This is what you should normally put in `configure.in':
+ AM_CONFIG_HEADER(config.h:config.in)
+
+ (If you are not using automake, use `AC_CONFIG_HEADER' rather than
+ `AM_CONFIG_HEADER').
+
+`AM_MAINTAINER_MODE'
+ This macro always appears in Cygnus configure scripts. Other
+ programs may or may not use it.
+
+ If this macro is used, the `--enable-maintainer-mode' option is
+ required to enable automatic rebuilding of generated files used by
+ the configure system. This of course requires that developers be
+ aware of, and use, that option.
+
+ If this macro is not used, then the generated files will always be
+ rebuilt automatically. This will cause problems if the wrong
+ versions of autoconf, automake, or others are in the builder's
+ `PATH'.
+
+ (If you are not using automake, you do not need to use this macro).
+
+`AC_EXEEXT'
+ Either this macro or `AM_EXEEXT' always appears in Cygnus configure
+ files. Other programs may or may not use one of them.
+
+ This macro looks for the executable suffix used on the host
+ system. On Unix systems, this is the empty string. On Windows
+ systems, this is `.exe'. This macro directs automake to use the
+ executable suffix as appropriate when creating programs. This
+ macro does not take any arguments.
+
+ The `AC_EXEEXT' form is new, and is part of a Cygnus patch to
+ autoconf to support compiling with Visual C++. Older programs use
+ `AM_EXEEXT' instead.
+
+ (Programs which do not use automake use neither `AC_EXEEXT' nor
+ `AM_EXEEXT').
+
+`AC_PROG_CC'
+ If you are writing C code, you will normally want to use this
+ macro. It locates the C compiler to use. It does not take any
+ arguments.
+
+ However, if this `configure.in' file is for a library which is to
+ be compiled by a cross compiler which may not fully work, then you
+ will not want to use `AC_PROG_CC'. Instead, you will want to use a
+ variant which does not call the macro `AC_PROG_CC_WORKS'. Examples
+ can be found in various `configure.in' files for libraries that are
+ compiled with cross compilers, such as libiberty or libgloss.
+ This is essentially a bug in autoconf, and there will probably be
+ a better workaround at some point.
+
+`AC_PROG_CXX'
+ If you are writing C++ code, you will want to use this macro. It
+ locates the C++ compiler to use. It does not take any arguments.
+ The same cross compiler comments apply as for `AC_PROG_CC'.
+
+`AM_PROG_LIBTOOL'
+ If you want to build libraries, and you want to permit them to be
+ shared, or you want to link against libraries which were built
+ using libtool, then you will need this macro. This macro is
+ required in order to use libtool.
+
+ By default, this will cause all libraries to be built as shared
+ libraries. To prevent this-to change the default-use
+ `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'. The configure
+ options `--enable-shared' and `--disable-shared' may be used to
+ override the default at build time.
+
+`AC_DEFINE(_GNU_SOURCE)'
+ GNU packages should normally include this line before any other
+ feature tests. This defines the macro `_GNU_SOURCE' when
+ compiling, which directs the libc header files to provide the
+ standard GNU system interfaces including all GNU extensions. If
+ this macro is not defined, certain GNU extensions may not be
+ available.
+
+`AC_OUTPUT'
+ This macro takes a list of file names which the configure process
+ should produce. This is normally a list of one or more `Makefile'
+ files in different directories. If your package lives entirely in
+ a single directory, you would use simply `AC_OUTPUT(Makefile)'.
+ If you also have, for example, a `lib' subdirectory, you would use
+ `AC_OUTPUT(Makefile lib/Makefile)'.
+
+ If you want to use locally defined macros in your `configure.in'
+file, then you will need to write a `acinclude.m4' file which defines
+them (if not using automake, this file is called `aclocal.m4').
+Alternatively, you can put separate macros in an `m4' subdirectory, and
+put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the
+`aclocal' program will be able to find them.
+
+ The different macro prefixes indicate which tool defines the macro.
+Macros which start with `AC_' are part of autoconf. Macros which start
+with `AM_' are provided by automake or libtool.
+
+
+File: configure.info, Node: Write Makefile.am, Next: Write acconfig.h, Prev: Write configure.in, Up: Getting Started
+
+2.2 Write Makefile.am
+=====================
+
+You must write the file `Makefile.am'. This is an automake input file,
+and the automake manual describes in detail what this file should look
+like.
+
+ The automake commands in `Makefile.am' mostly look like variable
+assignments in a `Makefile'. automake recognizes special variable
+names, and automatically add make rules to the output as needed.
+
+ There will be one `Makefile.am' file for each directory in your
+package. For each directory with subdirectories, the `Makefile.am'
+file should contain the line
+ SUBDIRS = DIR DIR ...
+ where each DIR is the name of a subdirectory.
+
+ For each `Makefile.am', there should be a corresponding `Makefile'
+in the `AC_OUTPUT' macro in `configure.in'.
+
+ Every `Makefile.am' written at Cygnus should contain the line
+ AUTOMAKE_OPTIONS = cygnus
+ This puts automake into Cygnus mode. See the automake manual for
+details.
+
+ You may to include the version number of `automake' that you are
+using on the `AUTOMAKE_OPTIONS' line. For example,
+ AUTOMAKE_OPTIONS = cygnus 1.3
+ This will prevent users from running an earlier version of
+`automake' and perhaps getting an invalid `Makefile.in'.
+
+ If your package builds a program, then in the directory where that
+program is built you will normally want a line like
+ bin_PROGRAMS = PROGRAM
+ where PROGRAM is the name of the program. You will then want a line
+like
+ PROGRAM_SOURCES = FILE FILE ...
+ where each FILE is the name of a source file to link into the
+program (e.g., `foo.c').
+
+ If your package builds a library, and you do not want the library to
+ever be built as a shared library, then in the directory where that
+library is built you will normally want a line like
+ lib_LIBRARIES = libNAME.a
+ where `libNAME.a' is the name of the library. You will then want a
+line like
+ libNAME_a_SOURCES = FILE FILE ...
+ where each FILE is the name of a source file to add to the library.
+
+ If your package builds a library, and you want to permit building the
+library as a shared library, then in the directory where that library is
+built you will normally want a line like
+ lib_LTLIBRARIES = libNAME.la
+ The use of `LTLIBRARIES', and the `.la' extension, indicate a
+library to be built using libtool. As usual, you will then want a line
+like
+ libNAME_la_SOURCES = FILE FILE ...
+
+ The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and
+`lib_LIBRARIES' are not arbitrary. They refer to particular
+directories, which may be set by the `--bindir' and `--libdir' options
+to `configure'. If those options are not used, the default values are
+based on the `--prefix' or `--exec-prefix' options to `configure'. It
+is possible to use other names if the program or library should be
+installed in some other directory.
+
+ The `Makefile.am' file may also contain almost anything that may
+appear in a normal `Makefile'. automake also supports many other
+special variables, as well as conditionals.
+
+ See the automake manual for more information.
+
+
+File: configure.info, Node: Write acconfig.h, Next: Generate files, Prev: Write Makefile.am, Up: Getting Started
+
+2.3 Write acconfig.h
+====================
+
+If you are generating a portability header file, (i.e., you are using
+`AM_CONFIG_HEADER' in `configure.in'), then you will have to write a
+`acconfig.h' file. It will have to contain the following lines.
+
+ /* Name of package. */
+ #undef PACKAGE
+
+ /* Version of package. */
+ #undef VERSION
+
+ This requirement is really a bug in the system, and the requirement
+may be eliminated at some later date.
+
+ The `acconfig.h' file will also similar comment and `#undef' lines
+for any unusual macros in the `configure.in' file, including any macro
+which appears in a `AC_DEFINE' macro.
+
+ In particular, if you are writing a GNU package and therefore include
+`AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will
+need lines like this in `acconfig.h':
+ /* Enable GNU extensions. */
+ #undef _GNU_SOURCE
+
+ Normally the `autoheader' program will inform you of any such
+requirements by printing an error message when it is run. However, if
+you do anything particular odd in your `configure.in' file, you will
+have to make sure that the right entries appear in `acconfig.h', since
+otherwise the results of the tests may not be available in the
+`config.h' file which your code will use.
+
+ (Thee `PACKAGE' and `VERSION' lines are not required if you are not
+using automake, and in that case you may not need a `acconfig.h' file
+at all).
+
+
+File: configure.info, Node: Generate files, Next: Getting Started Example, Prev: Write acconfig.h, Up: Getting Started
+
+2.4 Generate files
+==================
+
+Once you have written `configure.in', `Makefile.am', `acconfig.h', and
+possibly `acinclude.m4', you must use autoconf and automake programs to
+produce the first versions of the generated files. This is done by
+executing the following sequence of commands.
+
+ aclocal
+ autoconf
+ autoheader
+ automake
+
+ The `aclocal' and `automake' commands are part of the automake
+package, and the `autoconf' and `autoheader' commands are part of the
+autoconf package.
+
+ If you are using a `m4' subdirectory for your macros, you will need
+to use the `-I m4' option when you run `aclocal'.
+
+ If you are not using the Cygnus tree, use the `-a' option when
+running `automake' command in order to copy the required support files
+into your source directory.
+
+ If you are using libtool, you must build and install the libtool
+package with the same `--prefix' and `--exec-prefix' options as you
+used with the autoconf and automake packages. You must do this before
+running any of the above commands. If you are not using the Cygnus
+tree, you will need to run the `libtoolize' program to copy the libtool
+support files into your directory.
+
+ Once you have managed to run these commands without getting any
+errors, you should create a new empty directory, and run the `configure'
+script which will have been created by `autoconf' with the
+`--enable-maintainer-mode' option. This will give you a set of
+Makefiles which will include rules to automatically rebuild all the
+generated files.
+
+ After doing that, whenever you have changed some of the input files
+and want to regenerated the other files, go to your object directory
+and run `make'. Doing this is more reliable than trying to rebuild the
+files manually, because there are complex order dependencies and it is
+easy to forget something.
+
+
+File: configure.info, Node: Getting Started Example, Prev: Generate files, Up: Getting Started
+
+2.5 Example
+===========
+
+Let's consider a trivial example.
+
+ Suppose we want to write a simple version of `touch'. Our program,
+which we will call `poke', will take a single file name argument, and
+use the `utime' system call to set the modification and access times of
+the file to the current time. We want this program to be highly
+portable.
+
+ We'll first see what this looks like without using autoconf and
+automake, and then see what it looks like with them.
+
+* Menu:
+
+* Getting Started Example 1:: First Try.
+* Getting Started Example 2:: Second Try.
+* Getting Started Example 3:: Third Try.
+* Generate Files in Example:: Generate Files.
+
+
+File: configure.info, Node: Getting Started Example 1, Next: Getting Started Example 2, Up: Getting Started Example
+
+2.5.1 First Try
+---------------
+
+Here is our first try at `poke.c'. Note that we've written it without
+ANSI/ISO C prototypes, since we want it to be highly portable.
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <sys/types.h>
+ #include <utime.h>
+
+ int
+ main (argc, argv)
+ int argc;
+ char **argv;
+ {
+ if (argc != 2)
+ {
+ fprintf (stderr, "Usage: poke file\n");
+ exit (1);
+ }
+
+ if (utime (argv[1], NULL) < 0)
+ {
+ perror ("utime");
+ exit (1);
+ }
+
+ exit (0);
+ }
+
+ We also write a simple `Makefile'.
+
+ CC = gcc
+ CFLAGS = -g -O2
+
+ all: poke
+
+ poke: poke.o
+ $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
+
+ So far, so good.
+
+ Unfortunately, there are a few problems.
+
+ On older Unix systems derived from BSD 4.3, the `utime' system call
+does not accept a second argument of `NULL'. On those systems, we need
+to pass a pointer to `struct utimbuf' structure. Unfortunately, even
+older systems don't define that structure; on those systems, we need to
+pass an array of two `long' values.
+
+ The header file `stdlib.h' was invented by ANSI C, and older systems
+don't have a copy. We included it above to get a declaration of `exit'.
+
+ We can find some of these portability problems by running
+`autoscan', which will create a `configure.scan' file which we can use
+as a prototype for our `configure.in' file. I won't show the output,
+but it will notice the potential problems with `utime' and `stdlib.h'.
+
+ In our `Makefile', we don't provide any way to install the program.
+This doesn't matter much for such a simple example, but a real program
+will need an `install' target. For that matter, we will also want a
+`clean' target.
+
+
+File: configure.info, Node: Getting Started Example 2, Next: Getting Started Example 3, Prev: Getting Started Example 1, Up: Getting Started Example
+
+2.5.2 Second Try
+----------------
+
+Here is our second try at this program.
+
+ We modify `poke.c' to use preprocessor macros to control what
+features are available. (I've cheated a bit by using the same macro
+names which autoconf will use).
+
+ #include <stdio.h>
+
+ #ifdef STDC_HEADERS
+ #include <stdlib.h>
+ #endif
+
+ #include <sys/types.h>
+
+ #ifdef HAVE_UTIME_H
+ #include <utime.h>
+ #endif
+
+ #ifndef HAVE_UTIME_NULL
+
+ #include <time.h>
+
+ #ifndef HAVE_STRUCT_UTIMBUF
+
+ struct utimbuf
+ {
+ long actime;
+ long modtime;
+ };
+
+ #endif
+
+ static int
+ utime_now (file)
+ char *file;
+ {
+ struct utimbuf now;
+
+ now.actime = now.modtime = time (NULL);
+ return utime (file, &now);
+ }
+
+ #define utime(f, p) utime_now (f)
+
+ #endif /* HAVE_UTIME_NULL */
+
+ int
+ main (argc, argv)
+ int argc;
+ char **argv;
+ {
+ if (argc != 2)
+ {
+ fprintf (stderr, "Usage: poke file\n");
+ exit (1);
+ }
+
+ if (utime (argv[1], NULL) < 0)
+ {
+ perror ("utime");
+ exit (1);
+ }
+
+ exit (0);
+ }
+
+ Here is the associated `Makefile'. We've added support for the
+preprocessor flags we use. We've also added `install' and `clean'
+targets.
+
+ # Set this to your installation directory.
+ bindir = /usr/local/bin
+
+ # Uncomment this if you have the standard ANSI/ISO C header files.
+ # STDC_HDRS = -DSTDC_HEADERS
+
+ # Uncomment this if you have utime.h.
+ # UTIME_H = -DHAVE_UTIME_H
+
+ # Uncomment this if utime (FILE, NULL) works on your system.
+ # UTIME_NULL = -DHAVE_UTIME_NULL
+
+ # Uncomment this if struct utimbuf is defined in utime.h.
+ # UTIMBUF = -DHAVE_STRUCT_UTIMBUF
+
+ CC = gcc
+ CFLAGS = -g -O2
+
+ ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
+
+ all: poke
+
+ poke: poke.o
+ $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
+
+ .c.o:
+ $(CC) -c $(ALL_CFLAGS) poke.c
+
+ install: poke
+ cp poke $(bindir)/poke
+
+ clean:
+ rm poke poke.o
+
+ Some problems with this approach should be clear.
+
+ Users who want to compile poke will have to know how `utime' works
+on their systems, so that they can uncomment the `Makefile' correctly.
+
+ The installation is done using `cp', but many systems have an
+`install' program which may be used, and which supports optional
+features such as stripping debugging information out of the installed
+binary.
+
+ The use of `Makefile' variables like `CC', `CFLAGS' and `LDFLAGS'
+follows the requirements of the GNU standards. This is convenient for
+all packages, since it reduces surprises for users. However, it is
+easy to get the details wrong, and wind up with a slightly nonstandard
+distribution.
+
+
+File: configure.info, Node: Getting Started Example 3, Next: Generate Files in Example, Prev: Getting Started Example 2, Up: Getting Started Example
+
+2.5.3 Third Try
+---------------
+
+For our third try at this program, we will write a `configure.in'
+script to discover the configuration features on the host system, rather
+than requiring the user to edit the `Makefile'. We will also write a
+`Makefile.am' rather than a `Makefile'.
+
+ The only change to `poke.c' is to add a line at the start of the
+file:
+ #include "config.h"
+
+ The new `configure.in' file is as follows.
+
+ AC_INIT(poke.c)
+ AM_INIT_AUTOMAKE(poke, 1.0)
+ AM_CONFIG_HEADER(config.h:config.in)
+ AC_PROG_CC
+ AC_HEADER_STDC
+ AC_CHECK_HEADERS(utime.h)
+ AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
+ AC_FUNC_UTIME_NULL
+ AC_OUTPUT(Makefile)
+
+ The first four macros in this file, and the last one, were described
+above; see *Note Write configure.in::. If we omit these macros, then
+when we run `automake' we will get a reminder that we need them.
+
+ The other macros are standard autoconf macros.
+
+`AC_HEADER_STDC'
+ Check for standard C headers.
+
+`AC_CHECK_HEADERS'
+ Check whether a particular header file exists.
+
+`AC_EGREP_HEADER'
+ Check for a particular string in a particular header file, in this
+ case checking for `utimbuf' in `utime.h'.
+
+`AC_FUNC_UTIME_NULL'
+ Check whether `utime' accepts a NULL second argument to set the
+ file change time to the current time.
+
+ See the autoconf manual for a more complete description.
+
+ The new `Makefile.am' file is as follows. Note how simple this is
+compared to our earlier `Makefile'.
+
+ bin_PROGRAMS = poke
+
+ poke_SOURCES = poke.c
+
+ This means that we should build a single program name `poke'. It
+should be installed in the binary directory, which we called `bindir'
+earlier. The program `poke' is built from the source file `poke.c'.
+
+ We must also write a `acconfig.h' file. Besides `PACKAGE' and
+`VERSION', which must be mentioned for all packages which use automake,
+we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an
+`AC_DEFINE'.
+
+ /* Name of package. */
+ #undef PACKAGE
+
+ /* Version of package. */
+ #undef VERSION
+
+ /* Whether utime.h defines struct utimbuf. */
+ #undef HAVE_STRUCT_UTIMBUF
+
+
+File: configure.info, Node: Generate Files in Example, Prev: Getting Started Example 3, Up: Getting Started Example
+
+2.5.4 Generate Files
+--------------------
+
+We must now generate the other files, using the following commands.
+
+ aclocal
+ autoconf
+ autoheader
+ automake
+
+ When we run `autoheader', it will remind us of any macros we forgot
+to add to `acconfig.h'.
+
+ When we run `automake', it will want to add some files to our
+distribution. It will add them automatically if we use the
+`--add-missing' option.
+
+ By default, `automake' will run in GNU mode, which means that it
+will want us to create certain additional files; as of this writing, it
+will want `NEWS', `README', `AUTHORS', and `ChangeLog', all of which
+are files which should appear in a standard GNU distribution. We can
+either add those files, or run `automake' with the `--foreign' option.
+
+ Running these tools will generate the following files, all of which
+are described in the next chapter.
+
+ * `aclocal.m4'
+
+ * `configure'
+
+ * `config.in'
+
+ * `Makefile.in'
+
+ * `stamp-h.in'
+
+
+File: configure.info, Node: Files, Next: Configuration Names, Prev: Getting Started, Up: Top
+
+3 Files
+*******
+
+As was seen in the previous chapter, the GNU configure and build system
+uses a number of different files. The developer must write a few files.
+The others are generated by various tools.
+
+ The system is rather flexible, and can be used in many different
+ways. In describing the files that it uses, I will describe the common
+case, and mention some other cases that may arise.
+
+* Menu:
+
+* Developer Files:: Developer Files.
+* Build Files:: Build Files.
+* Support Files:: Support Files.
+
+
+File: configure.info, Node: Developer Files, Next: Build Files, Up: Files
+
+3.1 Developer Files
+===================
+
+This section describes the files written or generated by the developer
+of a package.
+
+* Menu:
+
+* Developer Files Picture:: Developer Files Picture.
+* Written Developer Files:: Written Developer Files.
+* Generated Developer Files:: Generated Developer Files.
+
+
+File: configure.info, Node: Developer Files Picture, Next: Written Developer Files, Up: Developer Files
+
+3.1.1 Developer Files Picture
+-----------------------------
+
+Here is a picture of the files which are written by the developer, the
+generated files which would be included with a complete source
+distribution, and the tools which create those files. The file names
+are plain text and the tool names are enclosed by `*' characters (e.g.,
+`autoheader' is the name of a tool, not the name of a file).
+
+ acconfig.h configure.in Makefile.am
+ | | |
+ | --------------+---------------------- |
+ | | | | |
+ v v | acinclude.m4 | |
+ *autoheader* | | v v
+ | | v --->*automake*
+ v |--->*aclocal* | |
+ config.in | | | v
+ | v | Makefile.in
+ | aclocal.m4---
+ | |
+ v v
+ *autoconf*
+ |
+ v
+ configure
+
+
+File: configure.info, Node: Written Developer Files, Next: Generated Developer Files, Prev: Developer Files Picture, Up: Developer Files
+
+3.1.2 Written Developer Files
+-----------------------------
+
+The following files would be written by the developer.
+
+`configure.in'
+ This is the configuration script. This script contains
+ invocations of autoconf macros. It may also contain ordinary
+ shell script code. This file will contain feature tests for
+ portability issues. The last thing in the file will normally be
+ an `AC_OUTPUT' macro listing which files to create when the
+ builder runs the configure script. This file is always required
+ when using the GNU configure system. *Note Write configure.in::.
+
+`Makefile.am'
+ This is the automake input file. It describes how the code should
+ be built. It consists of definitions of automake variables. It
+ may also contain ordinary Makefile targets. This file is only
+ needed when using automake (newer tools normally use automake, but
+ there are still older tools which have not been converted, in
+ which the developer writes `Makefile.in' directly). *Note Write
+ Makefile.am::.
+
+`acconfig.h'
+ When the configure script creates a portability header file, by
+ using `AM_CONFIG_HEADER' (or, if not using automake,
+ `AC_CONFIG_HEADER'), this file is used to describe macros which are
+ not recognized by the `autoheader' command. This is normally a
+ fairly uninteresting file, consisting of a collection of `#undef'
+ lines with comments. Normally any call to `AC_DEFINE' in
+ `configure.in' will require a line in this file. *Note Write
+ acconfig.h::.
+
+`acinclude.m4'
+ This file is not always required. It defines local autoconf
+ macros. These macros may then be used in `configure.in'. If you
+ don't need any local autoconf macros, then you don't need this
+ file at all. In fact, in general, you never need local autoconf
+ macros, since you can put everything in `configure.in', but
+ sometimes a local macro is convenient.
+
+ Newer tools may omit `acinclude.m4', and instead use a
+ subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS =
+ -I m4' in `Makefile.am' to force `aclocal' to look there for macro
+ definitions. The macro definitions are then placed in separate
+ files in that directory.
+
+ The `acinclude.m4' file is only used when using automake; in older
+ tools, the developer writes `aclocal.m4' directly, if it is needed.
+
+
+File: configure.info, Node: Generated Developer Files, Prev: Written Developer Files, Up: Developer Files
+
+3.1.3 Generated Developer Files
+-------------------------------
+
+The following files would be generated by the developer.
+
+ When using automake, these files are normally not generated manually
+after the first time. Instead, the generated `Makefile' contains rules
+to automatically rebuild the files as required. When
+`AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in
+Cygnus code), the automatic rebuilding rules will only be defined if
+you configure using the `--enable-maintainer-mode' option.
+
+ When using automatic rebuilding, it is important to ensure that all
+the various tools have been built and installed on your `PATH'. Using
+automatic rebuilding is highly recommended, so much so that I'm not
+going to explain what you have to do if you don't use it.
+
+`configure'
+ This is the configure script which will be run when building the
+ package. This is generated by `autoconf' from `configure.in' and
+ `aclocal.m4'. This is a shell script.
+
+`Makefile.in'
+ This is the file which the configure script will turn into the
+ `Makefile' at build time. This file is generated by `automake'
+ from `Makefile.am'. If you aren't using automake, you must write
+ this file yourself. This file is pretty much a normal `Makefile',
+ with some configure substitutions for certain variables.
+
+`aclocal.m4'
+ This file is created by the `aclocal' program, based on the
+ contents of `configure.in' and `acinclude.m4' (or, as noted in the
+ description of `acinclude.m4' above, on the contents of an `m4'
+ subdirectory). This file contains definitions of autoconf macros
+ which `autoconf' will use when generating the file `configure'.
+ These autoconf macros may be defined by you in `acinclude.m4' or
+ they may be defined by other packages such as automake, libtool or
+ gettext. If you aren't using automake, you will normally write
+ this file yourself; in that case, if `configure.in' uses only
+ standard autoconf macros, this file will not be needed at all.
+
+`config.in'
+ This file is created by `autoheader' based on `acconfig.h' and
+ `configure.in'. At build time, the configure script will define
+ some of the macros in it to create `config.h', which may then be
+ included by your program. This permits your C code to use
+ preprocessor conditionals to change its behaviour based on the
+ characteristics of the host system. This file may also be called
+ `config.h.in'.
+
+`stamp.h-in'
+ This rather uninteresting file, which I omitted from the picture,
+ is generated by `automake'. It always contains the string
+ `timestamp'. It is used as a timestamp file indicating whether
+ `config.in' is up to date. Using a timestamp file means that
+ `config.in' can be marked as up to date without actually changing
+ its modification time. This is useful since `config.in' depends
+ upon `configure.in', but it is easy to change `configure.in' in a
+ way which does not affect `config.in'.
+
+
+File: configure.info, Node: Build Files, Next: Support Files, Prev: Developer Files, Up: Files
+
+3.2 Build Files
+===============
+
+This section describes the files which are created at configure and
+build time. These are the files which somebody who builds the package
+will see.
+
+ Of course, the developer will also build the package. The
+distinction between developer files and build files is not that the
+developer does not see the build files, but that somebody who only
+builds the package does not have to worry about the developer files.
+
+* Menu:
+
+* Build Files Picture:: Build Files Picture.
+* Build Files Description:: Build Files Description.
+
+
+File: configure.info, Node: Build Files Picture, Next: Build Files Description, Up: Build Files
+
+3.2.1 Build Files Picture
+-------------------------
+
+Here is a picture of the files which will be created at build time.
+`config.status' is both a created file and a shell script which is run
+to create other files, and the picture attempts to show that.
+
+ config.in *configure* Makefile.in
+ | | |
+ | v |
+ | config.status |
+ | | |
+ *config.status*<======+==========>*config.status*
+ | |
+ v v
+ config.h Makefile
+
+
+File: configure.info, Node: Build Files Description, Prev: Build Files Picture, Up: Build Files
+
+3.2.2 Build Files Description
+-----------------------------
+
+This is a description of the files which are created at build time.
+
+`config.status'
+ The first step in building a package is to run the `configure'
+ script. The `configure' script will create the file
+ `config.status', which is itself a shell script. When you first
+ run `configure', it will automatically run `config.status'. An
+ `Makefile' derived from an automake generated `Makefile.in' will
+ contain rules to automatically run `config.status' again when
+ necessary to recreate certain files if their inputs change.
+
+`Makefile'
+ This is the file which make will read to build the program. The
+ `config.status' script will transform `Makefile.in' into
+ `Makefile'.
+
+`config.h'
+ This file defines C preprocessor macros which C code can use to
+ adjust its behaviour on different systems. The `config.status'
+ script will transform `config.in' into `config.h'.
+
+`config.cache'
+ This file did not fit neatly into the picture, and I omitted it.
+ It is used by the `configure' script to cache results between
+ runs. This can be an important speedup. If you modify
+ `configure.in' in such a way that the results of old tests should
+ change (perhaps you have added a new library to `LDFLAGS'), then
+ you will have to remove `config.cache' to force the tests to be
+ rerun.
+
+ The autoconf manual explains how to set up a site specific cache
+ file. This can speed up running `configure' scripts on your
+ system.
+
+`stamp.h'
+ This file, which I omitted from the picture, is similar to
+ `stamp-h.in'. It is used as a timestamp file indicating whether
+ `config.h' is up to date. This is useful since `config.h' depends
+ upon `config.status', but it is easy for `config.status' to change
+ in a way which does not affect `config.h'.
+
+
+File: configure.info, Node: Support Files, Prev: Build Files, Up: Files
+
+3.3 Support Files
+=================
+
+The GNU configure and build system requires several support files to be
+included with your distribution. You do not normally need to concern
+yourself with these. If you are using the Cygnus tree, most are already
+present. Otherwise, they will be installed with your source by
+`automake' (with the `--add-missing' option) and `libtoolize'.
+
+ You don't have to put the support files in the top level directory.
+You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR'
+macro in `configure.in' to tell `automake' and the `configure' script
+where they are.
+
+ In this section, I describe the support files, so that you can know
+what they are and why they are there.
+
+`ABOUT-NLS'
+ Added by automake if you are using gettext. This is a
+ documentation file about the gettext project.
+
+`ansi2knr.c'
+ Used by an automake generated `Makefile' if you put `ansi2knr' in
+ `AUTOMAKE_OPTIONS' in `Makefile.am'. This permits compiling ANSI
+ C code with a K&R C compiler.
+
+`ansi2knr.1'
+ The man page which goes with `ansi2knr.c'.
+
+`config.guess'
+ A shell script which determines the configuration name for the
+ system on which it is run.
+
+`config.sub'
+ A shell script which canonicalizes a configuration name entered by
+ a user.
+
+`elisp-comp'
+ Used to compile Emacs LISP files.
+
+`install-sh'
+ A shell script which installs a program. This is used if the
+ configure script can not find an install binary.
+
+`ltconfig'
+ Used by libtool. This is a shell script which configures libtool
+ for the particular system on which it is used.
+
+`ltmain.sh'
+ Used by libtool. This is the actual libtool script which is used,
+ after it is configured by `ltconfig' to build a library.
+
+`mdate-sh'
+ A shell script used by an automake generated `Makefile' to pretty
+ print the modification time of a file. This is used to maintain
+ version numbers for texinfo files.
+
+`missing'
+ A shell script used if some tool is missing entirely. This is
+ used by an automake generated `Makefile' to avoid certain sorts of
+ timestamp problems.
+
+`mkinstalldirs'
+ A shell script which creates a directory, including all parent
+ directories. This is used by an automake generated `Makefile'
+ during installation.
+
+`texinfo.tex'
+ Required if you have any texinfo files. This is used when
+ converting Texinfo files into DVI using `texi2dvi' and TeX.
+
+`ylwrap'
+ A shell script used by an automake generated `Makefile' to run
+ programs like `bison', `yacc', `flex', and `lex'. These programs
+ default to producing output files with a fixed name, and the
+ `ylwrap' script runs them in a subdirectory to avoid file name
+ conflicts when using a parallel make program.
+
+
+File: configure.info, Node: Configuration Names, Next: Cross Compilation Tools, Prev: Files, Up: Top
+
+4 Configuration Names
+*********************
+
+The GNU configure system names all systems using a "configuration
+name". All such names used to be triplets (they may now contain four
+parts in certain cases), and the term "configuration triplet" is still
+seen.
+
+* Menu:
+
+* Configuration Name Definition:: Configuration Name Definition.
+* Using Configuration Names:: Using Configuration Names.
+
+
+File: configure.info, Node: Configuration Name Definition, Next: Using Configuration Names, Up: Configuration Names
+
+4.1 Configuration Name Definition
+=================================
+
+This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM. In
+some cases, this is extended to a four part form:
+CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM.
+
+ When using a configuration name in a configure option, it is normally
+not necessary to specify an entire name. In particular, the
+MANUFACTURER field is often omitted, leading to strings such as
+`i386-linux' or `sparc-sunos'. The shell script `config.sub' will
+translate these shortened strings into the canonical form. autoconf
+will arrange for `config.sub' to be run automatically when it is needed.
+
+ The fields of a configuration name are as follows:
+
+CPU
+ The type of processor. This is typically something like `i386' or
+ `sparc'. More specific variants are used as well, such as
+ `mipsel' to indicate a little endian MIPS processor.
+
+MANUFACTURER
+ A somewhat freeform field which indicates the manufacturer of the
+ system. This is often simply `unknown'. Other common strings are
+ `pc' for an IBM PC compatible system, or the name of a workstation
+ vendor, such as `sun'.
+
+OPERATING_SYSTEM
+ The name of the operating system which is run on the system. This
+ will be something like `solaris2.5' or `irix6.3'. There is no
+ particular restriction on the version number, and strings like
+ `aix4.1.4.0' are seen. For an embedded system, which has no
+ operating system, this field normally indicates the type of object
+ file format, such as `elf' or `coff'.
+
+KERNEL
+ This is used mainly for GNU/Linux. A typical GNU/Linux
+ configuration name is `i586-pc-linux-gnulibc1'. In this case the
+ kernel, `linux', is separated from the operating system,
+ `gnulibc1'.
+
+ The shell script `config.guess' will normally print the correct
+configuration name for the system on which it is run. It does by
+running `uname' and by examining other characteristics of the system.
+
+ Because `config.guess' can normally determine the configuration name
+for a machine, it is normally only necessary to specify a configuration
+name when building a cross-compiler or when building using a
+cross-compiler.
+
+
+File: configure.info, Node: Using Configuration Names, Prev: Configuration Name Definition, Up: Configuration Names
+
+4.2 Using Configuration Names
+=============================
+
+A configure script will sometimes have to make a decision based on a
+configuration name. You will need to do this if you have to compile
+code differently based on something which can not be tested using a
+standard autoconf feature test.
+
+ It is normally better to test for particular features, rather than to
+test for a particular system. This is because as Unix evolves,
+different systems copy features from one another. Even if you need to
+determine whether the feature is supported based on a configuration
+name, you should define a macro which describes the feature, rather than
+defining a macro which describes the particular system you are on.
+
+ Testing for a particular system is normally done using a case
+statement in `configure.in'. The case statement might look something
+like the following, assuming that `host' is a shell variable holding a
+canonical configuration name (which will be the case if `configure.in'
+uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro).
+
+ case "${host}" in
+ i[3-7]86-*-linux-gnu*) do something ;;
+ sparc*-sun-solaris2.[56789]*) do something ;;
+ sparc*-sun-solaris*) do something ;;
+ mips*-*-elf*) do something ;;
+ esac
+
+ It is particularly important to use `*' after the operating system
+field, in order to match the version number which will be generated by
+`config.guess'.
+
+ In most cases you must be careful to match a range of processor
+types. For most processor families, a trailing `*' suffices, as in
+`mips*' above. For the i386 family, something along the lines of
+`i[3-7]86' suffices at present. For the m68k family, you will need
+something like `m68*'. Of course, if you do not need to match on the
+processor, it is simpler to just replace the entire field by a `*', as
+in `*-*-irix*'.
+
+
+File: configure.info, Node: Cross Compilation Tools, Next: Canadian Cross, Prev: Configuration Names, Up: Top
+
+5 Cross Compilation Tools
+*************************
+
+The GNU configure and build system can be used to build "cross
+compilation" tools. A cross compilation tool is a tool which runs on
+one system and produces code which runs on another system.
+
+* Menu:
+
+* Cross Compilation Concepts:: Cross Compilation Concepts.
+* Host and Target:: Host and Target.
+* Using the Host Type:: Using the Host Type.
+* Specifying the Target:: Specifying the Target.
+* Using the Target Type:: Using the Target Type.
+* Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree
+
+
+File: configure.info, Node: Cross Compilation Concepts, Next: Host and Target, Up: Cross Compilation Tools
+
+5.1 Cross Compilation Concepts
+==============================
+
+A compiler which produces programs which run on a different system is a
+cross compilation compiler, or simply a "cross compiler". Similarly,
+we speak of cross assemblers, cross linkers, etc.
+
+ In the normal case, a compiler produces code which runs on the same
+system as the one on which the compiler runs. When it is necessary to
+distinguish this case from the cross compilation case, such a compiler
+is called a "native compiler". Similarly, we speak of native
+assemblers, etc.
+
+ Although the debugger is not strictly speaking a compilation tool,
+it is nevertheless meaningful to speak of a cross debugger: a debugger
+which is used to debug code which runs on another system. Everything
+that is said below about configuring cross compilation tools applies to
+the debugger as well.
+
+
+File: configure.info, Node: Host and Target, Next: Using the Host Type, Prev: Cross Compilation Concepts, Up: Cross Compilation Tools
+
+5.2 Host and Target
+===================
+
+When building cross compilation tools, there are two different systems
+involved: the system on which the tools will run, and the system for
+which the tools generate code.
+
+ The system on which the tools will run is called the "host" system.
+
+ The system for which the tools generate code is called the "target"
+system.
+
+ For example, suppose you have a compiler which runs on a GNU/Linux
+system and generates ELF programs for a MIPS embedded system. In this
+case the GNU/Linux system is the host, and the MIPS ELF system is the
+target. Such a compiler could be called a GNU/Linux cross MIPS ELF
+compiler, or, equivalently, a `i386-linux-gnu' cross `mips-elf'
+compiler.
+
+ Naturally, most programs are not cross compilation tools. For those
+programs, it does not make sense to speak of a target. It only makes
+sense to speak of a target for tools like `gcc' or the `binutils' which
+actually produce running code. For example, it does not make sense to
+speak of the target of a tool like `bison' or `make'.
+
+ Most cross compilation tools can also serve as native tools. For a
+native compilation tool, it is still meaningful to speak of a target.
+For a native tool, the target is the same as the host. For example, for
+a GNU/Linux native compiler, the host is GNU/Linux, and the target is
+also GNU/Linux.
+
+
+File: configure.info, Node: Using the Host Type, Next: Specifying the Target, Prev: Host and Target, Up: Cross Compilation Tools
+
+5.3 Using the Host Type
+=======================
+
+In almost all cases the host system is the system on which you run the
+`configure' script, and on which you build the tools (for the case when
+they differ, *note Canadian Cross::).
+
+ If your configure script needs to know the configuration name of the
+host system, and the package is not a cross compilation tool and
+therefore does not have a target, put `AC_CANONICAL_HOST' in
+`configure.in'. This macro will arrange to define a few shell
+variables when the `configure' script is run.
+
+`host'
+ The canonical configuration name of the host. This will normally
+ be determined by running the `config.guess' shell script, although
+ the user is permitted to override this by using an explicit
+ `--host' option.
+
+`host_alias'
+ In the unusual case that the user used an explicit `--host' option,
+ this will be the argument to `--host'. In the normal case, this
+ will be the same as the `host' variable.
+
+`host_cpu'
+`host_vendor'
+`host_os'
+ The first three parts of the canonical configuration name.
+
+ The shell variables may be used by putting shell code in
+`configure.in'. For an example, see *Note Using Configuration Names::.
+
+
+File: configure.info, Node: Specifying the Target, Next: Using the Target Type, Prev: Using the Host Type, Up: Cross Compilation Tools
+
+5.4 Specifying the Target
+=========================
+
+By default, the `configure' script will assume that the target is the
+same as the host. This is the more common case; for example, it leads
+to a native compiler rather than a cross compiler.
+
+ If you want to build a cross compilation tool, you must specify the
+target explicitly by using the `--target' option when you run
+`configure'. The argument to `--target' is the configuration name of
+the system for which you wish to generate code. *Note Configuration
+Names::.
+
+ For example, to build tools which generate code for a MIPS ELF
+embedded system, you would use `--target mips-elf'.
+
+
+File: configure.info, Node: Using the Target Type, Next: Cross Tools in the Cygnus Tree, Prev: Specifying the Target, Up: Cross Compilation Tools
+
+5.5 Using the Target Type
+=========================
+
+When writing `configure.in' for a cross compilation tool, you will need
+to use information about the target. To do this, put
+`AC_CANONICAL_SYSTEM' in `configure.in'.
+
+ `AC_CANONICAL_SYSTEM' will look for a `--target' option and
+canonicalize it using the `config.sub' shell script. It will also run
+`AC_CANONICAL_HOST' (*note Using the Host Type::).
+
+ The target type will be recorded in the following shell variables.
+Note that the host versions of these variables will also be defined by
+`AC_CANONICAL_HOST'.
+
+`target'
+ The canonical configuration name of the target.
+
+`target_alias'
+ The argument to the `--target' option. If the user did not specify
+ a `--target' option, this will be the same as `host_alias'.
+
+`target_cpu'
+`target_vendor'
+`target_os'
+ The first three parts of the canonical target configuration name.
+
+ Note that if `host' and `target' are the same string, you can assume
+a native configuration. If they are different, you can assume a cross
+configuration.
+
+ It is arguably possible for `host' and `target' to represent the
+same system, but for the strings to not be identical. For example, if
+`config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures
+with `--target sparc-sun-sunos4.1', then the slight differences between
+the two versions of SunOS may be unimportant for your tool. However,
+in the general case it can be quite difficult to determine whether the
+differences between two configuration names are significant or not.
+Therefore, by convention, if the user specifies a `--target' option
+without specifying a `--host' option, it is assumed that the user wants
+to configure a cross compilation tool.
+
+ The variables `target' and `target_alias' should be handled
+differently.
+
+ In general, whenever the user may actually see a string,
+`target_alias' should be used. This includes anything which may appear
+in the file system, such as a directory name or part of a tool name.
+It also includes any tool output, unless it is clearly labelled as the
+canonical target configuration name. This permits the user to use the
+`--target' option to specify how the tool will appear to the outside
+world.
+
+ On the other hand, when checking for characteristics of the target
+system, `target' should be used. This is because a wide variety of
+`--target' options may map into the same canonical configuration name.
+You should not attempt to duplicate the canonicalization done by
+`config.sub' in your own code.
+
+ By convention, cross tools are installed with a prefix of the
+argument used with the `--target' option, also known as `target_alias'
+(*note Using the Target Type::). If the user does not use the
+`--target' option, and thus is building a native tool, no prefix is
+used.
+
+ For example, if gcc is configured with `--target mips-elf', then the
+installed binary will be named `mips-elf-gcc'. If gcc is configured
+without a `--target' option, then the installed binary will be named
+`gcc'.
+
+ The autoconf macro `AC_ARG_PROGRAM' will handle this for you. If
+you are using automake, no more need be done; the programs will
+automatically be installed with the correct prefixes. Otherwise, see
+the autoconf documentation for `AC_ARG_PROGRAM'.
+
+
+File: configure.info, Node: Cross Tools in the Cygnus Tree, Prev: Using the Target Type, Up: Cross Compilation Tools
+
+5.6 Cross Tools in the Cygnus Tree
+==================================
+
+The Cygnus tree is used for various packages including gdb, the GNU
+binutils, and egcs. It is also, of course, used for Cygnus releases.
+
+ In the Cygnus tree, the top level `configure' script uses the old
+Cygnus configure system, not autoconf. The top level `Makefile.in' is
+written to build packages based on what is in the source tree, and
+supports building a large number of tools in a single
+`configure'/`make' step.
+
+ The Cygnus tree may be configured with a `--target' option. The
+`--target' option applies recursively to every subdirectory, and
+permits building an entire set of cross tools at once.
+
+* Menu:
+
+* Host and Target Libraries:: Host and Target Libraries.
+* Target Library Configure Scripts:: Target Library Configure Scripts.
+* Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree.
+* Target libiberty:: Target libiberty
+
+
+File: configure.info, Node: Host and Target Libraries, Next: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree
+
+5.6.1 Host and Target Libraries
+-------------------------------
+
+The Cygnus tree distinguishes host libraries from target libraries.
+
+ Host libraries are built with the compiler used to build the programs
+which run on the host, which is called the host compiler. This includes
+libraries such as `bfd' and `tcl'. These libraries are built with the
+host compiler, and are linked into programs like the binutils or gcc
+which run on the host.
+
+ Target libraries are built with the target compiler. If gcc is
+present in the source tree, then the target compiler is the gcc that is
+built using the host compiler. Target libraries are libraries such as
+`newlib' and `libstdc++'. These libraries are not linked into the host
+programs, but are instead made available for use with programs built
+with the target compiler.
+
+ For the rest of this section, assume that gcc is present in the
+source tree, so that it will be used to build the target libraries.
+
+ There is a complication here. The configure process needs to know
+which compiler you are going to use to build a tool; otherwise, the
+feature tests will not work correctly. The Cygnus tree handles this by
+not configuring the target libraries until the target compiler is
+built. In order to permit everything to build using a single
+`configure'/`make', the configuration of the target libraries is
+actually triggered during the make step.
+
+ When the target libraries are configured, the `--target' option is
+not used. Instead, the `--host' option is used with the argument of
+the `--target' option for the overall configuration. If no `--target'
+option was used for the overall configuration, the `--host' option will
+be passed with the output of the `config.guess' shell script. Any
+`--build' option is passed down unchanged.
+
+ This translation of configuration options is done because since the
+target libraries are compiled with the target compiler, they are being
+built in order to run on the target of the overall configuration. By
+the definition of host, this means that their host system is the same as
+the target system of the overall configuration.
+
+ The same process is used for both a native configuration and a cross
+configuration. Even when using a native configuration, the target
+libraries will be configured and built using the newly built compiler.
+This is particularly important for the C++ libraries, since there is no
+reason to assume that the C++ compiler used to build the host tools (if
+there even is one) uses the same ABI as the g++ compiler which will be
+used to build the target libraries.
+
+ There is one difference between a native configuration and a cross
+configuration. In a native configuration, the target libraries are
+normally configured and built as siblings of the host tools. In a cross
+configuration, the target libraries are normally built in a subdirectory
+whose name is the argument to `--target'. This is mainly for
+historical reasons.
+
+ To summarize, running `configure' in the Cygnus tree configures all
+the host libraries and tools, but does not configure any of the target
+libraries. Running `make' then does the following steps:
+
+ * Build the host libraries.
+
+ * Build the host programs, including gcc. Note that we call gcc
+ both a host program (since it runs on the host) and a target
+ compiler (since it generates code for the target).
+
+ * Using the newly built target compiler, configure the target
+ libraries.
+
+ * Build the target libraries.
+
+ The steps need not be done in precisely this order, since they are
+actually controlled by `Makefile' targets.
+
+
+File: configure.info, Node: Target Library Configure Scripts, Next: Make Targets in Cygnus Tree, Prev: Host and Target Libraries, Up: Cross Tools in the Cygnus Tree
+
+5.6.2 Target Library Configure Scripts
+--------------------------------------
+
+There are a few things you must know in order to write a configure
+script for a target library. This is just a quick sketch, and beginners
+shouldn't worry if they don't follow everything here.
+
+ The target libraries are configured and built using a newly built
+target compiler. There may not be any startup files or libraries for
+this target compiler. In fact, those files will probably be built as
+part of some target library, which naturally means that they will not
+exist when your target library is configured.
+
+ This means that the configure script for a target library may not use
+any test which requires doing a link. This unfortunately includes many
+useful autoconf macros, such as `AC_CHECK_FUNCS'. autoconf macros
+which do a compile but not a link, such as `AC_CHECK_HEADERS', may be
+used.
+
+ This is a severe restriction, but normally not a fatal one, as target
+libraries can often assume the presence of other target libraries, and
+thus know which functions will be available.
+
+ As of this writing, the autoconf macro `AC_PROG_CC' does a link to
+make sure that the compiler works. This may fail in a target library,
+so target libraries must use a different set of macros to locate the
+compiler. See the `configure.in' file in a directory like `libiberty'
+or `libgloss' for an example.
+
+ As noted in the previous section, target libraries are sometimes
+built in directories which are siblings to the host tools, and are
+sometimes built in a subdirectory. The `--with-target-subdir' configure
+option will be passed when the library is configured. Its value will be
+an empty string if the target library is a sibling. Its value will be
+the name of the subdirectory if the target library is in a subdirectory.
+
+ If the overall build is not a native build (i.e., the overall
+configure used the `--target' option), then the library will be
+configured with the `--with-cross-host' option. The value of this
+option will be the host system of the overall build. Recall that the
+host system of the library will be the target of the overall build. If
+the overall build is a native build, the `--with-cross-host' option
+will not be used.
+
+ A library which can be built both standalone and as a target library
+may want to install itself into different directories depending upon the
+case. When built standalone, or when built native, the library should
+be installed in `$(libdir)'. When built as a target library which is
+not native, the library should be installed in `$(tooldir)/lib'. The
+`--with-cross-host' option may be used to distinguish these cases.
+
+ This same test of `--with-cross-host' may be used to see whether it
+is OK to use link tests in the configure script. If the
+`--with-cross-host' option is not used, then the library is being built
+either standalone or native, and a link should work.
+
+
+File: configure.info, Node: Make Targets in Cygnus Tree, Next: Target libiberty, Prev: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree
+
+5.6.3 Make Targets in Cygnus Tree
+---------------------------------
+
+The top level `Makefile' in the Cygnus tree defines targets for every
+known subdirectory.
+
+ For every subdirectory DIR which holds a host library or program,
+the `Makefile' target `all-DIR' will build that library or program.
+
+ There are dependencies among host tools. For example, building gcc
+requires first building gas, because the gcc build process invokes the
+target assembler. These dependencies are reflected in the top level
+`Makefile'.
+
+ For every subdirectory DIR which holds a target library, the
+`Makefile' target `configure-target-DIR' will configure that library.
+The `Makefile' target `all-target-DIR' will build that library.
+
+ Every `configure-target-DIR' target depends upon `all-gcc', since
+gcc, the target compiler, is required to configure the tool. Every
+`all-target-DIR' target depends upon the corresponding
+`configure-target-DIR' target.
+
+ There are several other targets which may be of interest for each
+directory: `install-DIR', `clean-DIR', and `check-DIR'. There are also
+corresponding `target' versions of these for the target libraries ,
+such as `install-target-DIR'.
+
+
+File: configure.info, Node: Target libiberty, Prev: Make Targets in Cygnus Tree, Up: Cross Tools in the Cygnus Tree
+
+5.6.4 Target libiberty
+----------------------
+
+The `libiberty' subdirectory is currently a special case, in that it is
+the only directory which is built both using the host compiler and
+using the target compiler.
+
+ This is because the files in `libiberty' are used when building the
+host tools, and they are also incorporated into the `libstdc++' target
+library as support code.
+
+ This duality does not pose any particular difficulties. It means
+that there are targets for both `all-libiberty' and
+`all-target-libiberty'.
+
+ In a native configuration, when target libraries are not built in a
+subdirectory, the same objects are normally used as both the host build
+and the target build. This is normally OK, since libiberty contains
+only C code, and in a native configuration the results of the host
+compiler and the target compiler are normally interoperable.
+
+ Irix 6 is again an exception here, since the SGI native compiler
+defaults to using the `O32' ABI, and gcc defaults to using the `N32'
+ABI. On Irix 6, the target libraries are built in a subdirectory even
+for a native configuration, avoiding this problem.
+
+ There are currently no other libraries built for both the host and
+the target, but there is no conceptual problem with adding more.
+
+
+File: configure.info, Node: Canadian Cross, Next: Cygnus Configure, Prev: Cross Compilation Tools, Up: Top
+
+6 Canadian Cross
+****************
+
+It is possible to use the GNU configure and build system to build a
+program which will run on a system which is different from the system on
+which the tools are built. In other words, it is possible to build
+programs using a cross compiler.
+
+ This is referred to as a "Canadian Cross".
+
+* Menu:
+
+* Canadian Cross Example:: Canadian Cross Example.
+* Canadian Cross Concepts:: Canadian Cross Concepts.
+* Build Cross Host Tools:: Build Cross Host Tools.
+* Build and Host Options:: Build and Host Options.
+* CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree.
+* CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree.
+* Supporting Canadian Cross:: Supporting Canadian Cross.
+
+
+File: configure.info, Node: Canadian Cross Example, Next: Canadian Cross Concepts, Up: Canadian Cross
+
+6.1 Canadian Cross Example
+==========================
+
+Here is an example of a Canadian Cross.
+
+ While running on a GNU/Linux, you can build a program which will run
+on a Solaris system. You would use a GNU/Linux cross Solaris compiler
+to build the program.
+
+ Of course, you could not run the resulting program on your GNU/Linux
+system. You would have to copy it over to a Solaris system before you
+would run it.
+
+ Of course, you could also simply build the programs on the Solaris
+system in the first place. However, perhaps the Solaris system is not
+available for some reason; perhaps you actually don't have one, but you
+want to build the tools for somebody else to use. Or perhaps your
+GNU/Linux system is much faster than your Solaris system.
+
+ A Canadian Cross build is most frequently used when building
+programs to run on a non-Unix system, such as DOS or Windows. It may
+be simpler to configure and build on a Unix system than to support the
+configuration machinery on a non-Unix system.
+
+
+File: configure.info, Node: Canadian Cross Concepts, Next: Build Cross Host Tools, Prev: Canadian Cross Example, Up: Canadian Cross
+
+6.2 Canadian Cross Concepts
+===========================
+
+When building a Canadian Cross, there are at least two different systems
+involved: the system on which the tools are being built, and the system
+on which the tools will run.
+
+ The system on which the tools are being built is called the "build"
+system.
+
+ The system on which the tools will run is called the host system.
+
+ For example, if you are building a Solaris program on a GNU/Linux
+system, as in the previous section, the build system would be GNU/Linux,
+and the host system would be Solaris.
+
+ It is, of course, possible to build a cross compiler using a Canadian
+Cross (i.e., build a cross compiler using a cross compiler). In this
+case, the system for which the resulting cross compiler generates code
+is called the target system. (For a more complete discussion of host
+and target systems, *note Host and Target::).
+
+ An example of building a cross compiler using a Canadian Cross would
+be building a Windows cross MIPS ELF compiler on a GNU/Linux system. In
+this case the build system would be GNU/Linux, the host system would be
+Windows, and the target system would be MIPS ELF.
+
+ The name Canadian Cross comes from the case when the build, host, and
+target systems are all different. At the time that these issues were
+all being hashed out, Canada had three national political parties.
+
+
+File: configure.info, Node: Build Cross Host Tools, Next: Build and Host Options, Prev: Canadian Cross Concepts, Up: Canadian Cross
+
+6.3 Build Cross Host Tools
+==========================
+
+In order to configure a program for a Canadian Cross build, you must
+first build and install the set of cross tools you will use to build the
+program.
+
+ These tools will be build cross host tools. That is, they will run
+on the build system, and will produce code that runs on the host system.
+
+ It is easy to confuse the meaning of build and host here. Always
+remember that the build system is where you are doing the build, and the
+host system is where the resulting program will run. Therefore, you
+need a build cross host compiler.
+
+ In general, you must have a complete cross environment in order to do
+the build. This normally means a cross compiler, cross assembler, and
+so forth, as well as libraries and include files for the host system.
+
+
+File: configure.info, Node: Build and Host Options, Next: CCross not in Cygnus Tree, Prev: Build Cross Host Tools, Up: Canadian Cross
+
+6.4 Build and Host Options
+==========================
+
+When you run `configure', you must use both the `--build' and `--host'
+options.
+
+ The `--build' option is used to specify the configuration name of
+the build system. This can normally be the result of running the
+`config.guess' shell script, and it is reasonable to use
+`--build=`config.guess`'.
+
+ The `--host' option is used to specify the configuration name of the
+host system.
+
+ As we explained earlier, `config.guess' is used to set the default
+value for the `--host' option (*note Using the Host Type::). We can
+now see that since `config.guess' returns the type of system on which
+it is run, it really identifies the build system. Since the host
+system is normally the same as the build system (i.e., people do not
+normally build using a cross compiler), it is reasonable to use the
+result of `config.guess' as the default for the host system when the
+`--host' option is not used.
+
+ It might seem that if the `--host' option were used without the
+`--build' option that the configure script could run `config.guess' to
+determine the build system, and presume a Canadian Cross if the result
+of `config.guess' differed from the `--host' option. However, for
+historical reasons, some configure scripts are routinely run using an
+explicit `--host' option, rather than using the default from
+`config.guess'. As noted earlier, it is difficult or impossible to
+reliably compare configuration names (*note Using the Target Type::).
+Therefore, by convention, if the `--host' option is used, but the
+`--build' option is not used, then the build system defaults to the
+host system.
+
+
+File: configure.info, Node: CCross not in Cygnus Tree, Next: CCross in Cygnus Tree, Prev: Build and Host Options, Up: Canadian Cross
+
+6.5 Canadian Cross not in Cygnus Tree.
+======================================
+
+If you are not using the Cygnus tree, you must explicitly specify the
+cross tools which you want to use to build the program. This is done by
+setting environment variables before running the `configure' script.
+
+ You must normally set at least the environment variables `CC', `AR',
+and `RANLIB' to the cross tools which you want to use to build.
+
+ For some programs, you must set additional cross tools as well, such
+as `AS', `LD', or `NM'.
+
+ You would set these environment variables to the build cross tools
+which you are going to use.
+
+ For example, if you are building a Solaris program on a GNU/Linux
+system, and your GNU/Linux cross Solaris compiler were named
+`solaris-gcc', then you would set the environment variable `CC' to
+`solaris-gcc'.
+
+
+File: configure.info, Node: CCross in Cygnus Tree, Next: Supporting Canadian Cross, Prev: CCross not in Cygnus Tree, Up: Canadian Cross
+
+6.6 Canadian Cross in Cygnus Tree
+=================================
+
+This section describes configuring and building a Canadian Cross when
+using the Cygnus tree.
+
+* Menu:
+
+* Standard Cygnus CCross:: Building a Normal Program.
+* Cross Cygnus CCross:: Building a Cross Program.
+
+
+File: configure.info, Node: Standard Cygnus CCross, Next: Cross Cygnus CCross, Up: CCross in Cygnus Tree
+
+6.6.1 Building a Normal Program
+-------------------------------
+
+When configuring a Canadian Cross in the Cygnus tree, all the
+appropriate environment variables are automatically set to `HOST-TOOL',
+where HOST is the value used for the `--host' option, and TOOL is the
+name of the tool (e.g., `gcc', `as', etc.). These tools must be on
+your `PATH'.
+
+ Adding a prefix of HOST will give the usual name for the build cross
+host tools. To see this, consider that when these cross tools were
+built, they were configured to run on the build system and to produce
+code for the host system. That is, they were configured with a
+`--target' option that is the same as the system which we are now
+calling the host. Recall that the default name for installed cross
+tools uses the target system as a prefix (*note Using the Target
+Type::). Since that is the system which we are now calling the host,
+HOST is the right prefix to use.
+
+ For example, if you configure with `--build=i386-linux-gnu' and
+`--host=solaris', then the Cygnus tree will automatically default to
+using the compiler `solaris-gcc'. You must have previously built and
+installed this compiler, probably by doing a build with no `--host'
+option and with a `--target' option of `solaris'.
+
+
+File: configure.info, Node: Cross Cygnus CCross, Prev: Standard Cygnus CCross, Up: CCross in Cygnus Tree
+
+6.6.2 Building a Cross Program
+------------------------------
+
+There are additional considerations if you want to build a cross
+compiler, rather than a native compiler, in the Cygnus tree using a
+Canadian Cross.
+
+ When you build a cross compiler using the Cygnus tree, then the
+target libraries will normally be built with the newly built target
+compiler (*note Host and Target Libraries::). However, this will not
+work when building with a Canadian Cross. This is because the newly
+built target compiler will be a program which runs on the host system,
+and therefore will not be able to run on the build system.
+
+ Therefore, when building a cross compiler with the Cygnus tree, you
+must first install a set of build cross target tools. These tools will
+be used when building the target libraries.
+
+ Note that this is not a requirement of a Canadian Cross in general.
+For example, it would be possible to build just the host cross target
+tools on the build system, to copy the tools to the host system, and to
+build the target libraries on the host system. The requirement for
+build cross target tools is imposed by the Cygnus tree, which expects
+to be able to build both host programs and target libraries in a single
+`configure'/`make' step. Because it builds these in a single step, it
+expects to be able to build the target libraries on the build system,
+which means that it must use a build cross target toolchain.
+
+ For example, suppose you want to build a Windows cross MIPS ELF
+compiler on a GNU/Linux system. You must have previously installed
+both a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
+compiler.
+
+ In order to build the Windows (configuration name `i386-cygwin32')
+cross MIPS ELF (configure name `mips-elf') compiler, you might execute
+the following commands (long command lines are broken across lines with
+a trailing backslash as a continuation character).
+
+ mkdir linux-x-cygwin32
+ cd linux-x-cygwin32
+ SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \
+ --exec-prefix=INSTALLDIR/H-i386-linux
+ make
+ make install
+ cd ..
+ mkdir linux-x-mips-elf
+ cd linux-x-mips-elf
+ SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \
+ --exec-prefix=INSTALLDIR/H-i386-linux
+ make
+ make install
+ cd ..
+ mkdir cygwin32-x-mips-elf
+ cd cygwin32-x-mips-elf
+ SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \
+ --target=mips-elf --prefix=WININSTALLDIR \
+ --exec-prefix=WININSTALLDIR/H-i386-cygwin32
+ make
+ make install
+
+ You would then copy the contents of WININSTALLDIR over to the
+Windows machine, and run the resulting programs.
+
+
+File: configure.info, Node: Supporting Canadian Cross, Prev: CCross in Cygnus Tree, Up: Canadian Cross
+
+6.7 Supporting Canadian Cross
+=============================
+
+If you want to make it possible to build a program you are developing
+using a Canadian Cross, you must take some care when writing your
+configure and make rules. Simple cases will normally work correctly.
+However, it is not hard to write configure and make tests which will
+fail in a Canadian Cross.
+
+* Menu:
+
+* CCross in Configure:: Supporting Canadian Cross in Configure Scripts.
+* CCross in Make:: Supporting Canadian Cross in Makefiles.
+
+
+File: configure.info, Node: CCross in Configure, Next: CCross in Make, Up: Supporting Canadian Cross
+
+6.7.1 Supporting Canadian Cross in Configure Scripts
+----------------------------------------------------
+
+In a `configure.in' file, after calling `AC_PROG_CC', you can find out
+whether this is a Canadian Cross configure by examining the shell
+variable `cross_compiling'. In a Canadian Cross, which means that the
+compiler is a cross compiler, `cross_compiling' will be `yes'. In a
+normal configuration, `cross_compiling' will be `no'.
+
+ You ordinarily do not need to know the type of the build system in a
+configure script. However, if you do need that information, you can get
+it by using the macro `AC_CANONICAL_SYSTEM', the same macro that is
+used to determine the target system. This macro will set the variables
+`build', `build_alias', `build_cpu', `build_vendor', and `build_os',
+which correspond to the similar `target' and `host' variables, except
+that they describe the build system.
+
+ When writing tests in `configure.in', you must remember that you
+want to test the host environment, not the build environment.
+
+ Macros like `AC_CHECK_FUNCS' which use the compiler will test the
+host environment. That is because the tests will be done by running the
+compiler, which is actually a build cross host compiler. If the
+compiler can find the function, that means that the function is present
+in the host environment.
+
+ Tests like `test -f /dev/ptyp0', on the other hand, will test the
+build environment. Remember that the configure script is running on the
+build system, not the host system. If your configure scripts examines
+files, those files will be on the build system. Whatever you determine
+based on those files may or may not be the case on the host system.
+
+ Most autoconf macros will work correctly for a Canadian Cross. The
+main exception is `AC_TRY_RUN'. This macro tries to compile and run a
+test program. This will fail in a Canadian Cross, because the program
+will be compiled for the host system, which means that it will not run
+on the build system.
+
+ The `AC_TRY_RUN' macro provides an optional argument to tell the
+configure script what to do in a Canadian Cross. If that argument is
+not present, you will get a warning when you run `autoconf':
+ warning: AC_TRY_RUN called without default to allow cross compiling
+ This tells you that the resulting `configure' script will not work
+with a Canadian Cross.
+
+ In some cases while it may better to perform a test at configure
+time, it is also possible to perform the test at run time. In such a
+case you can use the cross compiling argument to `AC_TRY_RUN' to tell
+your program that the test could not be performed at configure time.
+
+ There are a few other autoconf macros which will not work correctly
+with a Canadian Cross: a partial list is `AC_FUNC_GETPGRP',
+`AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and
+`AC_SYS_RESTARTABLE_SYSCALLS'. The `AC_CHECK_SIZEOF' macro is
+generally not very useful with a Canadian Cross; it permits an optional
+argument indicating the default size, but there is no way to know what
+the correct default should be.
+
+
+File: configure.info, Node: CCross in Make, Prev: CCross in Configure, Up: Supporting Canadian Cross
+
+6.7.2 Supporting Canadian Cross in Makefiles.
+---------------------------------------------
+
+The main Canadian Cross issue in a `Makefile' arises when you want to
+use a subsidiary program to generate code or data which you will then
+include in your real program.
+
+ If you compile this subsidiary program using `$(CC)' in the usual
+way, you will not be able to run it. This is because `$(CC)' will
+build a program for the host system, but the program is being built on
+the build system.
+
+ You must instead use a compiler for the build system, rather than the
+host system. In the Cygnus tree, this make variable `$(CC_FOR_BUILD)'
+will hold a compiler for the build system.
+
+ Note that you should not include `config.h' in a file you are
+compiling with `$(CC_FOR_BUILD)'. The `configure' script will build
+`config.h' with information for the host system. However, you are
+compiling the file using a compiler for the build system (a native
+compiler). Subsidiary programs are normally simple filters which do no
+user interaction, and it is normally possible to write them in a highly
+portable fashion so that the absence of `config.h' is not crucial.
+
+ The gcc `Makefile.in' shows a complex situation in which certain
+files, such as `rtl.c', must be compiled into both subsidiary programs
+run on the build system and into the final program. This approach may
+be of interest for advanced build system hackers. Note that the build
+system compiler is rather confusingly called `HOST_CC'.
+
+
+File: configure.info, Node: Cygnus Configure, Next: Multilibs, Prev: Canadian Cross, Up: Top
+
+7 Cygnus Configure
+******************
+
+The Cygnus configure script predates autoconf. All of its interesting
+features have been incorporated into autoconf. No new programs should
+be written to use the Cygnus configure script.
+
+ However, the Cygnus configure script is still used in a few places:
+at the top of the Cygnus tree and in a few target libraries in the
+Cygnus tree. Until those uses have been replaced with autoconf, some
+brief notes are appropriate here. This is not complete documentation,
+but it should be possible to use this as a guide while examining the
+scripts themselves.
+
+* Menu:
+
+* Cygnus Configure Basics:: Cygnus Configure Basics.
+* Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries.
+
+
+File: configure.info, Node: Cygnus Configure Basics, Next: Cygnus Configure in C++ Libraries, Up: Cygnus Configure
+
+7.1 Cygnus Configure Basics
+===========================
+
+Cygnus configure does not use any generated files; there is no program
+corresponding to `autoconf'. Instead, there is a single shell script
+named `configure' which may be found at the top of the Cygnus tree.
+This shell script was written by hand; it was not generated by
+autoconf, and it is incorrect, and indeed harmful, to run `autoconf' in
+the top level of a Cygnus tree.
+
+ Cygnus configure works in a particular directory by examining the
+file `configure.in' in that directory. That file is broken into four
+separate shell scripts.
+
+ The first is the contents of `configure.in' up to a line that starts
+with `# per-host:'. This is the common part.
+
+ The second is the rest of `configure.in' up to a line that starts
+with `# per-target:'. This is the per host part.
+
+ The third is the rest of `configure.in' up to a line that starts
+with `# post-target:'. This is the per target part.
+
+ The fourth is the remainder of `configure.in'. This is the post
+target part.
+
+ If any of these comment lines are missing, the corresponding shell
+script is empty.
+
+ Cygnus configure will first execute the common part. This must set
+the shell variable `srctrigger' to the name of a source file, to
+confirm that Cygnus configure is looking at the right directory. This
+may set the shell variables `package_makefile_frag' and
+`package_makefile_rules_frag'.
+
+ Cygnus configure will next set the `build' and `host' shell
+variables, and execute the per host part. This may set the shell
+variable `host_makefile_frag'.
+
+ Cygnus configure will next set the `target' variable, and execute
+the per target part. This may set the shell variable
+`target_makefile_frag'.
+
+ Any of these scripts may set the `subdirs' shell variable. This
+variable is a list of subdirectories where a `Makefile.in' file may be
+found. Cygnus configure will automatically look for a `Makefile.in'
+file in the current directory. The `subdirs' shell variable is not
+normally used, and I believe that the only directory which uses it at
+present is `newlib'.
+
+ For each `Makefile.in', Cygnus configure will automatically create a
+`Makefile' by adding definitions for `make' variables such as `host'
+and `target', and automatically editing the values of `make' variables
+such as `prefix' if they are present.
+
+ Also, if any of the `makefile_frag' shell variables are set, Cygnus
+configure will interpret them as file names relative to either the
+working directory or the source directory, and will read the contents of
+the file into the generated `Makefile'. The file contents will be read
+in after the first line in `Makefile.in' which starts with `####'.
+
+ These `Makefile' fragments are used to customize behaviour for a
+particular host or target. They serve to select particular files to
+compile, and to define particular preprocessor macros by providing
+values for `make' variables which are then used during compilation.
+Cygnus configure, unlike autoconf, normally does not do feature tests,
+and normally requires support to be added manually for each new host.
+
+ The `Makefile' fragment support is similar to the autoconf
+`AC_SUBST_FILE' macro.
+
+ After creating each `Makefile', the post target script will be run
+(i.e., it may be run several times). This script may further customize
+the `Makefile'. When it is run, the shell variable `Makefile' will
+hold the name of the `Makefile', including the appropriate directory
+component.
+
+ Like an autoconf generated `configure' script, Cygnus configure will
+create a file named `config.status' which, when run, will automatically
+recreate the configuration. The `config.status' file will simply
+execute the Cygnus configure script again with the appropriate
+arguments.
+
+ Any of the parts of `configure.in' may set the shell variables
+`files' and `links'. Cygnus configure will set up symlinks from the
+names in `links' to the files named in `files'. This is similar to the
+autoconf `AC_LINK_FILES' macro.
+
+ Finally, any of the parts of `configure.in' may set the shell
+variable `configdirs' to a set of subdirectories. If it is set, Cygnus
+configure will recursively run the configure process in each
+subdirectory. If the subdirectory uses Cygnus configure, it will
+contain a `configure.in' file but no `configure' file, in which case
+Cygnus configure will invoke itself recursively. If the subdirectory
+has a `configure' file, Cygnus configure assumes that it is an autoconf
+generated `configure' script, and simply invokes it directly.
+
+
+File: configure.info, Node: Cygnus Configure in C++ Libraries, Prev: Cygnus Configure Basics, Up: Cygnus Configure
+
+7.2 Cygnus Configure in C++ Libraries
+=====================================
+
+The C++ library configure system, written by Per Bothner, deserves
+special mention. It uses Cygnus configure, but it does feature testing
+like that done by autoconf generated `configure' scripts. This
+approach is used in the libraries `libio', `libstdc++', and `libg++'.
+
+ Most of the `Makefile' information is written out by the shell
+script `libio/config.shared'. Each `configure.in' file sets certain
+shell variables, and then invokes `config.shared' to create two package
+`Makefile' fragments. These fragments are then incorporated into the
+resulting `Makefile' by the Cygnus configure script.
+
+ The file `_G_config.h' is created in the `libio' object directory by
+running the shell script `libio/gen-params'. This shell script uses
+feature tests to define macros and typedefs in `_G_config.h'.
+
+
+File: configure.info, Node: Multilibs, Next: FAQ, Prev: Cygnus Configure, Up: Top
+
+8 Multilibs
+***********
+
+For some targets gcc may have different processor requirements depending
+upon command line options. An obvious example is the `-msoft-float'
+option supported on several processors. This option means that the
+floating point registers are not available, which means that floating
+point operations must be done by calling an emulation subroutine rather
+than by using machine instructions.
+
+ For such options, gcc is often configured to compile target libraries
+twice: once with `-msoft-float' and once without. When gcc compiles
+target libraries more than once, the resulting libraries are called
+"multilibs".
+
+ Multilibs are not really part of the GNU configure and build system,
+but we discuss them here since they require support in the `configure'
+scripts and `Makefile's used for target libraries.
+
+* Menu:
+
+* Multilibs in gcc:: Multilibs in gcc.
+* Multilibs in Target Libraries:: Multilibs in Target Libraries.
+
+
+File: configure.info, Node: Multilibs in gcc, Next: Multilibs in Target Libraries, Up: Multilibs
+
+8.1 Multilibs in gcc
+====================
+
+In gcc, multilibs are defined by setting the variable
+`MULTILIB_OPTIONS' in the target `Makefile' fragment. Several other
+`MULTILIB' variables may also be defined there. *Note The Target
+Makefile Fragment: (gcc)Target Fragment.
+
+ If you have built gcc, you can see what multilibs it uses by running
+it with the `-print-multi-lib' option. The output `.;' means that no
+multilibs are used. In general, the output is a sequence of lines, one
+per multilib. The first part of each line, up to the `;', is the name
+of the multilib directory. The second part is a list of compiler
+options separated by `@' characters.
+
+ Multilibs are built in a tree of directories. The top of the tree,
+represented by `.' in the list of multilib directories, is the default
+library to use when no special compiler options are used. The
+subdirectories of the tree hold versions of the library to use when
+particular compiler options are used.
+
+
+File: configure.info, Node: Multilibs in Target Libraries, Prev: Multilibs in gcc, Up: Multilibs
+
+8.2 Multilibs in Target Libraries
+=================================
+
+The target libraries in the Cygnus tree are automatically built with
+multilibs. That means that each library is built multiple times.
+
+ This default is set in the top level `configure.in' file, by adding
+`--enable-multilib' to the list of arguments passed to configure when
+it is run for the target libraries (*note Host and Target Libraries::).
+
+ Each target library uses the shell script `config-ml.in', written by
+Doug Evans, to prepare to build target libraries. This shell script is
+invoked after the `Makefile' has been created by the `configure'
+script. If multilibs are not enabled, it does nothing, otherwise it
+modifies the `Makefile' to support multilibs.
+
+ The `config-ml.in' script makes one copy of the `Makefile' for each
+multilib in the appropriate subdirectory. When configuring in the
+source directory (which is not recommended), it will build a symlink
+tree of the sources in each subdirectory.
+
+ The `config-ml.in' script sets several variables in the various
+`Makefile's. The `Makefile.in' must have definitions for these
+variables already; `config-ml.in' simply changes the existing values.
+The `Makefile' should use default values for these variables which will
+do the right thing in the subdirectories.
+
+`MULTISRCTOP'
+ `config-ml.in' will set this to a sequence of `../' strings, where
+ the number of strings is the number of multilib levels in the
+ source tree. The default value should be the empty string.
+
+`MULTIBUILDTOP'
+ `config-ml.in' will set this to a sequence of `../' strings, where
+ the number of strings is number of multilib levels in the object
+ directory. The default value should be the empty string. This
+ will differ from `MULTISRCTOP' when configuring in the source tree
+ (which is not recommended).
+
+`MULTIDIRS'
+ In the top level `Makefile' only, `config-ml.in' will set this to
+ the list of multilib subdirectories. The default value should be
+ the empty string.
+
+`MULTISUBDIR'
+ `config-ml.in' will set this to the installed subdirectory name to
+ use for this subdirectory, with a leading `/'. The default value
+ shold be the empty string.
+
+`MULTIDO'
+`MULTICLEAN'
+ In the top level `Makefile' only, `config-ml.in' will set these
+ variables to commands to use when doing a recursive make. These
+ variables should both default to the string `true', so that by
+ default nothing happens.
+
+ All references to the parent of the source directory should use the
+variable `MULTISRCTOP'. Instead of writing `$(srcdir)/..', you must
+write `$(srcdir)/$(MULTISRCTOP)..'.
+
+ Similarly, references to the parent of the object directory should
+use the variable `MULTIBUILDTOP'.
+
+ In the installation target, the libraries should be installed in the
+subdirectory `MULTISUBDIR'. Instead of installing
+`$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'.
+
+ The `config-ml.in' script also modifies the top level `Makefile' to
+add `multi-do' and `multi-clean' targets which are used when building
+multilibs.
+
+ The default target of the `Makefile' should include the following
+command:
+ @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
+ This assumes that `$(FLAGS_TO_PASS)' is defined as a set of
+variables to pass to a recursive invocation of `make'. This will build
+all the multilibs. Note that the default value of `MULTIDO' is `true',
+so by default this command will do nothing. It will only do something
+in the top level `Makefile' if multilibs were enabled.
+
+ The `install' target of the `Makefile' should include the following
+command:
+ @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
+
+ In general, any operation, other than clean, which should be
+performed on all the multilibs should use a `$(MULTIDO)' line, setting
+the variable `DO' to the target of each recursive call to `make'.
+
+ The `clean' targets (`clean', `mostlyclean', etc.) should use
+`$(MULTICLEAN)'. For example, the `clean' target should do this:
+ @$(MULTICLEAN) DO=clean multi-clean
+
+
+File: configure.info, Node: FAQ, Next: Index, Prev: Multilibs, Up: Top
+
+9 Frequently Asked Questions
+****************************
+
+Which do I run first, `autoconf' or `automake'?
+ Except when you first add autoconf or automake support to a
+ package, you shouldn't run either by hand. Instead, configure
+ with the `--enable-maintainer-mode' option, and let `make' take
+ care of it.
+
+`autoconf' says something about undefined macros.
+ This means that you have macros in your `configure.in' which are
+ not defined by `autoconf'. You may be using an old version of
+ `autoconf'; try building and installing a newer one. Make sure the
+ newly installled `autoconf' is first on your `PATH'. Also, see
+ the next question.
+
+My `configure' script has stuff like `CY_GNU_GETTEXT' in it.
+ This means that you have macros in your `configure.in' which should
+ be defined in your `aclocal.m4' file, but aren't. This usually
+ means that `aclocal' was not able to appropriate definitions of the
+ macros. Make sure that you have installed all the packages you
+ need. In particular, make sure that you have installed libtool
+ (this is where `AM_PROG_LIBTOOL' is defined) and gettext (this is
+ where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version
+ of gettext).
+
+My `Makefile' has `@' characters in it.
+ This may mean that you tried to use an autoconf substitution in
+ your `Makefile.in' without adding the appropriate `AC_SUBST' call
+ to your `configure' script. Or it may just mean that you need to
+ rebuild `Makefile' in your build directory. To rebuild `Makefile'
+ from `Makefile.in', run the shell script `config.status' with no
+ arguments. If you need to force `configure' to run again, first
+ run `config.status --recheck'. These runs are normally done
+ automatically by `Makefile' targets, but if your `Makefile' has
+ gotten messed up you'll need to help them along.
+
+Why do I have to run both `config.status --recheck' and `config.status'?
+ Normally, you don't; they will be run automatically by `Makefile'
+ targets. If you do need to run them, use `config.status --recheck'
+ to run the `configure' script again with the same arguments as the
+ first time you ran it. Use `config.status' (with no arguments) to
+ regenerate all files (`Makefile', `config.h', etc.) based on the
+ results of the configure script. The two cases are separate
+ because it isn't always necessary to regenerate all the files
+ after running `config.status --recheck'. The `Makefile' targets
+ generated by automake will use the environment variables
+ `CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as
+ they are needed.
+
+What is the Cygnus tree?
+ The Cygnus tree is used for various packages including gdb, the GNU
+ binutils, and egcs. It is also, of course, used for Cygnus
+ releases. It is the build system which was developed at Cygnus,
+ using the Cygnus configure script. It permits building many
+ different packages with a single configure and make. The
+ configure scripts in the tree are being converted to autoconf, but
+ the general build structure remains intact.
+
+Why do I have to keep rebuilding and reinstalling the tools?
+ I know, it's a pain. Unfortunately, there are bugs in the tools
+ themselves which need to be fixed, and each time that happens
+ everybody who uses the tools need to reinstall new versions of
+ them. I don't know if there is going to be a clever fix until the
+ tools stabilize.
+
+Why not just have a Cygnus tree `make' target to update the tools?
+ The tools unfortunately need to be installed before they can be
+ used. That means that they must be built using an appropriate
+ prefix, and it seems unwise to assume that every configuration
+ uses an appropriate prefix. It might be possible to make them
+ work in place, or it might be possible to install them in some
+ subdirectory; so far these approaches have not been implemented.
+
+
+File: configure.info, Node: Index, Prev: FAQ, Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* --build option: Build and Host Options.
+ (line 9)
+* --host option: Build and Host Options.
+ (line 14)
+* --target option: Specifying the Target.
+ (line 10)
+* _GNU_SOURCE: Write configure.in. (line 134)
+* AC_CANONICAL_HOST: Using the Host Type. (line 10)
+* AC_CANONICAL_SYSTEM: Using the Target Type.
+ (line 6)
+* AC_CONFIG_HEADER: Write configure.in. (line 66)
+* AC_EXEEXT: Write configure.in. (line 86)
+* AC_INIT: Write configure.in. (line 38)
+* AC_OUTPUT: Write configure.in. (line 142)
+* AC_PREREQ: Write configure.in. (line 42)
+* AC_PROG_CC: Write configure.in. (line 103)
+* AC_PROG_CXX: Write configure.in. (line 117)
+* acconfig.h: Written Developer Files.
+ (line 27)
+* acconfig.h, writing: Write acconfig.h. (line 6)
+* acinclude.m4: Written Developer Files.
+ (line 37)
+* aclocal.m4: Generated Developer Files.
+ (line 33)
+* AM_CONFIG_HEADER: Write configure.in. (line 53)
+* AM_DISABLE_SHARED: Write configure.in. (line 127)
+* AM_EXEEXT: Write configure.in. (line 86)
+* AM_INIT_AUTOMAKE: Write configure.in. (line 48)
+* AM_MAINTAINER_MODE: Write configure.in. (line 70)
+* AM_PROG_LIBTOOL: Write configure.in. (line 122)
+* AM_PROG_LIBTOOL in configure: FAQ. (line 19)
+* build option: Build and Host Options.
+ (line 9)
+* building with a cross compiler: Canadian Cross. (line 6)
+* canadian cross: Canadian Cross. (line 6)
+* canadian cross in configure: CCross in Configure. (line 6)
+* canadian cross in cygnus tree: CCross in Cygnus Tree.
+ (line 6)
+* canadian cross in makefile: CCross in Make. (line 6)
+* canadian cross, configuring: Build and Host Options.
+ (line 6)
+* canonical system names: Configuration Names. (line 6)
+* config.cache: Build Files Description.
+ (line 28)
+* config.h: Build Files Description.
+ (line 23)
+* config.h.in: Generated Developer Files.
+ (line 45)
+* config.in: Generated Developer Files.
+ (line 45)
+* config.status: Build Files Description.
+ (line 9)
+* config.status --recheck: FAQ. (line 40)
+* configuration names: Configuration Names. (line 6)
+* configuration triplets: Configuration Names. (line 6)
+* configure: Generated Developer Files.
+ (line 21)
+* configure build system: Build and Host Options.
+ (line 9)
+* configure host: Build and Host Options.
+ (line 14)
+* configure target: Specifying the Target.
+ (line 10)
+* configure.in: Written Developer Files.
+ (line 9)
+* configure.in, writing: Write configure.in. (line 6)
+* configuring a canadian cross: Build and Host Options.
+ (line 6)
+* cross compiler: Cross Compilation Concepts.
+ (line 6)
+* cross compiler, building with: Canadian Cross. (line 6)
+* cross tools: Cross Compilation Tools.
+ (line 6)
+* CY_GNU_GETTEXT in configure: FAQ. (line 19)
+* cygnus configure: Cygnus Configure. (line 6)
+* goals: Goals. (line 6)
+* history: History. (line 6)
+* host names: Configuration Names. (line 6)
+* host option: Build and Host Options.
+ (line 14)
+* host system: Host and Target. (line 6)
+* host triplets: Configuration Names. (line 6)
+* HOST_CC: CCross in Make. (line 27)
+* libg++ configure: Cygnus Configure in C++ Libraries.
+ (line 6)
+* libio configure: Cygnus Configure in C++ Libraries.
+ (line 6)
+* libstdc++ configure: Cygnus Configure in C++ Libraries.
+ (line 6)
+* Makefile: Build Files Description.
+ (line 18)
+* Makefile, garbage characters: FAQ. (line 29)
+* Makefile.am: Written Developer Files.
+ (line 18)
+* Makefile.am, writing: Write Makefile.am. (line 6)
+* Makefile.in: Generated Developer Files.
+ (line 26)
+* multilibs: Multilibs. (line 6)
+* stamp-h: Build Files Description.
+ (line 41)
+* stamp-h.in: Generated Developer Files.
+ (line 54)
+* system names: Configuration Names. (line 6)
+* system types: Configuration Names. (line 6)
+* target option: Specifying the Target.
+ (line 10)
+* target system: Host and Target. (line 6)
+* triplets: Configuration Names. (line 6)
+* undefined macros: FAQ. (line 12)
+
+
+
+Tag Table:
+Node: Top971
+Node: Introduction1499
+Node: Goals2581
+Node: Tools3305
+Node: History4299
+Node: Building7297
+Node: Getting Started10560
+Node: Write configure.in11073
+Node: Write Makefile.am18324
+Node: Write acconfig.h21501
+Node: Generate files23038
+Node: Getting Started Example25004
+Node: Getting Started Example 125759
+Node: Getting Started Example 227680
+Node: Getting Started Example 330675
+Node: Generate Files in Example33039
+Node: Files34129
+Node: Developer Files34740
+Node: Developer Files Picture35120
+Node: Written Developer Files36408
+Node: Generated Developer Files38960
+Node: Build Files42104
+Node: Build Files Picture42765
+Node: Build Files Description43529
+Node: Support Files45535
+Node: Configuration Names48417
+Node: Configuration Name Definition48917
+Node: Using Configuration Names51240
+Node: Cross Compilation Tools53210
+Node: Cross Compilation Concepts53901
+Node: Host and Target54869
+Node: Using the Host Type56370
+Node: Specifying the Target57719
+Node: Using the Target Type58508
+Node: Cross Tools in the Cygnus Tree61939
+Node: Host and Target Libraries62996
+Node: Target Library Configure Scripts66745
+Node: Make Targets in Cygnus Tree69837
+Node: Target libiberty71185
+Node: Canadian Cross72572
+Node: Canadian Cross Example73413
+Node: Canadian Cross Concepts74532
+Node: Build Cross Host Tools76044
+Node: Build and Host Options76996
+Node: CCross not in Cygnus Tree78782
+Node: CCross in Cygnus Tree79760
+Node: Standard Cygnus CCross80181
+Node: Cross Cygnus CCross81545
+Node: Supporting Canadian Cross84345
+Node: CCross in Configure84960
+Node: CCross in Make88128
+Node: Cygnus Configure89731
+Node: Cygnus Configure Basics90566
+Node: Cygnus Configure in C++ Libraries95244
+Node: Multilibs96251
+Node: Multilibs in gcc97296
+Node: Multilibs in Target Libraries98374
+Node: FAQ102565
+Node: Index106665
+
+End Tag Table
diff --git a/etc/standards.info b/etc/standards.info
new file mode 100644
index 00000000000..69b594fd5b2
--- /dev/null
+++ b/etc/standards.info
@@ -0,0 +1,5576 @@
+This is standards.info, produced by makeinfo version 4.8 from
+./standards.texi.
+
+INFO-DIR-SECTION GNU organization
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+
+ The GNU coding standards, last updated July 22, 2007.
+
+ Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+
+File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
+
+Version
+*******
+
+The GNU coding standards, last updated July 22, 2007.
+
+ Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+* Menu:
+
+* Preface:: About the GNU Coding Standards.
+* Legal Issues:: Keeping free software free.
+* Design Advice:: General program design.
+* Program Behavior:: Program behavior for all programs
+* Writing C:: Making the best use of C.
+* Documentation:: Documenting programs.
+* Managing Releases:: The release process.
+* References:: Mentioning non-free software or documentation.
+* GNU Free Documentation License:: Copying and sharing this manual.
+* Index::
+
+
+File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
+
+1 About the GNU Coding Standards
+********************************
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to writing portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+ This release of the GNU Coding Standards was last updated July 22,
+2007.
+
+ If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version. You can get the GNU Coding
+Standards from the GNU web server in many different formats, including
+the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
+`http://www.gnu.org/prep/standards/'.
+
+ Corrections or suggestions for this document should be sent to
+<bug-standards@gnu.org>. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the `standards.texi' or `make-stds.texi' files, but if you
+don't have those files, please mail your suggestion anyway.
+
+ These standards cover the minimum of what is important when writing a
+GNU package. Likely, the need for additional standards will come up.
+Sometimes, you might suggest that such standards be added to this
+document. If you think your standards would be generally useful, please
+do suggest them.
+
+ You should also set standards for your package on many questions not
+addressed or not firmly specified here. The most important point is to
+be self-consistent--try to stick to the conventions you pick, and try
+to document them as much as possible. That way, your program will be
+more maintainable by others.
+
+ The GNU Hello program serves as an example of how to follow the GNU
+coding standards for a trivial program.
+`http://www.gnu.org/software/hello/hello.html'.
+
+
+File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
+
+2 Keeping Free Software Free
+****************************
+
+This chapter discusses how you can make sure that GNU software avoids
+legal difficulties, and other related issues.
+
+* Menu:
+
+* Reading Non-Free Code:: Referring to proprietary programs.
+* Contributions:: Accepting contributions.
+* Trademarks:: How we deal with trademark issues.
+
+
+File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
+
+2.1 Referring to Proprietary Programs
+=====================================
+
+Don't in any circumstances refer to Unix source code for or during your
+work on GNU! (Or to any other proprietary programs.)
+
+ If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+ For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different. You could keep the entire input file in memory and scan it
+there instead of using stdio. Use a smarter algorithm discovered more
+recently than the Unix program. Eliminate use of temporary files. Do
+it in one pass instead of two (we did this in the assembler).
+
+ Or, on the contrary, emphasize simplicity instead of speed. For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+ Or go for generality. For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead. Make sure your program handles NULs and
+other funny characters in the input files. Add a programming language
+for extensibility and write part of the program in that language.
+
+ Or turn some parts of the program into independently usable
+libraries. Or use a simple garbage collector instead of tracking
+precisely when to free memory, or use a new GNU facility such as
+obstacks.
+
+
+File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
+
+2.2 Accepting Contributions
+===========================
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it--just as we asked you to
+sign papers initially. _Each_ person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+ So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers. Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+ This applies both before you release the program and afterward. If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+ This also applies to comments and documentation files. For copyright
+law, comments and code are just text. Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+ We know it is frustrating to ask for legal papers; it's frustrating
+for us as well. But if you don't wait, you are going out on a limb--for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+ You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes. Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use. For example, if someone sent you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+ The very worst thing is if you forget to tell us about the other
+contributor. We could be very embarrassed in court some day as a
+result.
+
+ We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy. It is also available
+online for your perusal: `http://www.gnu.org/prep/maintain/'.
+
+
+File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
+
+2.3 Trademarks
+==============
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+ Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, and
+there is no legal requirement for them, so we don't use them.
+
+ What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might reasonably understand as
+naming or labeling our own programs or activities. For example, since
+"Objective C" is (or at least was) a trademark, we made sure to say
+that we provide a "compiler for the Objective C language" rather than
+an "Objective C compiler". The latter would have been meant as a
+shorter way of saying the former, but it does not explicitly state the
+relationship, so it could be misinterpreted as using "Objective C" as a
+label for the compiler rather than for the language.
+
+ Please don't use "win" as an abbreviation for Microsoft Windows in
+GNU software or documentation. In hacker terminology, calling
+something a "win" is a form of praise. If you wish to praise Microsoft
+Windows when speaking on your own, by all means do so, but not in GNU
+software. Usually we write the name "Windows" in full, but when
+brevity is very important (as in file names and sometimes symbol
+names), we abbreviate it to "w". For instance, the files and functions
+in Emacs that deal with Windows start with `w32'.
+
+
+File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
+
+3 General Program Design
+************************
+
+This chapter discusses some of the issues you should take into account
+when designing your program.
+
+* Menu:
+
+* Source Language:: Which languages to use.
+* Compatibility:: Compatibility with other implementations.
+* Using Extensions:: Using non-standard features.
+* Standard C:: Using standard C features.
+* Conditional Compilation:: Compiling code only if a conditional is true.
+
+
+File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
+
+3.1 Which Languages to Use
+==========================
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language is like
+using a non-standard feature: it will cause trouble for users. Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program. For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+ C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+ So in general it is much better to use C, rather than the comparable
+alternatives.
+
+ But there are two exceptions to that conclusion:
+
+ * It is no problem to use another language to write a tool
+ specifically intended for use with that language. That is because
+ the only people who want to build the tool will be those who have
+ installed the other language anyway.
+
+ * If an application is of interest only to a narrow part of the
+ community, then the question of which language it is written in
+ has less effect on other people, so you may as well please
+ yourself.
+
+ Many programs are designed to be extensible: they include an
+interpreter for a language that is higher level than C. Often much of
+the program is written in that language, too. The Emacs editor
+pioneered this technique.
+
+ The standard extensibility interpreter for GNU software is GUILE
+(`http://www.gnu.org/software/guile/'), which implements the language
+Scheme (an especially clean and simple dialect of Lisp). We don't
+reject programs written in other "scripting languages" such as Perl and
+Python, but using GUILE is very important for the overall consistency
+of the GNU system.
+
+
+File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
+
+3.2 Compatibility with Other Implementations
+============================================
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with Standard C if Standard C specifies their behavior, and
+upward compatible with POSIX if POSIX specifies their behavior.
+
+ When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+ Standard C and POSIX prohibit many kinds of extensions. Feel free
+to make the extensions anyway, and include a `--ansi', `--posix', or
+`--compatible' option to turn them off. However, if the extension has
+a significant chance of breaking any real programs or scripts, then it
+is not really upward compatible. So you should try to redesign its
+interface to make it upward compatible.
+
+ Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable `POSIXLY_CORRECT' is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
+ When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better. (For example,
+`vi' is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free `vi' clone, so we offer it.)
+
+ Additional useful features are welcome regardless of whether there
+is any precedent for them.
+
+
+File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
+
+3.3 Using Non-standard Features
+===============================
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities. Whether to use these
+extensions in implementing your program is a difficult question.
+
+ On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program unless
+the other GNU tools are available. This might cause the program to
+work on fewer kinds of machines.
+
+ With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a "keyword" `INLINE' and
+define that as a macro to expand into either `inline' or nothing,
+depending on the compiler.
+
+ In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+ An exception to this rule are the large, established programs (such
+as Emacs) which run on a great variety of systems. Using GNU
+extensions in such programs would make many users unhappy, so we don't
+do that.
+
+ Another exception is for programs that are used as part of
+compilation: anything that must be compiled with other compilers in
+order to bootstrap the GNU compilation facilities. If these require
+the GNU compiler, then no one can compile them without having them
+installed already. That would be extremely troublesome in certain
+cases.
+
+
+File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
+
+3.4 Standard C and Pre-Standard C
+=================================
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs. There is one exception: do not ever use the
+"trigraph" feature of Standard C.
+
+ 1999 Standard C is not widespread yet, so please do not require its
+features in programs. It is ok to use its features if they are present.
+
+ However, it is easy to support pre-standard compilers in most
+programs, so if you know how to do that, feel free. If a program you
+are maintaining has such support, you should try to keep it working.
+
+ To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+ int
+ foo (int x, int y)
+ ...
+
+write the definition in pre-standard style like this,
+
+ int
+ foo (x, y)
+ int x, y;
+ ...
+
+and use a separate declaration to specify the argument prototype:
+
+ int foo (int, int);
+
+ You need such a declaration anyway, in a header file, to get the
+benefit of prototypes in all the files where the function is called.
+And once you have the declaration, you normally lose nothing by writing
+the function definition in the pre-standard style.
+
+ This technique does not work for integer types narrower than `int'.
+If you think of an argument as being of a type narrower than `int',
+declare it as `int' instead.
+
+ There are a few special cases where this technique is hard to use.
+For example, if a function argument needs to hold the system type
+`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
+some machines; but you cannot use `int' instead, because `dev_t' is
+wider than `int' on some machines. There is no type you can safely use
+on all machines in a non-standard definition. The only way to support
+non-standard C and pass such an argument is to check the width of
+`dev_t' using Autoconf and choose the argument type accordingly. This
+may not be worth the trouble.
+
+ In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+ /* Declare the prototype for a general external function. */
+ #if defined (__STDC__) || defined (WINDOWSNT)
+ #define P_(proto) proto
+ #else
+ #define P_(proto) ()
+ #endif
+
+
+File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
+
+3.5 Conditional Compilation
+===========================
+
+When supporting configuration options already known when building your
+program we prefer using `if (... )' over conditional compilation, as in
+the former case the compiler is able to perform more extensive checking
+of all possible code paths.
+
+ For example, please write
+
+ if (HAS_FOO)
+ ...
+ else
+ ...
+
+instead of:
+
+ #ifdef HAS_FOO
+ ...
+ #else
+ ...
+ #endif
+
+ A modern compiler such as GCC will generate exactly the same code in
+both cases, and we have been using similar techniques with good success
+in several projects. Of course, the former method assumes that
+`HAS_FOO' is defined as either 0 or 1.
+
+ While this is not a silver bullet solving all portability problems,
+and is not always appropriate, following this policy would have saved
+GCC developers many hours, or even days, per year.
+
+ In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
+which cannot be simply used in `if( ...)' statements, there is an easy
+workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
+in the following example:
+
+ #ifdef REVERSIBLE_CC_MODE
+ #define HAS_REVERSIBLE_CC_MODE 1
+ #else
+ #define HAS_REVERSIBLE_CC_MODE 0
+ #endif
+
+
+File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
+
+4 Program Behavior for All Programs
+***********************************
+
+This chapter describes conventions for writing robust software. It
+also describes general standards for error messages, the command line
+interface, and how libraries should behave.
+
+* Menu:
+
+* Non-GNU Standards:: We consider standards such as POSIX;
+ we don't "obey" them.
+* Semantics:: Writing robust programs.
+* Libraries:: Library behavior.
+* Errors:: Formatting error messages.
+* User Interfaces:: Standards about interfaces generally.
+* Graphical Interfaces:: Standards for graphical interfaces.
+* Command-Line Interfaces:: Standards for command line interfaces.
+* Option Table:: Table of long options.
+* Memory Usage:: When and how to care about memory needs.
+* File Usage:: Which files to use, and where.
+
+
+File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior
+
+4.1 Non-GNU Standards
+=====================
+
+The GNU Project regards standards published by other organizations as
+suggestions, not orders. We consider those standards, but we do not
+"obey" them. In developing a GNU program, you should implement an
+outside standard's specifications when that makes the GNU system better
+overall in an objective sense. When it doesn't, you shouldn't.
+
+ In most cases, following published standards is convenient for
+users--it means that their programs or scripts will work more portably.
+For instance, GCC implements nearly all the features of Standard C as
+specified by that standard. C program developers would be unhappy if
+it did not. And GNU utilities mostly follow specifications of POSIX.2;
+shell script writers and users would be unhappy if our programs were
+incompatible.
+
+ But we do not follow either of these specifications rigidly, and
+there are specific points on which we decided not to follow them, so as
+to make the GNU system better for users.
+
+ For instance, Standard C says that nearly all extensions to C are
+prohibited. How silly! GCC implements many extensions, some of which
+were later adopted as part of the standard. If you want these
+constructs to give an error message as "required" by the standard, you
+must specify `--pedantic', which was implemented only so that we can
+say "GCC is a 100% implementation of the standard," not because there
+is any reason to actually use it.
+
+ POSIX.2 specifies that `df' and `du' must output sizes by default in
+units of 512 bytes. What users want is units of 1k, so that is what we
+do by default. If you want the ridiculous behavior "required" by
+POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
+was originally going to be named `POSIX_ME_HARDER').
+
+ GNU utilities also depart from the letter of the POSIX.2
+specification when they support long-named command-line options, and
+intermixing options with ordinary arguments. This minor
+incompatibility with POSIX is never a problem in practice, and it is
+very useful.
+
+ In particular, don't reject a new feature, or remove an old one,
+merely because a standard says it is "forbidden" or "deprecated."
+
+
+File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior
+
+4.2 Writing Robust Programs
+===========================
+
+Avoid arbitrary limits on the length or number of _any_ data structure,
+including file names, lines, files, and symbols, by allocating all data
+structures dynamically. In most Unix utilities, "long lines are
+silently truncated". This is not acceptable in a GNU utility.
+
+ Utilities reading files should not drop NUL characters, or any other
+nonprinting characters _including those with codes above 0177_. The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of terminals or printers that can't handle
+those characters. Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters,
+using encodings such as UTF-8 and others.
+
+ Check every system call for an error return, unless you know you
+wish to ignore errors. Include the system error text (from `perror' or
+equivalent) in _every_ error message resulting from a failing system
+call, as well as the name of the file if any and the name of the
+utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
+
+ Check every call to `malloc' or `realloc' to see if it returned
+zero. Check `realloc' even if you are making the block smaller; in a
+system that rounds block sizes to a power of 2, `realloc' may get a
+different block if you ask for less space.
+
+ In Unix, `realloc' can destroy the storage block if it returns zero.
+GNU `realloc' does not have this bug: if it fails, the original block
+is unchanged. Feel free to assume the bug is fixed. If you wish to
+run your program on Unix, and wish to avoid lossage in this case, you
+can use the GNU `malloc'.
+
+ You must expect `free' to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling `free'.
+
+ If `malloc' fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop. This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+ Use `getopt_long' to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+ When static storage is to be written in during program execution, use
+explicit C code to initialize it. Reserve C initialized declarations
+for data that will not be changed.
+
+ Try to avoid low-level interfaces to obscure Unix data structures
+(such as file directories, utmp, or the layout of kernel memory), since
+these are less likely to work compatibly. If you need to find all the
+files in a directory, use `readdir' or some other high-level interface.
+These are supported compatibly by GNU.
+
+ The preferred signal handling facilities are the BSD variant of
+`signal', and the POSIX `sigaction' function; the alternative USG
+`signal' interface is an inferior design.
+
+ Nowadays, using the POSIX signal functions may be the easiest way to
+make a program portable. If you use `signal', then on GNU/Linux
+systems running GNU libc version 1, you should include `bsd/signal.h'
+instead of `signal.h', so as to get BSD behavior. It is up to you
+whether to support systems where `signal' has only the USG behavior, or
+give up on them.
+
+ In error checks that detect "impossible" conditions, just abort.
+There is usually no point in printing any message. These checks
+indicate the existence of bugs. Whoever wants to fix the bugs will have
+to read the source code and run a debugger. So explain the problem with
+comments in the source. The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+ Do not use a count of errors as the exit status for a program.
+_That does not work_, because exit status values are limited to 8 bits
+(0 through 255). A single run of the program might have 256 errors; if
+you try to return 256 as the exit status, the parent process will see 0
+as the status, and it will appear that the program succeeded.
+
+ If you make temporary files, check the `TMPDIR' environment
+variable; if that variable is defined, use the specified directory
+instead of `/tmp'.
+
+ In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories. In C, you can
+avoid this problem by creating temporary files in this manner:
+
+ fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+
+or by using the `mkstemps' function from libiberty.
+
+ In bash, use `set -C' to avoid this problem.
+
+
+File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
+
+4.3 Library Behavior
+====================
+
+Try to make library functions reentrant. If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of `malloc' itself.
+
+ Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+ Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this prefix.
+In addition, there should only be one of these in any given library
+member. This usually means putting each one in a separate source file.
+
+ An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+ External symbols that are not documented entry points for the user
+should have names beginning with `_'. The `_' should be followed by
+the chosen name prefix for the library, to prevent collisions with
+other libraries. These can go in the same files with user entry points
+if you like.
+
+ Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+
+File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
+
+4.4 Formatting Error Messages
+=============================
+
+Error messages from compilers should look like this:
+
+ SOURCE-FILE-NAME:LINENO: MESSAGE
+
+If you want to mention the column number, use one of these formats:
+
+ SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+ SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
+
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line. (Both
+of these conventions are chosen for compatibility.) Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
+ The error message can also give both the starting and ending
+positions of the erroneous text. There are several formats so that you
+can avoid redundant information such as a duplicate line number. Here
+are the possible formats:
+
+ SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
+ SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
+ SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
+
+When an error is spread over several files, you can use this format:
+
+ FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
+
+ Error messages from other noninteractive programs should look like
+this:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
+
+when there is an appropriate source file, or like this:
+
+ PROGRAM: MESSAGE
+
+when there is no relevant source file.
+
+ If you want to mention the column number, use this format:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+ In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message. The place to indicate which program is running is in the
+prompt or with the screen layout. (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+ The string MESSAGE should not begin with a capital letter when it
+follows a program name and/or file name, because that isn't the
+beginning of a sentence. (The sentence conceptually starts at the
+beginning of the line.) Also, it should not end with a period.
+
+ Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter. But they should not
+end with a period.
+
+
+File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
+
+4.5 Standards for Interfaces Generally
+======================================
+
+Please don't make the behavior of a utility depend on the name used to
+invoke it. It is useful sometimes to make a link to a utility with a
+different name, and that should not change what it does.
+
+ Instead, use a run time option or a compilation switch or both to
+select among the alternate behaviors.
+
+ Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then. (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+ If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+ Compatibility requires certain programs to depend on the type of
+output device. It would be disastrous if `ls' or `sh' did not do so in
+the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a `dir' program much like
+`ls' except that its default output format is always multi-column
+format.
+
+
+File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
+
+4.6 Standards for Graphical Interfaces
+======================================
+
+When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK+ toolkit unless the
+functionality specifically requires some alternative (for example,
+"displaying jpeg images while in console mode").
+
+ In addition, please provide a command-line interface to control the
+functionality. (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.) This is so
+that the same jobs can be done from scripts.
+
+ Please also consider providing a CORBA interface (for use from
+GNOME), a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console mode).
+Once you are doing the work to provide the functionality and the
+graphical interface, these won't be much extra work.
+
+
+File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
+
+4.7 Standards for Command Line Interfaces
+=========================================
+
+It is a good idea to follow the POSIX guidelines for the command-line
+options of a program. The easiest way to do this is to use `getopt' to
+parse them. Note that the GNU version of `getopt' will normally permit
+options anywhere among the arguments unless the special argument `--'
+is used. This is not what POSIX specifies; it is a GNU extension.
+
+ Please define long-named options that are equivalent to the
+single-letter Unix-style options. We hope to make GNU more user
+friendly this way. This is easy to do with the GNU function
+`getopt_long'.
+
+ One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the "verbose" option of any GNU program which has one, to be
+spelled precisely `--verbose'. To achieve this uniformity, look at the
+table of common long-option names when you choose the option names for
+your program (*note Option Table::).
+
+ It is usually a good idea for file names given as ordinary arguments
+to be input files only; any output files would be specified using
+options (preferably `-o' or `--output'). Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it. This will lead to more consistency
+among GNU utilities, and fewer idiosyncrasies for users to remember.
+
+ All programs should support two standard options: `--version' and
+`--help'. CGI programs should accept these as command-line options,
+and also if given as the `PATH_INFO'; for instance, visiting
+`http://example.org/p.cgi/--help' in a browser should output the same
+information as invoking `p.cgi --help' from the command line.
+
+* Menu:
+
+* --version:: The standard output for --version.
+* --help:: The standard output for --help.
+
+
+File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces
+
+4.7.1 `--version'
+-----------------
+
+The standard `--version' option should direct the program to print
+information about its name, version, origin and legal status, all on
+standard output, and then exit successfully. Other options and
+arguments should be ignored once this is seen, and the program should
+not perform its normal function.
+
+ The first line is meant to be easy for a program to parse; the
+version number proper starts after the last space. In addition, it
+contains the canonical name for this program, in this format:
+
+ GNU Emacs 19.30
+
+The program's name should be a constant string; _don't_ compute it from
+`argv[0]'. The idea is to state the standard or canonical name for the
+program, not its file name. There are other ways to find out the
+precise file name where a command is found in `PATH'.
+
+ If the program is a subsidiary part of a larger package, mention the
+package name in parentheses, like this:
+
+ emacsserver (GNU Emacs) 19.30
+
+If the package has a version number which is different from this
+program's version number, you can mention the package version number
+just before the close-parenthesis.
+
+ If you _need_ to mention the version numbers of libraries which are
+distributed separately from the package which contains this program,
+you can do so by printing an additional line of version info for each
+library you want to mention. Use the same format for these lines as for
+the first line.
+
+ Please do not mention all of the libraries that the program uses
+"just for completeness"--that would produce a lot of unhelpful clutter.
+Please mention library version numbers only if you find in practice that
+they are very important to you in debugging.
+
+ The following line, after the version number line or lines, should
+be a copyright notice. If more than one copyright notice is called
+for, put each on a separate line.
+
+ Next should follow a line stating the license, preferably using one
+of abbrevations below, and a brief statement that the program is free
+software, and that users are free to copy and change it. Also mention
+that there is no warranty, to the extent permitted by law. See
+recommended wording below.
+
+ It is ok to finish the output with a list of the major authors of the
+program, as a way of giving credit.
+
+ Here's an example of output that follows these rules:
+
+ GNU hello 2.3
+ Copyright (C) 2007 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+ This is free software: you are free to change and redistribute it.
+ There is NO WARRANTY, to the extent permitted by law.
+
+ You should adapt this to your program, of course, filling in the
+proper year, copyright holder, name of program, and the references to
+distribution terms, and changing the rest of the wording as necessary.
+
+ This copyright notice only needs to mention the most recent year in
+which changes were made--there's no need to list the years for previous
+versions' changes. You don't have to mention the name of the program in
+these notices, if that is inconvenient, since it appeared in the first
+line. (The rules are different for copyright notices in source files;
+*note Copyright Notices: (maintain)Copyright Notices.)
+
+ Translations of the above lines must preserve the validity of the
+copyright notices (*note Internationalization::). If the translation's
+character set supports it, the `(C)' should be replaced with the
+copyright symbol, as follows:
+
+ (the official copyright symbol, which is the letter C in a circle);
+
+ Write the word "Copyright" exactly like that, in English. Do not
+translate it into another language. International treaties recognize
+the English word "Copyright"; translations into other languages do not
+have legal significance.
+
+ Finally, here is the table of our suggested license abbreviations.
+Any abbreviation can be followed by `vVERSION[+]', meaning that
+particular version, or later versions with the `+', as shown above.
+
+ In the case of exceptions for extra permissions with the GPL, we use
+`/' for a separator; the version number can follow the license
+abbreviation as usual, as in the examples below.
+
+GPL
+ GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
+
+LGPL
+ GNU Lesser General Public License,
+ `http://www.gnu.org/licenses/lgpl.html'.
+
+GPL/Guile
+ GNU GPL with the exception for Guile; for example, GPLv3+/Guile
+ means the GNU GPL version 3 or later, with the extra exception for
+ Guile.
+
+ GNU GPL with the exception for Ada.
+
+Apache
+ The Apache Software Foundation license,
+ `http://www.apache.org/licenses'.
+
+Artistic
+ The Artistic license used for Perl,
+ `http://www.perlfoundation.org/legal'.
+
+Expat
+ The Expat license, `http://www.jclark.com/xml/copying.txt'.
+
+MPL
+ The Mozilla Public License, `http://www.mozilla.org/MPL/'.
+
+OBSD
+ The original (4-clause) BSD license, incompatible with the GNU GPL
+ `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
+
+PHP
+ The license used for PHP, `http://www.php.net/license/'.
+
+public domain
+ The non-license that is being in the public domain,
+ `http://www.gnu.org/licenses/license-list.html#PublicDomain'.
+
+Python
+ The license for Python, `http://www.python.org/2.0.1/license.html'.
+
+RBSD
+ The revised (3-clause) BSD, compatible with the GNU GPL,
+ `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
+
+X11
+ The simple non-copyleft license used for most versions of the X
+ Window system, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
+
+Zlib
+ The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
+
+
+ More information about these licenses and many more are on the GNU
+licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
+
+
+File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces
+
+4.7.2 `--help'
+--------------
+
+The standard `--help' option should output brief documentation for how
+to invoke the program, on standard output, then exit successfully.
+Other options and arguments should be ignored once this is seen, and
+the program should not perform its normal function.
+
+ Near the end of the `--help' option's output there should be a line
+that says where to mail bug reports. It should have this format:
+
+ Report bugs to MAILING-ADDRESS.
+
+
+File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
+
+4.8 Table of Long Options
+=========================
+
+Here is a table of long options used by GNU programs. It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with. If you use names not already in the table,
+please send <bug-standards@gnu.org> a list of them, with their
+meanings, so we can update the table.
+
+`after-date'
+ `-N' in `tar'.
+
+`all'
+ `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
+
+`all-text'
+ `-a' in `diff'.
+
+`almost-all'
+ `-A' in `ls'.
+
+`append'
+ `-a' in `etags', `tee', `time'; `-r' in `tar'.
+
+`archive'
+ `-a' in `cp'.
+
+`archive-name'
+ `-n' in `shar'.
+
+`arglength'
+ `-l' in `m4'.
+
+`ascii'
+ `-a' in `diff'.
+
+`assign'
+ `-v' in `gawk'.
+
+`assume-new'
+ `-W' in Make.
+
+`assume-old'
+ `-o' in Make.
+
+`auto-check'
+ `-a' in `recode'.
+
+`auto-pager'
+ `-a' in `wdiff'.
+
+`auto-reference'
+ `-A' in `ptx'.
+
+`avoid-wraps'
+ `-n' in `wdiff'.
+
+`background'
+ For server programs, run in the background.
+
+`backward-search'
+ `-B' in `ctags'.
+
+`basename'
+ `-f' in `shar'.
+
+`batch'
+ Used in GDB.
+
+`baud'
+ Used in GDB.
+
+`before'
+ `-b' in `tac'.
+
+`binary'
+ `-b' in `cpio' and `diff'.
+
+`bits-per-code'
+ `-b' in `shar'.
+
+`block-size'
+ Used in `cpio' and `tar'.
+
+`blocks'
+ `-b' in `head' and `tail'.
+
+`break-file'
+ `-b' in `ptx'.
+
+`brief'
+ Used in various programs to make output shorter.
+
+`bytes'
+ `-c' in `head', `split', and `tail'.
+
+`c++'
+ `-C' in `etags'.
+
+`catenate'
+ `-A' in `tar'.
+
+`cd'
+ Used in various programs to specify the directory to use.
+
+`changes'
+ `-c' in `chgrp' and `chown'.
+
+`classify'
+ `-F' in `ls'.
+
+`colons'
+ `-c' in `recode'.
+
+`command'
+ `-c' in `su'; `-x' in GDB.
+
+`compare'
+ `-d' in `tar'.
+
+`compat'
+ Used in `gawk'.
+
+`compress'
+ `-Z' in `tar' and `shar'.
+
+`concatenate'
+ `-A' in `tar'.
+
+`confirmation'
+ `-w' in `tar'.
+
+`context'
+ Used in `diff'.
+
+`copyleft'
+ `-W copyleft' in `gawk'.
+
+`copyright'
+ `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
+
+`core'
+ Used in GDB.
+
+`count'
+ `-q' in `who'.
+
+`count-links'
+ `-l' in `du'.
+
+`create'
+ Used in `tar' and `cpio'.
+
+`cut-mark'
+ `-c' in `shar'.
+
+`cxref'
+ `-x' in `ctags'.
+
+`date'
+ `-d' in `touch'.
+
+`debug'
+ `-d' in Make and `m4'; `-t' in Bison.
+
+`define'
+ `-D' in `m4'.
+
+`defines'
+ `-d' in Bison and `ctags'.
+
+`delete'
+ `-D' in `tar'.
+
+`dereference'
+ `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
+
+`dereference-args'
+ `-D' in `du'.
+
+`device'
+ Specify an I/O device (special file name).
+
+`diacritics'
+ `-d' in `recode'.
+
+`dictionary-order'
+ `-d' in `look'.
+
+`diff'
+ `-d' in `tar'.
+
+`digits'
+ `-n' in `csplit'.
+
+`directory'
+ Specify the directory to use, in various programs. In `ls', it
+ means to show directories themselves rather than their contents.
+ In `rm' and `ln', it means to not treat links to directories
+ specially.
+
+`discard-all'
+ `-x' in `strip'.
+
+`discard-locals'
+ `-X' in `strip'.
+
+`dry-run'
+ `-n' in Make.
+
+`ed'
+ `-e' in `diff'.
+
+`elide-empty-files'
+ `-z' in `csplit'.
+
+`end-delete'
+ `-x' in `wdiff'.
+
+`end-insert'
+ `-z' in `wdiff'.
+
+`entire-new-file'
+ `-N' in `diff'.
+
+`environment-overrides'
+ `-e' in Make.
+
+`eof'
+ `-e' in `xargs'.
+
+`epoch'
+ Used in GDB.
+
+`error-limit'
+ Used in `makeinfo'.
+
+`error-output'
+ `-o' in `m4'.
+
+`escape'
+ `-b' in `ls'.
+
+`exclude-from'
+ `-X' in `tar'.
+
+`exec'
+ Used in GDB.
+
+`exit'
+ `-x' in `xargs'.
+
+`exit-0'
+ `-e' in `unshar'.
+
+`expand-tabs'
+ `-t' in `diff'.
+
+`expression'
+ `-e' in `sed'.
+
+`extern-only'
+ `-g' in `nm'.
+
+`extract'
+ `-i' in `cpio'; `-x' in `tar'.
+
+`faces'
+ `-f' in `finger'.
+
+`fast'
+ `-f' in `su'.
+
+`fatal-warnings'
+ `-E' in `m4'.
+
+`file'
+ `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
+ in `touch'.
+
+`field-separator'
+ `-F' in `gawk'.
+
+`file-prefix'
+ `-b' in Bison.
+
+`file-type'
+ `-F' in `ls'.
+
+`files-from'
+ `-T' in `tar'.
+
+`fill-column'
+ Used in `makeinfo'.
+
+`flag-truncation'
+ `-F' in `ptx'.
+
+`fixed-output-files'
+ `-y' in Bison.
+
+`follow'
+ `-f' in `tail'.
+
+`footnote-style'
+ Used in `makeinfo'.
+
+`force'
+ `-f' in `cp', `ln', `mv', and `rm'.
+
+`force-prefix'
+ `-F' in `shar'.
+
+`foreground'
+ For server programs, run in the foreground; in other words, don't
+ do anything special to run the server in the background.
+
+`format'
+ Used in `ls', `time', and `ptx'.
+
+`freeze-state'
+ `-F' in `m4'.
+
+`fullname'
+ Used in GDB.
+
+`gap-size'
+ `-g' in `ptx'.
+
+`get'
+ `-x' in `tar'.
+
+`graphic'
+ `-i' in `ul'.
+
+`graphics'
+ `-g' in `recode'.
+
+`group'
+ `-g' in `install'.
+
+`gzip'
+ `-z' in `tar' and `shar'.
+
+`hashsize'
+ `-H' in `m4'.
+
+`header'
+ `-h' in `objdump' and `recode'
+
+`heading'
+ `-H' in `who'.
+
+`help'
+ Used to ask for brief usage information.
+
+`here-delimiter'
+ `-d' in `shar'.
+
+`hide-control-chars'
+ `-q' in `ls'.
+
+`html'
+ In `makeinfo', output HTML.
+
+`idle'
+ `-u' in `who'.
+
+`ifdef'
+ `-D' in `diff'.
+
+`ignore'
+ `-I' in `ls'; `-x' in `recode'.
+
+`ignore-all-space'
+ `-w' in `diff'.
+
+`ignore-backups'
+ `-B' in `ls'.
+
+`ignore-blank-lines'
+ `-B' in `diff'.
+
+`ignore-case'
+ `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
+
+`ignore-errors'
+ `-i' in Make.
+
+`ignore-file'
+ `-i' in `ptx'.
+
+`ignore-indentation'
+ `-I' in `etags'.
+
+`ignore-init-file'
+ `-f' in Oleo.
+
+`ignore-interrupts'
+ `-i' in `tee'.
+
+`ignore-matching-lines'
+ `-I' in `diff'.
+
+`ignore-space-change'
+ `-b' in `diff'.
+
+`ignore-zeros'
+ `-i' in `tar'.
+
+`include'
+ `-i' in `etags'; `-I' in `m4'.
+
+`include-dir'
+ `-I' in Make.
+
+`incremental'
+ `-G' in `tar'.
+
+`info'
+ `-i', `-l', and `-m' in Finger.
+
+`init-file'
+ In some programs, specify the name of the file to read as the
+ user's init file.
+
+`initial'
+ `-i' in `expand'.
+
+`initial-tab'
+ `-T' in `diff'.
+
+`inode'
+ `-i' in `ls'.
+
+`interactive'
+ `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
+ `-w' in `tar'.
+
+`intermix-type'
+ `-p' in `shar'.
+
+`iso-8601'
+ Used in `date'
+
+`jobs'
+ `-j' in Make.
+
+`just-print'
+ `-n' in Make.
+
+`keep-going'
+ `-k' in Make.
+
+`keep-files'
+ `-k' in `csplit'.
+
+`kilobytes'
+ `-k' in `du' and `ls'.
+
+`language'
+ `-l' in `etags'.
+
+`less-mode'
+ `-l' in `wdiff'.
+
+`level-for-gzip'
+ `-g' in `shar'.
+
+`line-bytes'
+ `-C' in `split'.
+
+`lines'
+ Used in `split', `head', and `tail'.
+
+`link'
+ `-l' in `cpio'.
+
+`lint'
+`lint-old'
+ Used in `gawk'.
+
+`list'
+ `-t' in `cpio'; `-l' in `recode'.
+
+`list'
+ `-t' in `tar'.
+
+`literal'
+ `-N' in `ls'.
+
+`load-average'
+ `-l' in Make.
+
+`login'
+ Used in `su'.
+
+`machine'
+ Used in `uname'.
+
+`macro-name'
+ `-M' in `ptx'.
+
+`mail'
+ `-m' in `hello' and `uname'.
+
+`make-directories'
+ `-d' in `cpio'.
+
+`makefile'
+ `-f' in Make.
+
+`mapped'
+ Used in GDB.
+
+`max-args'
+ `-n' in `xargs'.
+
+`max-chars'
+ `-n' in `xargs'.
+
+`max-lines'
+ `-l' in `xargs'.
+
+`max-load'
+ `-l' in Make.
+
+`max-procs'
+ `-P' in `xargs'.
+
+`mesg'
+ `-T' in `who'.
+
+`message'
+ `-T' in `who'.
+
+`minimal'
+ `-d' in `diff'.
+
+`mixed-uuencode'
+ `-M' in `shar'.
+
+`mode'
+ `-m' in `install', `mkdir', and `mkfifo'.
+
+`modification-time'
+ `-m' in `tar'.
+
+`multi-volume'
+ `-M' in `tar'.
+
+`name-prefix'
+ `-a' in Bison.
+
+`nesting-limit'
+ `-L' in `m4'.
+
+`net-headers'
+ `-a' in `shar'.
+
+`new-file'
+ `-W' in Make.
+
+`no-builtin-rules'
+ `-r' in Make.
+
+`no-character-count'
+ `-w' in `shar'.
+
+`no-check-existing'
+ `-x' in `shar'.
+
+`no-common'
+ `-3' in `wdiff'.
+
+`no-create'
+ `-c' in `touch'.
+
+`no-defines'
+ `-D' in `etags'.
+
+`no-deleted'
+ `-1' in `wdiff'.
+
+`no-dereference'
+ `-d' in `cp'.
+
+`no-inserted'
+ `-2' in `wdiff'.
+
+`no-keep-going'
+ `-S' in Make.
+
+`no-lines'
+ `-l' in Bison.
+
+`no-piping'
+ `-P' in `shar'.
+
+`no-prof'
+ `-e' in `gprof'.
+
+`no-regex'
+ `-R' in `etags'.
+
+`no-sort'
+ `-p' in `nm'.
+
+`no-splash'
+ Don't print a startup splash screen.
+
+`no-split'
+ Used in `makeinfo'.
+
+`no-static'
+ `-a' in `gprof'.
+
+`no-time'
+ `-E' in `gprof'.
+
+`no-timestamp'
+ `-m' in `shar'.
+
+`no-validate'
+ Used in `makeinfo'.
+
+`no-wait'
+ Used in `emacsclient'.
+
+`no-warn'
+ Used in various programs to inhibit warnings.
+
+`node'
+ `-n' in `info'.
+
+`nodename'
+ `-n' in `uname'.
+
+`nonmatching'
+ `-f' in `cpio'.
+
+`nstuff'
+ `-n' in `objdump'.
+
+`null'
+ `-0' in `xargs'.
+
+`number'
+ `-n' in `cat'.
+
+`number-nonblank'
+ `-b' in `cat'.
+
+`numeric-sort'
+ `-n' in `nm'.
+
+`numeric-uid-gid'
+ `-n' in `cpio' and `ls'.
+
+`nx'
+ Used in GDB.
+
+`old-archive'
+ `-o' in `tar'.
+
+`old-file'
+ `-o' in Make.
+
+`one-file-system'
+ `-l' in `tar', `cp', and `du'.
+
+`only-file'
+ `-o' in `ptx'.
+
+`only-prof'
+ `-f' in `gprof'.
+
+`only-time'
+ `-F' in `gprof'.
+
+`options'
+ `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
+
+`output'
+ In various programs, specify the output file name.
+
+`output-prefix'
+ `-o' in `shar'.
+
+`override'
+ `-o' in `rm'.
+
+`overwrite'
+ `-c' in `unshar'.
+
+`owner'
+ `-o' in `install'.
+
+`paginate'
+ `-l' in `diff'.
+
+`paragraph-indent'
+ Used in `makeinfo'.
+
+`parents'
+ `-p' in `mkdir' and `rmdir'.
+
+`pass-all'
+ `-p' in `ul'.
+
+`pass-through'
+ `-p' in `cpio'.
+
+`port'
+ `-P' in `finger'.
+
+`portability'
+ `-c' in `cpio' and `tar'.
+
+`posix'
+ Used in `gawk'.
+
+`prefix-builtins'
+ `-P' in `m4'.
+
+`prefix'
+ `-f' in `csplit'.
+
+`preserve'
+ Used in `tar' and `cp'.
+
+`preserve-environment'
+ `-p' in `su'.
+
+`preserve-modification-time'
+ `-m' in `cpio'.
+
+`preserve-order'
+ `-s' in `tar'.
+
+`preserve-permissions'
+ `-p' in `tar'.
+
+`print'
+ `-l' in `diff'.
+
+`print-chars'
+ `-L' in `cmp'.
+
+`print-data-base'
+ `-p' in Make.
+
+`print-directory'
+ `-w' in Make.
+
+`print-file-name'
+ `-o' in `nm'.
+
+`print-symdefs'
+ `-s' in `nm'.
+
+`printer'
+ `-p' in `wdiff'.
+
+`prompt'
+ `-p' in `ed'.
+
+`proxy'
+ Specify an HTTP proxy.
+
+`query-user'
+ `-X' in `shar'.
+
+`question'
+ `-q' in Make.
+
+`quiet'
+ Used in many programs to inhibit the usual output. Every program
+ accepting `--quiet' should accept `--silent' as a synonym.
+
+`quiet-unshar'
+ `-Q' in `shar'
+
+`quote-name'
+ `-Q' in `ls'.
+
+`rcs'
+ `-n' in `diff'.
+
+`re-interval'
+ Used in `gawk'.
+
+`read-full-blocks'
+ `-B' in `tar'.
+
+`readnow'
+ Used in GDB.
+
+`recon'
+ `-n' in Make.
+
+`record-number'
+ `-R' in `tar'.
+
+`recursive'
+ Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
+
+`reference-limit'
+ Used in `makeinfo'.
+
+`references'
+ `-r' in `ptx'.
+
+`regex'
+ `-r' in `tac' and `etags'.
+
+`release'
+ `-r' in `uname'.
+
+`reload-state'
+ `-R' in `m4'.
+
+`relocation'
+ `-r' in `objdump'.
+
+`rename'
+ `-r' in `cpio'.
+
+`replace'
+ `-i' in `xargs'.
+
+`report-identical-files'
+ `-s' in `diff'.
+
+`reset-access-time'
+ `-a' in `cpio'.
+
+`reverse'
+ `-r' in `ls' and `nm'.
+
+`reversed-ed'
+ `-f' in `diff'.
+
+`right-side-defs'
+ `-R' in `ptx'.
+
+`same-order'
+ `-s' in `tar'.
+
+`same-permissions'
+ `-p' in `tar'.
+
+`save'
+ `-g' in `stty'.
+
+`se'
+ Used in GDB.
+
+`sentence-regexp'
+ `-S' in `ptx'.
+
+`separate-dirs'
+ `-S' in `du'.
+
+`separator'
+ `-s' in `tac'.
+
+`sequence'
+ Used by `recode' to chose files or pipes for sequencing passes.
+
+`shell'
+ `-s' in `su'.
+
+`show-all'
+ `-A' in `cat'.
+
+`show-c-function'
+ `-p' in `diff'.
+
+`show-ends'
+ `-E' in `cat'.
+
+`show-function-line'
+ `-F' in `diff'.
+
+`show-tabs'
+ `-T' in `cat'.
+
+`silent'
+ Used in many programs to inhibit the usual output. Every program
+ accepting `--silent' should accept `--quiet' as a synonym.
+
+`size'
+ `-s' in `ls'.
+
+`socket'
+ Specify a file descriptor for a network server to use for its
+ socket, instead of opening and binding a new socket. This
+ provides a way to run, in a non-privileged process, a server that
+ normally needs a reserved port number.
+
+`sort'
+ Used in `ls'.
+
+`source'
+ `-W source' in `gawk'.
+
+`sparse'
+ `-S' in `tar'.
+
+`speed-large-files'
+ `-H' in `diff'.
+
+`split-at'
+ `-E' in `unshar'.
+
+`split-size-limit'
+ `-L' in `shar'.
+
+`squeeze-blank'
+ `-s' in `cat'.
+
+`start-delete'
+ `-w' in `wdiff'.
+
+`start-insert'
+ `-y' in `wdiff'.
+
+`starting-file'
+ Used in `tar' and `diff' to specify which file within a directory
+ to start processing with.
+
+`statistics'
+ `-s' in `wdiff'.
+
+`stdin-file-list'
+ `-S' in `shar'.
+
+`stop'
+ `-S' in Make.
+
+`strict'
+ `-s' in `recode'.
+
+`strip'
+ `-s' in `install'.
+
+`strip-all'
+ `-s' in `strip'.
+
+`strip-debug'
+ `-S' in `strip'.
+
+`submitter'
+ `-s' in `shar'.
+
+`suffix'
+ `-S' in `cp', `ln', `mv'.
+
+`suffix-format'
+ `-b' in `csplit'.
+
+`sum'
+ `-s' in `gprof'.
+
+`summarize'
+ `-s' in `du'.
+
+`symbolic'
+ `-s' in `ln'.
+
+`symbols'
+ Used in GDB and `objdump'.
+
+`synclines'
+ `-s' in `m4'.
+
+`sysname'
+ `-s' in `uname'.
+
+`tabs'
+ `-t' in `expand' and `unexpand'.
+
+`tabsize'
+ `-T' in `ls'.
+
+`terminal'
+ `-T' in `tput' and `ul'. `-t' in `wdiff'.
+
+`text'
+ `-a' in `diff'.
+
+`text-files'
+ `-T' in `shar'.
+
+`time'
+ Used in `ls' and `touch'.
+
+`timeout'
+ Specify how long to wait before giving up on some operation.
+
+`to-stdout'
+ `-O' in `tar'.
+
+`total'
+ `-c' in `du'.
+
+`touch'
+ `-t' in Make, `ranlib', and `recode'.
+
+`trace'
+ `-t' in `m4'.
+
+`traditional'
+ `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
+ and `ptx'.
+
+`tty'
+ Used in GDB.
+
+`typedefs'
+ `-t' in `ctags'.
+
+`typedefs-and-c++'
+ `-T' in `ctags'.
+
+`typeset-mode'
+ `-t' in `ptx'.
+
+`uncompress'
+ `-z' in `tar'.
+
+`unconditional'
+ `-u' in `cpio'.
+
+`undefine'
+ `-U' in `m4'.
+
+`undefined-only'
+ `-u' in `nm'.
+
+`update'
+ `-u' in `cp', `ctags', `mv', `tar'.
+
+`usage'
+ Used in `gawk'; same as `--help'.
+
+`uuencode'
+ `-B' in `shar'.
+
+`vanilla-operation'
+ `-V' in `shar'.
+
+`verbose'
+ Print more information about progress. Many programs support this.
+
+`verify'
+ `-W' in `tar'.
+
+`version'
+ Print the version number.
+
+`version-control'
+ `-V' in `cp', `ln', `mv'.
+
+`vgrind'
+ `-v' in `ctags'.
+
+`volume'
+ `-V' in `tar'.
+
+`what-if'
+ `-W' in Make.
+
+`whole-size-limit'
+ `-l' in `shar'.
+
+`width'
+ `-w' in `ls' and `ptx'.
+
+`word-regexp'
+ `-W' in `ptx'.
+
+`writable'
+ `-T' in `who'.
+
+`zeros'
+ `-z' in `gprof'.
+
+
+File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
+
+4.9 Memory Usage
+================
+
+If a program typically uses just a few meg of memory, don't bother
+making any effort to reduce memory usage. For example, if it is
+impractical for other reasons to operate on files more than a few meg
+long, it is reasonable to read entire input files into memory to
+operate on them.
+
+ However, for programs such as `cat' or `tail', that can usefully
+operate on very large files, it is important to avoid using a technique
+that would artificially limit the size of files it can handle. If a
+program works by lines and could be applied to arbitrary user-supplied
+input files, it should keep only a line in memory, because this is not
+very hard and users will want to be able to operate on input files that
+are bigger than will fit in memory all at once.
+
+ If your program creates complicated data structures, just make them
+in memory and give a fatal error if `malloc' returns zero.
+
+
+File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
+
+4.10 File Usage
+===============
+
+Programs should be prepared to operate when `/usr' and `/etc' are
+read-only file systems. Thus, if the program manages log files, lock
+files, backup files, score files, or any other files which are modified
+for internal purposes, these files should not be stored in `/usr' or
+`/etc'.
+
+ There are two exceptions. `/etc' is used to store system
+configuration information; it is reasonable for a program to modify
+files in `/etc' when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+
+File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
+
+5 Making The Best Use of C
+**************************
+
+This chapter provides advice on how best to use the C language when
+writing GNU software.
+
+* Menu:
+
+* Formatting:: Formatting your source code.
+* Comments:: Commenting your work.
+* Syntactic Conventions:: Clean use of C constructs.
+* Names:: Naming variables, functions, and files.
+* System Portability:: Portability among different operating systems.
+* CPU Portability:: Supporting the range of CPU types.
+* System Functions:: Portability and ``standard'' library functions.
+* Internationalization:: Techniques for internationalization.
+* Character Set:: Use ASCII by default.
+* Quote Characters:: Use `...' in the C locale.
+* Mmap:: How you can safely use `mmap'.
+
+
+File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
+
+5.1 Formatting Your Source Code
+===============================
+
+It is important to put the open-brace that starts the body of a C
+function in column one, so that they will start a defun. Several tools
+look for open-braces in column one to find the beginnings of C
+functions. These tools will not work on code not formatted that way.
+
+ Avoid putting open-brace, open-parenthesis or open-bracket in column
+one when they are inside a function, so that they won't start a defun.
+The open-brace that starts a `struct' body can go in column one if you
+find it useful to treat that definition as a defun.
+
+ It is also important for function definitions to start the name of
+the function in column one. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus,
+using Standard C syntax, the format is this:
+
+ static char *
+ concat (char *s1, char *s2)
+ {
+ ...
+ }
+
+or, if you want to use traditional C syntax, format the definition like
+this:
+
+ static char *
+ concat (s1, s2) /* Name starts in column one here */
+ char *s1, *s2;
+ { /* Open brace in column one here */
+ ...
+ }
+
+ In Standard C, if the arguments don't fit nicely on one line, split
+it like this:
+
+ int
+ lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+ ...
+
+ The rest of this section gives our recommendations for other aspects
+of C formatting style, which is also the default style of the `indent'
+program in version 1.2 and newer. It corresponds to the options
+
+ -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+ -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+
+ We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+ But whatever style you use, please use it consistently, since a
+mixture of styles within one program tends to look ugly. If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+ For the body of the function, our recommended style looks like this:
+
+ if (x < foo (y, z))
+ haha = bar[4] + 5;
+ else
+ {
+ while (z)
+ {
+ haha += foo (z, z);
+ z--;
+ }
+ return ++x + bar ();
+ }
+
+ We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+ When you split an expression into multiple lines, split it before an
+operator, not after one. Here is the right way:
+
+ if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+
+ Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+ mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+
+ Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+ mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+
+ Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+ v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+ v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+
+ Format do-while statements like this:
+
+ do
+ {
+ a = foo (a);
+ }
+ while (a > 0);
+
+ Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+
+File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
+
+5.2 Commenting Your Work
+========================
+
+Every program should start with a comment saying briefly what it is for.
+Example: `fmt - filter for simple filling of text'. This comment
+should be at the top of the source file containing the `main' function
+of the program.
+
+ Also, please write a brief comment at the start of each source file,
+with the file name and a line or two about the overall purpose of the
+file.
+
+ Please write the comments in a GNU program in English, because
+English is the one language that nearly all programmers in all
+countries can read. If you do not write English well, please write
+comments in English as well as you can, then ask other people to help
+rewrite them. If you can't write comments in English, please find
+someone to work with you and translate your comments into English.
+
+ Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion. If there is anything nonstandard about
+its use (such as an argument of type `char *' which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+ Also explain the significance of the return value, if there is one.
+
+ Please put two spaces after the end of a sentence in your comments,
+so that the Emacs sentence commands will work. Also, please write
+complete sentences and capitalize the first word. If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier. If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., "The identifier lower-case is ...").
+
+ The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, "the inode
+number NODE_NUM" rather than "an inode".
+
+ There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the
+function itself would be off the bottom of the screen.
+
+ There should be a comment on each static variable as well, like this:
+
+ /* Nonzero means truncate lines in the display;
+ zero means continue them. */
+ int truncate_lines;
+
+ Every `#endif' should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, _including its
+sense_. `#else' should have a comment describing the condition _and
+sense_ of the code that follows. For example:
+
+ #ifdef foo
+ ...
+ #else /* not foo */
+ ...
+ #endif /* not foo */
+ #ifdef foo
+ ...
+ #endif /* foo */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+ #ifndef foo
+ ...
+ #else /* foo */
+ ...
+ #endif /* foo */
+ #ifndef foo
+ ...
+ #endif /* not foo */
+
+
+File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
+
+5.3 Clean Use of C Constructs
+=============================
+
+Please explicitly declare the types of all objects. For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return `int' rather than omitting the `int'.
+
+ Some programmers like to use the GCC `-Wall' option, and change the
+code whenever it issues a warning. If you want to do this, then do.
+Other programmers prefer not to use `-Wall', because it gives warnings
+for valid and legitimate code which they do not want to change. If you
+want to do this, then do. The compiler should be your servant, not
+your master.
+
+ Declarations of external functions and functions to appear later in
+the source file should all go in one place near the beginning of the
+file (somewhere before the first function definition in the file), or
+else should go in a header file. Don't put `extern' declarations inside
+functions.
+
+ It used to be common practice to use the same local variables (with
+names like `tem') over and over for different values within one
+function. Instead of doing this, it is better to declare a separate
+local variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+ Don't use local variables or parameters that shadow global
+identifiers.
+
+ Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead of
+this:
+
+ int foo,
+ bar;
+
+write either this:
+
+ int foo, bar;
+
+or this:
+
+ int foo;
+ int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+ When you have an `if'-`else' statement nested in another `if'
+statement, always put braces around the `if'-`else'. Thus, never write
+like this:
+
+ if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+
+always like this:
+
+ if (foo)
+ {
+ if (bar)
+ win ();
+ else
+ lose ();
+ }
+
+ If you have an `if' statement nested inside of an `else' statement,
+either write `else if' on one line, like this,
+
+ if (foo)
+ ...
+ else if (bar)
+ ...
+
+with its `then'-part indented like the preceding `then'-part, or write
+the nested `if' within braces like this:
+
+ if (foo)
+ ...
+ else
+ {
+ if (bar)
+ ...
+ }
+
+ Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately and
+then use it to declare the variables or typedefs.
+
+ Try to avoid assignments inside `if'-conditions (assignments inside
+`while'-conditions are ok). For example, don't write this:
+
+ if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+
+instead, write this:
+
+ foo = (char *) malloc (sizeof *foo);
+ if (foo == 0)
+ fatal ("virtual memory exhausted");
+
+ Don't make the program ugly to placate `lint'. Please don't insert
+any casts to `void'. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+
+File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
+
+5.4 Naming Variables, Functions, and Files
+==========================================
+
+The names of global variables and functions in a program serve as
+comments of a sort. So don't choose terse names--instead, look for
+names that give useful information about the meaning of the variable or
+function. In a GNU program, names should be English, like other
+comments.
+
+ Local variable names can be shorter, because they are used only
+within one context, where (presumably) comments explain their purpose.
+
+ Try to limit your use of abbreviations in symbol names. It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+ Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them. Stick to lower case; reserve
+upper case for macros and `enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+ For example, you should use names like `ignore_space_change_flag';
+don't use names like `iCantReadThis'.
+
+ Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+ /* Ignore changes in horizontal whitespace (-b). */
+ int ignore_space_change_flag;
+
+ When you want to define names with constant integer values, use
+`enum' rather than `#define'. GDB knows about enumeration constants.
+
+ You might want to make sure that none of the file names would
+conflict if the files were loaded onto an MS-DOS file system which
+shortens the names. You can use the program `doschk' to test for this.
+
+ Some GNU programs were designed to limit themselves to file names of
+14 characters or less, to avoid file name conflicts if they are read
+into older System V systems. Please preserve this feature in the
+existing GNU programs that have it, but there is no need to do this in
+new GNU programs. `doschk' also reports file names longer than 14
+characters.
+
+
+File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
+
+5.5 Portability between System Types
+====================================
+
+In the Unix world, "portability" refers to porting to different Unix
+versions. For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+ The primary purpose of GNU software is to run on top of the GNU
+kernel, compiled with the GNU C compiler, on various types of CPU. So
+the kinds of portability that are absolutely necessary are quite
+limited. But it is important to support Linux-based GNU systems, since
+they are the form of GNU that is popular.
+
+ Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to. Supporting a variety of Unix-like systems is desirable, although
+not paramount. It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+ The easiest way to achieve portability to most Unix-like systems is
+to use Autoconf. It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+ Avoid using the format of semi-internal data bases (e.g.,
+directories) when there is a higher-level alternative (`readdir').
+
+ As for systems that are not like Unix, such as MSDOS, Windows, VMS,
+MVS, and older Macintosh systems, supporting them is often a lot of
+work. When that is the case, it is better to spend your time adding
+features that will be useful on GNU and GNU/Linux, rather than on
+supporting other incompatible systems.
+
+ If you do support Windows, please do not abbreviate it as "win". In
+hacker terminology, calling something a "win" is a form of praise.
+You're free to praise Microsoft Windows on your own if you want, but
+please don't do this in GNU packages. Instead of abbreviating
+"Windows" to "un", you can write it in full or abbreviate it to "woe"
+or "w". In GNU Emacs, for instance, we use `w32' in file names of
+Windows-specific files, but the macro for Windows conditionals is
+called `WINDOWSNT'.
+
+ It is a good idea to define the "feature test macro" `_GNU_SOURCE'
+when compiling your C files. When you compile on GNU or GNU/Linux,
+this will enable the declarations of GNU library extension functions,
+and that will usually give you a compiler error message if you define
+the same function names in some other way in your program. (You don't
+have to actually _use_ these functions, if you prefer to make the
+program more portable to other systems.)
+
+ But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings. Doing so would make it hard
+to move your code into other GNU programs.
+
+
+File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
+
+5.6 Portability between CPUs
+============================
+
+Even GNU systems will differ because of differences among CPU
+types--for example, difference in byte ordering and alignment
+requirements. It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+`int' will be less than 32 bits. We don't support 16-bit machines in
+GNU.
+
+ Similarly, don't make any effort to cater to the possibility that
+`long' will be smaller than predefined types like `size_t'. For
+example, the following code is ok:
+
+ printf ("size = %lu\n", (unsigned long) sizeof array);
+ printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+
+ 1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows. We will leave it
+to those who want to port GNU programs to that environment to figure
+out how to do it.
+
+ Predefined file-size types like `off_t' are an exception: they are
+longer than `long' on many platforms, so code like the above won't work
+with them. One way to print an `off_t' value portably is to print its
+digits yourself, one by one.
+
+ Don't assume that the address of an `int' object is also the address
+of its least-significant byte. This is false on big-endian machines.
+Thus, don't make the following mistake:
+
+ int c;
+ ...
+ while ((c = getchar ()) != EOF)
+ write (file_descriptor, &c, 1);
+
+Instead, use `unsigned char' as follows. (The `unsigned' is for
+portability to unusual systems where `char' is signed and where there
+is integer overflow checking.)
+
+ int c;
+ while ((c = getchar ()) != EOF)
+ {
+ unsigned char u = c;
+ write (file_descriptor, &u, 1);
+ }
+
+ It used to be ok to not worry about the difference between pointers
+and integers when passing arguments to functions. However, on most
+modern 64-bit machines pointers are wider than `int'. Conversely,
+integer types like `long long int' and `off_t' are wider than pointers
+on most modern 32-bit machines. Hence it's often better nowadays to
+use prototypes to define functions whose argument types are not trivial.
+
+ In particular, if functions accept varying argument counts or types
+they should be declared using prototypes containing `...' and defined
+using `stdarg.h'. For an example of this, please see the Gnulib
+(http://www.gnu.org/software/gnulib/) error module, which declares and
+defines the following function:
+
+ /* Print a message with `fprintf (stderr, FORMAT, ...)';
+ if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
+ If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
+
+ void error (int status, int errnum, const char *format, ...);
+
+ A simple way to use the Gnulib error module is to obtain the two
+source files `error.c' and `error.h' from the Gnulib library source
+code repository at
+`http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/'. Here's a
+sample use:
+
+ #include "error.h"
+ #include <errno.h>
+ #include <stdio.h>
+
+ char *program_name = "myprogram";
+
+ FILE *
+ xfopen (char const *name)
+ {
+ FILE *fp = fopen (name, "r");
+ if (! fp)
+ error (1, errno, "cannot read %s", name);
+ return fp;
+ }
+
+ Avoid casting pointers to integers if you can. Such casts greatly
+reduce portability, and in most programs they are easy to avoid. In the
+cases where casting pointers to integers is essential--such as, a Lisp
+interpreter which stores type information as well as an address in one
+word--you'll have to make explicit provisions to handle different word
+sizes. You will also need to make provision for systems in which the
+normal range of addresses you can get from `malloc' starts far away
+from zero.
+
+
+File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
+
+5.7 Calling System Functions
+============================
+
+C implementations differ substantially. Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do. This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
+
+ * Don't use the return value of `sprintf'. It returns the number of
+ characters written on some systems, but not on all systems.
+
+ * Be aware that `vfprintf' is not always available.
+
+ * `main' should be declared to return type `int'. It should
+ terminate either by calling `exit' or by returning the integer
+ status code; make sure it cannot ever return an undefined value.
+
+ * Don't declare system functions explicitly.
+
+ Almost any declaration for a system function is wrong on some
+ system. To minimize conflicts, leave it to the system header
+ files to declare system functions. If the headers don't declare a
+ function, let it remain undeclared.
+
+ While it may seem unclean to use a function without declaring it,
+ in practice this works fine for most system library functions on
+ the systems where this really happens; thus, the disadvantage is
+ only theoretical. By contrast, actual declarations have
+ frequently caused actual conflicts.
+
+ * If you must declare a system function, don't specify the argument
+ types. Use an old-style declaration, not a Standard C prototype.
+ The more you specify about the function, the more likely a
+ conflict.
+
+ * In particular, don't unconditionally declare `malloc' or `realloc'.
+
+ Most GNU programs use those functions just once, in functions
+ conventionally named `xmalloc' and `xrealloc'. These functions
+ call `malloc' and `realloc', respectively, and check the results.
+
+ Because `xmalloc' and `xrealloc' are defined in your program, you
+ can declare them in other files without any risk of type conflict.
+
+ On most systems, `int' is the same length as a pointer; thus, the
+ calls to `malloc' and `realloc' work fine. For the few
+ exceptional systems (mostly 64-bit machines), you can use
+ *conditionalized* declarations of `malloc' and `realloc'--or put
+ these declarations in configuration files specific to those
+ systems.
+
+ * The string functions require special treatment. Some Unix systems
+ have a header file `string.h'; others have `strings.h'. Neither
+ file name is portable. There are two things you can do: use
+ Autoconf to figure out which file to include, or don't include
+ either file.
+
+ * If you don't include either strings file, you can't get
+ declarations for the string functions from the header file in the
+ usual way.
+
+ That causes less of a problem than you might think. The newer
+ standard string functions should be avoided anyway because many
+ systems still don't support them. The string functions you can
+ use are these:
+
+ strcpy strncpy strcat strncat
+ strlen strcmp strncmp
+ strchr strrchr
+
+ The copy and concatenate functions work fine without a declaration
+ as long as you don't use their values. Using their values without
+ a declaration fails on systems where the width of a pointer
+ differs from the width of `int', and perhaps in other cases. It
+ is trivial to avoid using their values, so do that.
+
+ The compare functions and `strlen' work fine without a declaration
+ on most systems, possibly all the ones that GNU software runs on.
+ You may find it necessary to declare them *conditionally* on a few
+ systems.
+
+ The search functions must be declared to return `char *'. Luckily,
+ there is no variation in the data type they return. But there is
+ variation in their names. Some systems give these functions the
+ names `index' and `rindex'; other systems use the names `strchr'
+ and `strrchr'. Some systems support both pairs of names, but
+ neither pair works on all systems.
+
+ You should pick a single pair of names and use it throughout your
+ program. (Nowadays, it is better to choose `strchr' and `strrchr'
+ for new programs, since those are the standard names.) Declare
+ both of those names as functions returning `char *'. On systems
+ which don't support those names, define them as macros in terms of
+ the other pair. For example, here is what to put at the beginning
+ of your file (or in a header) if you want to use the names
+ `strchr' and `strrchr' throughout:
+
+ #ifndef HAVE_STRCHR
+ #define strchr index
+ #endif
+ #ifndef HAVE_STRRCHR
+ #define strrchr rindex
+ #endif
+
+ char *strchr ();
+ char *strrchr ();
+
+ Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
+defined in systems where the corresponding functions exist. One way to
+get them properly defined is to use Autoconf.
+
+
+File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C
+
+5.8 Internationalization
+========================
+
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages. You should use this
+library in every program. Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+ Using GNU gettext involves putting a call to the `gettext' macro
+around each string that might need translation--like this:
+
+ printf (gettext ("Processing file `%s'..."));
+
+This permits GNU gettext to replace the string `"Processing file
+`%s'..."' with a translated version.
+
+ Once a program uses gettext, please make a point of writing calls to
+`gettext' when you add new strings that call for translation.
+
+ Using GNU gettext in a package involves specifying a "text domain
+name" for the package. The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package--for example, `coreutils' for the GNU core utilities.
+
+ To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences. When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+ Here is an example of what not to do:
+
+ printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
+
+ If you apply gettext to all strings, like this,
+
+ printf (gettext ("%s is full"),
+ capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
+
+the translator will hardly know that "disk" and "floppy disk" are meant
+to be substituted in the other string. Worse, in some languages (like
+French) the construction will not work: the translation of the word
+"full" depends on the gender of the first part of the sentence; it
+happens to be not the same for "disk" as for "floppy disk".
+
+ Complete sentences can be translated without problems:
+
+ printf (capacity > 5000000 ? gettext ("disk is full")
+ : gettext ("floppy disk is full"));
+
+ A similar problem appears at the level of sentence structure with
+this code:
+
+ printf ("# Implicit rule search has%s been done.\n",
+ f->tried_implicit ? "" : " not");
+
+Adding `gettext' calls to this code cannot give correct results for all
+languages, because negation in some languages requires adding words at
+more than one place in the sentence. By contrast, adding `gettext'
+calls does the job straightforwardly if the code starts out like this:
+
+ printf (f->tried_implicit
+ ? "# Implicit rule search has been done.\n",
+ : "# Implicit rule search has not been done.\n");
+
+ Another example is this one:
+
+ printf ("%d file%s processed", nfiles,
+ nfiles != 1 ? "s" : "");
+
+The problem with this example is that it assumes that plurals are made
+by adding `s'. If you apply gettext to the format string, like this,
+
+ printf (gettext ("%d file%s processed"), nfiles,
+ nfiles != 1 ? "s" : "");
+
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way, with gettext being applied to
+the two strings independently:
+
+ printf ((nfiles != 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+
+But this still doesn't work for languages like Polish, which has three
+plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23,
+24, ... and one for the rest. The GNU `ngettext' function solves this
+problem:
+
+ printf (ngettext ("%d files processed", "%d file processed", nfiles),
+ nfiles);
+
+
+File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C
+
+5.9 Character Set
+=================
+
+Sticking to the ASCII character set (plain text, 7-bit characters) is
+preferred in GNU source code comments, text documents, and other
+contexts, unless there is good reason to do something else because of
+the application domain. For example, if source code deals with the
+French Revolutionary calendar, it is OK if its literal strings contain
+accented characters in month names like "Flore'al". Also, it is OK to
+use non-ASCII characters to represent proper names of contributors in
+change logs (*note Change Logs::).
+
+ If you need to use non-ASCII characters, you should normally stick
+with one encoding, as one cannot in general mix encodings reliably.
+
+
+File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C
+
+5.10 Quote Characters
+=====================
+
+In the C locale, GNU programs should stick to plain ASCII for quotation
+characters in messages to users: preferably 0x60 (``') for left quotes
+and 0x27 (`'') for right quotes. It is ok, but not required, to use
+locale-specific quotes in other locales.
+
+ The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
+`quotearg' modules provide a reasonably straightforward way to support
+locale-specific quote characters, as well as taking care of other
+issues, such as quoting a filename that itself contains a quote
+character. See the Gnulib documentation for usage details.
+
+ In any case, the documentation for your program should clearly
+specify how it does quoting, if different than the preferred method of
+``' and `''. This is especially important if the output of your
+program is ever likely to be parsed by another program.
+
+ Quotation characters are a difficult area in the computing world at
+this time: there are no true left or right quote characters in Latin1;
+the ``' character we use was standardized there as a grave accent.
+Moreover, Latin1 is still not universally usable.
+
+ Unicode contains the unambiguous quote characters required, and its
+common encoding UTF-8 is upward compatible with Latin1. However,
+Unicode and UTF-8 are not universally well-supported, either.
+
+ This may change over the next few years, and then we will revisit
+this.
+
+
+File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C
+
+5.11 Mmap
+=========
+
+Don't assume that `mmap' either works on all files or fails for all
+files. It may work on some files and fail on others.
+
+ The proper way to use `mmap' is to try it on the specific file for
+which you want to use it--and if `mmap' doesn't work, fall back on
+doing the job in another way using `read' and `write'.
+
+ The reason this precaution is needed is that the GNU kernel (the
+HURD) provides a user-extensible file system, in which there can be many
+different kinds of "ordinary files." Many of them support `mmap', but
+some do not. It is important to make programs handle all these kinds
+of files.
+
+
+File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
+
+6 Documenting Programs
+**********************
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes. If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+* Menu:
+
+* GNU Manuals:: Writing proper manuals.
+* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
+* Manual Structure Details:: Specific structure conventions.
+* License for Manuals:: Writing the distribution terms for a manual.
+* Manual Credits:: Giving credit to documentation contributors.
+* Printed Manuals:: Mentioning the printed manual.
+* NEWS File:: NEWS files supplement manuals.
+* Change Logs:: Recording changes.
+* Man Pages:: Man pages are secondary.
+* Reading other Manuals:: How far you can go in learning
+ from other manuals.
+
+
+File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
+
+6.1 GNU Manuals
+===============
+
+The preferred document format for the GNU system is the Texinfo
+formatting language. Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners. Texinfo
+makes it possible to produce a good quality formatted book, using TeX,
+and to generate an Info file. It is also possible to generate HTML
+output from Texinfo source. See the Texinfo manual, either the
+hardcopy, or the on-line version available through `info' or the Emacs
+Info subsystem (`C-h i').
+
+ Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo. It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+ Make sure your manual is clear to a reader who knows nothing about
+the topic and reads it straight through. This means covering basic
+topics at the beginning, and advanced topics only later. This also
+means defining every specialized term when it is first used.
+
+ Programmers tend to carry over the structure of the program as the
+structure for its documentation. But this structure is not necessarily
+good for explaining how to use the program; it may be irrelevant and
+confusing for a user.
+
+ Instead, the right way to structure documentation is according to the
+concepts and questions that a user will have in mind when reading it.
+This principle applies at every level, from the lowest (ordering
+sentences in a paragraph) to the highest (ordering of chapter topics
+within the manual). Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented--but
+often they are different. An important part of learning to write good
+documentation is to learn to notice when you have unthinkingly
+structured the documentation like the implementation, stop yourself,
+and look for better alternatives.
+
+ For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual. That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+ Instead, each manual should cover a coherent _topic_. For example,
+instead of a manual for `diff' and a manual for `diff3', we have one
+manual for "comparison of files" which covers both of those programs,
+as well as `cmp'. By documenting these programs together, we can make
+the whole subject clearer.
+
+ The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands. It should
+give examples of their use. But don't organize the manual as a list of
+features. Instead, organize it logically, by subtopics. Address the
+questions that a user will ask when thinking about the job that the
+program does. Don't just tell the reader what each feature can do--say
+what jobs it is good for, and show how to use it for those jobs.
+Explain what is recommended usage, and what kinds of usage users should
+avoid.
+
+ In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside). A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want. The
+Bison manual is a good example of this--please take a look at it to see
+what we mean.
+
+ That is not as hard as it first sounds. Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense. Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs. The watchword is, _at each point, address the
+most fundamental and important issue raised by the preceding text._
+
+ If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject. These provide
+the framework for a beginner to understand the rest of the manual. The
+Bison manual provides a good example of how to do this.
+
+ To serve as a reference, a manual should have an Index that list all
+the functions, variables, options, and important concepts that are part
+of the program. One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+*Note Making Index Entries: (texinfo)Index Entries, and see *Note
+Defining the Entries of an Index: (texinfo)Indexing Commands.
+
+ Don't use Unix man pages as a model for how to write GNU
+documentation; most of them are terse, badly structured, and give
+inadequate explanation of the underlying concepts. (There are, of
+course, some exceptions.) Also, Unix man pages use a particular format
+which is different from what we use in GNU manuals.
+
+ Please include an email address in the manual for where to report
+bugs _in the text of the manual_.
+
+ Please do not use the term "pathname" that is used in Unix
+documentation; use "file name" (two words) instead. We use the term
+"path" only for search paths, which are lists of directory names.
+
+ Please do not use the term "illegal" to refer to erroneous input to
+a computer program. Please use "invalid" for this, and reserve the
+term "illegal" for activities prohibited by law.
+
+ Please do not write `()' after a function name just to indicate it
+is a function. `foo ()' is not a function, it is a function call with
+no arguments.
+
+
+File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
+
+6.2 Doc Strings and Manuals
+===========================
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable. You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them--but you must not do it. That
+approach is a fundamental mistake. The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+ A documentation string needs to stand alone--when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+ The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection. Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables. The previous descriptions of functions and variables in the
+section will also have given information about the topic. A description
+written to stand alone would repeat some of that information; this
+redundancy looks bad. Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+ The only good way to use documentation strings in writing a good
+manual is to use them as a source of information for writing good text.
+
+
+File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
+
+6.3 Manual Structure Details
+============================
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual. The Top node of the manual should
+also contain this information. If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+ Each program documented in the manual should have a node named
+`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
+its subnodes, if any) should describe the program's command line
+arguments and how to run it (the sort of information people would look
+for in a man page). Start with an `@example' containing a template for
+all the options and arguments that the program uses.
+
+ Alternatively, put a menu item in some menu whose item name fits one
+of the above patterns. This identifies the node which that item points
+to as the node for this purpose, regardless of the node's actual name.
+
+ The `--usage' feature of the Info reader looks for such a node or
+menu item in order to find the relevant text, so it is essential for
+every Texinfo file to have one.
+
+ If one manual describes several programs, it should have such a node
+for each program described in the manual.
+
+
+File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
+
+6.4 License for Manuals
+=======================
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long. Likewise for a collection of short
+documents--you only need one copy of the GNU FDL for the whole
+collection. For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+ See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
+of how to employ the GFDL.
+
+ Note that it is not obligatory to include a copy of the GNU GPL or
+GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
+can be a good idea to include the program's license in a large manual;
+in a short manual, whose size would be increased considerably by
+including the program's license, it is probably better not to include
+it.
+
+
+File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
+
+6.5 Manual Credits
+==================
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual. If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+
+File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
+
+6.6 Printed Manuals
+===================
+
+The FSF publishes some GNU manuals in printed form. To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it--for instance, with a link to the page
+`http://www.gnu.org/order/order.html'. This should not be included in
+the printed manual, though, because there it is redundant.
+
+ It is also useful to explain in the on-line forms of the manual how
+the user can print out the manual from the sources.
+
+
+File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
+
+6.7 The NEWS File
+=================
+
+In addition to its manual, the package should have a file named `NEWS'
+which contains a list of user-visible changes worth mentioning. In
+each new release, add items to the front of the file and identify the
+version they pertain to. Don't discard old items; leave them in the
+file after the newer items. This way, a user upgrading from any
+previous version can see what is new.
+
+ If the `NEWS' file gets very long, move some of the older items into
+a file named `ONEWS' and put a note at the end referring the user to
+that file.
+
+
+File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
+
+6.8 Change Logs
+===============
+
+Keep a change log to describe all the changes made to program source
+files. The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+* Menu:
+
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+* Indicating the Part Changed::
+
+
+File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
+
+6.8.1 Change Log Concepts
+-------------------------
+
+You can think of the change log as a conceptual "undo list" which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log to
+tell them what is in it. What they want from a change log is a clear
+explanation of how the earlier version differed.
+
+ The change log file is normally called `ChangeLog' and covers an
+entire directory. Each directory can have its own change log, or a
+directory can use the change log of its parent directory-it's up to you.
+
+ Another alternative is to record change log information with a
+version control system such as RCS or CVS. This can be converted
+automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
+command `C-x v a' (`vc-update-change-log') does the job.
+
+ There's no need to describe the full purpose of the changes or how
+they work together. If you think that a change calls for explanation,
+you're probably right. Please do explain it--but please put the
+explanation in comments in the code, where people will see it whenever
+they see the code. For example, "New function" is enough for the
+change log when you add a function, because there should be a comment
+before the function definition to explain what it does.
+
+ In the past, we recommended not mentioning changes in non-software
+files (manuals, help files, etc.) in change logs. However, we've been
+advised that it is a good idea to include them, for the sake of
+copyright records.
+
+ However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+ The easiest way to add an entry to `ChangeLog' is with the Emacs
+command `M-x add-change-log-entry'. An entry should have an asterisk,
+the name of the changed file, and then in parentheses the name of the
+changed functions, variables or whatever, followed by a colon. Then
+describe the changes you made to that function or variable.
+
+
+File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
+
+6.8.2 Style of Change Logs
+--------------------------
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when it was installed,
+followed by descriptions of specific changes. (These examples are
+drawn from Emacs and GCC.)
+
+ 1998-08-17 Richard Stallman <rms@gnu.org>
+
+ * register.el (insert-register): Return nil.
+ (jump-to-register): Likewise.
+
+ * sort.el (sort-subr): Return nil.
+
+ * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+ Restart the tex shell if process is gone or stopped.
+ (tex-shell-running): New function.
+
+ * expr.c (store_one_arg): Round size up for move_block_to_reg.
+ (expand_call): Round up when emitting USE insns.
+ * stmt.c (assign_parms): Round size up for move_block_from_reg.
+
+ It's important to name the changed function or variable in full.
+Don't abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+ For example, some people are tempted to abbreviate groups of function
+names by writing `* register.el ({insert,jump-to}-register)'; this is
+not a good idea, since searching for `jump-to-register' or
+`insert-register' would not find that entry.
+
+ Separate unrelated change log entries with blank lines. When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them. Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+ Break long lists of function names by closing continued lines with
+`)', rather than `,', and opening the continuation with `(' as in this
+example:
+
+ * keyboard.c (menu_bar_items, tool_bar_items)
+ (Fexecute_extended_command): Deal with `keymap' property.
+
+ When you install someone else's changes, put the contributor's name
+in the change log entry rather than in the text of the entry. In other
+words, write this:
+
+ 2002-07-14 John Doe <jdoe@gnu.org>
+
+ * sewing.c: Make it sew.
+
+rather than this:
+
+ 2002-07-14 Usual Maintainer <usual@gnu.org>
+
+ * sewing.c: Make it sew. Patch by jdoe@gnu.org.
+
+ As for the date, that should be the date you applied the change.
+
+
+File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
+
+6.8.3 Simple Changes
+--------------------
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+ When you change the calling sequence of a function in a simple
+fashion, and you change all the callers of the function to use the new
+calling sequence, there is no need to make individual entries for all
+the callers that you changed. Just write in the entry for the function
+being called, "All callers changed"--like this:
+
+ * keyboard.c (Fcommand_execute): New arg SPECIAL.
+ All callers changed.
+
+ When you change just comments or doc strings, it is enough to write
+an entry for the file, without mentioning the functions. Just "Doc
+fixes" is enough for the change log.
+
+ There's no technical need to make change log entries for
+documentation files. This is because documentation is not susceptible
+to bugs that are hard to fix. Documentation does not consist of parts
+that must interact in a precisely engineered fashion. To correct an
+error, you need not know the history of the erroneous passage; it is
+enough to compare what the documentation says with the way the program
+actually works.
+
+ However, you should keep change logs for documentation files when the
+project gets copyright assignments from its contributors, so as to make
+the records of authorship more accurate.
+
+
+File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
+
+6.8.4 Conditional Changes
+-------------------------
+
+C programs often contain compile-time `#if' conditionals. Many changes
+are conditional; sometimes you add a new definition which is entirely
+contained in a conditional. It is very useful to indicate in the
+change log the conditions for which the change applies.
+
+ Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+ Here is a simple example, describing a change which is conditional
+but does not have a function or entity name associated with it:
+
+ * xterm.c [SOLARIS2]: Include string.h.
+
+ Here is an entry describing a new definition which is entirely
+conditional. This new definition for the macro `FRAME_WINDOW_P' is
+used only when `HAVE_X_WINDOWS' is defined:
+
+ * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+
+ Here is an entry for a change within the function `init_display',
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
+
+ * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+
+ Here is an entry for a change that takes affect only when a certain
+macro is _not_ defined:
+
+ (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+
+
+File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
+
+6.8.5 Indicating the Part Changed
+---------------------------------
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does. Here is an entry
+for a change in the part of the function `sh-while-getopts' that deals
+with `sh' commands:
+
+ * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+ user-specified option string is empty.
+
+
+File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
+
+6.9 Man Pages
+=============
+
+In the GNU project, man pages are secondary. It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+ When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed. The time
+you spend on the man page is time taken away from more useful work.
+
+ For a simple program which changes little, updating the man page may
+be a small job. Then there is little reason not to include a man page,
+if you have one.
+
+ For a large program that changes a great deal, updating a man page
+may be a substantial burden. If a user offers to donate a man page,
+you may find this gift costly to accept. It may be better to refuse
+the man page unless the same person agrees to take full responsibility
+for maintaining it--so that you can wash your hands of it entirely. If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+ When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating. If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative. The note should say how to access the Texinfo
+documentation.
+
+ Be sure that man pages include a copyright statement and free
+license. The simple all-permissive license is appropriate for simple
+man pages:
+
+ Copying and distribution of this file, with or without modification,
+ are permitted in any medium without royalty provided the copyright
+ notice and this notice are preserved.
+
+ For long man pages, with enough explanation and documentation that
+they can be considered true manuals, use the GFDL (*note License for
+Manuals::).
+
+ Finally, the GNU help2man program
+(`http://www.gnu.org/software/help2man/') is one way to automate
+generation of a man page, in this case from `--help' output. This is
+sufficient in many cases.
+
+
+File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
+
+6.10 Reading other Manuals
+==========================
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+ It is ok to use these documents for reference, just as the author of
+a new algebra textbook can read other books on algebra. A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject. But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation. Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+
+File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
+
+7 The Release Process
+*********************
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of all
+GNU software.
+
+* Menu:
+
+* Configuration:: How configuration of GNU packages should work.
+* Makefile Conventions:: Makefile conventions.
+* Releases:: Making releases
+
+
+File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
+
+7.1 How Configuration Should Work
+=================================
+
+Each GNU distribution should come with a shell script named
+`configure'. This script is given arguments which describe the kind of
+machine and system you want to compile the program for.
+
+ The `configure' script must record the configuration options so that
+they affect compilation.
+
+ One way to do this is to make a link from a standard name such as
+`config.h' to the proper configuration file for the chosen system. If
+you use this technique, the distribution should _not_ contain a file
+named `config.h'. This is so that people won't be able to build the
+program without configuring it first.
+
+ Another thing that `configure' can do is to edit the Makefile. If
+you do this, the distribution should _not_ contain a file named
+`Makefile'. Instead, it should include a file `Makefile.in' which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+ If `configure' does write the `Makefile', then `Makefile' should
+have a target named `Makefile' which causes `configure' to be rerun,
+setting up the same configuration that was set up last time. The files
+that `configure' reads should be listed as dependencies of `Makefile'.
+
+ All the files which are output from the `configure' script should
+have comments at the beginning explaining that they were generated
+automatically using `configure'. This is so that users won't think of
+trying to edit them by hand.
+
+ The `configure' script should write a file named `config.status'
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+ The `configure' script should accept an option of the form
+`--srcdir=DIRNAME' to specify the directory where sources are found (if
+it is not the current directory). This makes it possible to build the
+program in a separate directory, so that the actual source directory is
+not modified.
+
+ If the user does not specify `--srcdir', then `configure' should
+check both `.' and `..' to see if it can find the sources. If it finds
+the sources in one of these places, it should use them from there.
+Otherwise, it should report that it cannot find the sources, and should
+exit with nonzero status.
+
+ Usually the easy way to support `--srcdir' is by editing a
+definition of `VPATH' into the Makefile. Some rules may need to refer
+explicitly to the specified source directory. To make this possible,
+`configure' can add to the Makefile a variable named `srcdir' whose
+value is precisely the specified directory.
+
+ The `configure' script should also take an argument which specifies
+the type of system to build the program for. This argument should look
+like this:
+
+ CPU-COMPANY-SYSTEM
+
+ For example, an Athlon-based GNU/Linux system might be
+`i686-pc-linux-gnu'.
+
+ The `configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus,
+`athlon-pc-gnu/linux' would be a valid alias. There is a shell script
+called `config.sub'
+(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub)
+that you can use as a subroutine to validate system types and
+canonicalize aliases.
+
+ The `configure' script should also take the option
+`--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
+argument. For example, `configure --build=i686-pc-linux-gnu' is
+equivalent to `configure i686-pc-linux-gnu'. When the build type is
+not specified by an option or argument, the `configure' script should
+normally guess it using the shell script `config.guess'
+(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess).
+
+ Other options are permitted to specify in more detail the software
+or hardware present on the machine, to include or exclude optional parts
+of the package, or to adjust the name of some tools or arguments to
+them:
+
+`--enable-FEATURE[=PARAMETER]'
+ Configure the package to build and install an optional user-level
+ facility called FEATURE. This allows users to choose which
+ optional features to include. Giving an optional PARAMETER of
+ `no' should omit FEATURE, if it is built by default.
+
+ No `--enable' option should *ever* cause one feature to replace
+ another. No `--enable' option should ever substitute one useful
+ behavior for another useful behavior. The only proper use for
+ `--enable' is for questions of whether to build part of the program
+ or exclude it.
+
+`--with-PACKAGE'
+ The package PACKAGE will be installed, so configure this package
+ to work with PACKAGE.
+
+ Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
+ `gnu-libc', `gdb', `x', and `x-toolkit'.
+
+ Do not use a `--with' option to specify the file name to use to
+ find certain files. That is outside the scope of what `--with'
+ options are for.
+
+`VARIABLE=VALUE'
+ Set the value of the variable VARIABLE to VALUE. This is used to
+ override the default values of commands or arguments in the build
+ process. For example, the user could issue `configure CFLAGS=-g
+ CXXFLAGS=-g' to build with debugging information and without the
+ default optimization.
+
+ Specifying variables as arguments to `configure', like this:
+ ./configure CC=gcc
+ is preferable to setting them in environment variables:
+ CC=gcc ./configure
+ as it helps to recreate the same configuration later with
+ `config.status'.
+
+ All `configure' scripts should accept all of the "detail" options
+and the variable settings, whether or not they make any difference to
+the particular package at hand. In particular, they should accept any
+option that starts with `--with-' or `--enable-'. This is so users
+will be able to configure an entire GNU source tree at once with a
+single set of options.
+
+ You will note that the categories `--with-' and `--enable-' are
+narrow: they *do not* provide a place for any sort of option you might
+think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+ Packages that perform part of the compilation process may support
+cross-compilation. In such a case, the host and target machines for the
+program may be different.
+
+ The `configure' script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+ To compile a program to run on a host type that differs from the
+build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
+uses the same syntax as BUILDTYPE. The host type normally defaults to
+the build type.
+
+ To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
+for the host type. So the command would look like this:
+
+ ./configure --host=HOSTTYPE --target=TARGETTYPE
+
+ The target type normally defaults to the host type. Programs for
+which cross-operation is not meaningful need not accept the `--target'
+option, because configuring an entire operating system for
+cross-operation is not a meaningful operation.
+
+ Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your `configure' script can simply
+ignore most of its arguments.
+
+
+File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
+
+7.2 Makefile Conventions
+========================
+
+This node describes conventions for writing the Makefiles for GNU
+programs. Using Automake will help you write a Makefile that follows
+these conventions.
+
+* Menu:
+
+* Makefile Basics:: General conventions for Makefiles.
+* Utilities in Makefiles:: Utilities to be used in Makefiles.
+* Command Variables:: Variables for specifying commands.
+* DESTDIR:: Supporting staged installs.
+* Directory Variables:: Variables for installation directories.
+* Standard Targets:: Standard targets for users.
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
+
+
+File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
+
+7.2.1 General Conventions for Makefiles
+---------------------------------------
+
+Every Makefile should contain this line:
+
+ SHELL = /bin/sh
+
+to avoid trouble on systems where the `SHELL' variable might be
+inherited from the environment. (This is never a problem with GNU
+`make'.)
+
+ Different `make' programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior. So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+ .SUFFIXES:
+ .SUFFIXES: .c .o
+
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+ Don't assume that `.' is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses `./' if the program is built as
+part of the make or `$(srcdir)/' if the file is an unchanging part of
+the source code. Without one of these prefixes, the current search
+path is used.
+
+ The distinction between `./' (the "build directory") and
+`$(srcdir)/' (the "source directory") is important because users can
+build in a separate directory using the `--srcdir' option to
+`configure'. A rule of the form:
+
+ foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+
+will fail when the build directory is not the source directory, because
+`foo.man' and `sedscript' are in the source directory.
+
+ When using GNU `make', relying on `VPATH' to find the source file
+will work in the case where there is a single dependency file, since
+the `make' automatic variable `$<' will represent the source file
+wherever it is. (Many versions of `make' set `$<' only in implicit
+rules.) A Makefile target like
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow `VPATH' to work correctly. When the target has
+multiple dependencies, using an explicit `$(srcdir)' is the easiest way
+to make the rule work well. For example, the target above for `foo.1'
+is best written as:
+
+ foo.1 : foo.man sedscript
+ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+ GNU distributions usually contain some files which are not source
+files--for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
+
+ However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+ Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel `make'.
+
+
+File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
+
+7.2.2 Utilities in Makefiles
+----------------------------
+
+Write the Makefile commands (and any shell scripts, such as
+`configure') to run in `sh', not in `csh'. Don't use any special
+features of `ksh' or `bash'.
+
+ The `configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+ cat cmp cp diff echo egrep expr false grep install-info
+ ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+ The compression program `gzip' can be used in the `dist' rule.
+
+ Stick to the generally supported options for these programs. For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+ It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+ The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via `make' variables
+so that the user can substitute alternatives. Here are some of the
+programs we mean:
+
+ ar bison cc flex install ld ldconfig lex
+ make makeinfo ranlib texi2dvi yacc
+
+ Use the following `make' variables to run those programs:
+
+ $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+ $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+ When you use `ranlib' or `ldconfig', you should make sure nothing
+bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
+
+ If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+ Additional utilities that can be used via Make variables are:
+
+ chgrp chmod chown mknod
+
+ It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+
+File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions
+
+7.2.3 Variables for Specifying Commands
+---------------------------------------
+
+Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+ In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named `BISON' whose default
+value is set with `BISON = bison', and refer to it with `$(BISON)'
+whenever you need to use Bison.
+
+ File management utilities such as `ln', `rm', `mv', and so on, need
+not be referred to through variables in this way, since users don't
+need to replace them with other programs.
+
+ Each program-name variable should come with an options variable that
+is used to supply options to the program. Append `FLAGS' to the
+program-name variable name to get the options variable name--for
+example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
+`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
+but we keep them because they are standard.) Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+ If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in `CFLAGS'. Users
+expect to be able to specify `CFLAGS' freely themselves. Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+ CFLAGS = -g
+ ALL_CFLAGS = -I. $(CFLAGS)
+ .c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+ Do include the `-g' option in `CFLAGS', because that is not
+_required_ for proper compilation. You can consider it a default that
+is only recommended. If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+ Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+ `CFLAGS' should be used in every invocation of the C compiler, both
+those which do compilation and those which do linking.
+
+ Every Makefile should define the variable `INSTALL', which is the
+basic command for installing a file into the system.
+
+ Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
+`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
+644'.) Then it should use those variables as the commands for actual
+installation, for executables and non-executables respectively.
+Minimal use of these variables is as follows:
+
+ $(INSTALL_PROGRAM) foo $(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+ However, it is preferable to support a `DESTDIR' prefix on the
+target files, as explained in the next section.
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
+
+
+File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions
+
+7.2.4 `DESTDIR': support for staged installs
+--------------------------------------------
+
+`DESTDIR' is a variable prepended to each installed target file, like
+this:
+
+ $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+ The `DESTDIR' variable is specified by the user on the `make'
+command line. For example:
+
+ make DESTDIR=/tmp/stage install
+
+`DESTDIR' should be supported only in the `install*' and `uninstall*'
+targets, as those are the only targets where it is useful.
+
+ If your installation step would normally install
+`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
+installation invoked as in the example above would install
+`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
+instead.
+
+ Prepending the variable `DESTDIR' to each target in this way
+provides for "staged installs", where the installed files are not
+placed directly into their expected location but are instead copied
+into a temporary location (`DESTDIR'). However, installed files
+maintain their relative directory structure and any embedded file names
+will not be modified.
+
+ You should not set the value of `DESTDIR' in your `Makefile' at all;
+then the files are installed into their expected locations by default.
+Also, specifying `DESTDIR' should not change the operation of the
+software in any way, so its value should not be included in any file
+contents.
+
+ `DESTDIR' support is commonly used in package creation. It is also
+helpful to users who want to understand what a given package will
+install where, and to allow users who don't normally have permissions
+to install into protected areas to build and install before gaining
+those permissions. Finally, it can be useful with tools such as
+`stow', where code is installed in one place but made to appear to be
+installed somewhere else using symbolic links or special mount
+operations. So, we strongly recommend GNU packages support `DESTDIR',
+though it is not an absolute requirement.
+
+
+File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions
+
+7.2.5 Variables for Installation Directories
+--------------------------------------------
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place. The standard names for these
+variables and the values they should have in GNU packages are described
+below. They are based on a standard file system layout; variants of it
+are used in GNU/Linux and other modern operating systems.
+
+ Installers are expected to override these values when calling `make'
+(e.g., `make prefix=/usr install' or `configure' (e.g., `configure
+--prefix=/usr'). GNU packages should not try to guess which value
+should be appropriate for these variables on the system they are being
+installed onto: use the default settings specified here so that all GNU
+packages behave identically, allowing the installer to achieve any
+desired layout.
+
+ These first two variables set the root for the installation. All the
+other installation directories should be subdirectories of one of these
+two, and nothing should be directly installed into these two
+directories.
+
+`prefix'
+ A prefix used in constructing the default values of the variables
+ listed below. The default value of `prefix' should be
+ `/usr/local'. When building the complete GNU system, the prefix
+ will be empty and `/usr' will be a symbolic link to `/'. (If you
+ are using Autoconf, write it as `@prefix@'.)
+
+ Running `make install' with a different value of `prefix' from the
+ one used to build the program should _not_ recompile the program.
+
+`exec_prefix'
+ A prefix used in constructing the default values of some of the
+ variables listed below. The default value of `exec_prefix' should
+ be `$(prefix)'. (If you are using Autoconf, write it as
+ `@exec_prefix@'.)
+
+ Generally, `$(exec_prefix)' is used for directories that contain
+ machine-specific files (such as executables and subroutine
+ libraries), while `$(prefix)' is used directly for other
+ directories.
+
+ Running `make install' with a different value of `exec_prefix'
+ from the one used to build the program should _not_ recompile the
+ program.
+
+ Executable programs are installed in one of the following
+directories.
+
+`bindir'
+ The directory for installing executable programs that users can
+ run. This should normally be `/usr/local/bin', but write it as
+ `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
+ `@bindir@'.)
+
+`sbindir'
+ The directory for installing executable programs that can be run
+ from the shell, but are only generally useful to system
+ administrators. This should normally be `/usr/local/sbin', but
+ write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
+ write it as `@sbindir@'.)
+
+`libexecdir'
+ The directory for installing executable programs to be run by other
+ programs rather than by users. This directory should normally be
+ `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+ (If you are using Autoconf, write it as `@libexecdir@'.)
+
+ The definition of `libexecdir' is the same for all packages, so
+ you should install your data in a subdirectory thereof. Most
+ packages install their data under `$(libexecdir)/PACKAGE-NAME/',
+ possibly within additional subdirectories thereof, such as
+ `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
+
+ Data files used by the program during its execution are divided into
+categories in two ways.
+
+ * Some files are normally modified by programs; others are never
+ normally modified (though users may edit some of these).
+
+ * Some files are architecture-independent and can be shared by all
+ machines at a site; some are architecture-dependent and can be
+ shared only by machines of the same kind and operating system;
+ others may never be shared between two machines.
+
+ This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+ Here are the variables Makefiles should use to specify directories
+to put these various kinds of files in:
+
+`datarootdir'
+ The root of the directory tree for read-only
+ architecture-independent data files. This should normally be
+ `/usr/local/share', but write it as `$(prefix)/share'. (If you
+ are using Autoconf, write it as `@datarootdir@'.) `datadir''s
+ default value is based on this variable; so are `infodir',
+ `mandir', and others.
+
+`datadir'
+ The directory for installing idiosyncratic read-only
+ architecture-independent data files for this program. This is
+ usually the same place as `datarootdir', but we use the two
+ separate variables so that you can move these program-specific
+ files without altering the location for Info files, man pages, etc.
+
+ This should normally be `/usr/local/share', but write it as
+ `$(datarootdir)'. (If you are using Autoconf, write it as
+ `@datadir@'.)
+
+ The definition of `datadir' is the same for all packages, so you
+ should install your data in a subdirectory thereof. Most packages
+ install their data under `$(datadir)/PACKAGE-NAME/'.
+
+`sysconfdir'
+ The directory for installing read-only data files that pertain to a
+ single machine-that is to say, files for configuring a host.
+ Mailer and network configuration files, `/etc/passwd', and so
+ forth belong here. All the files in this directory should be
+ ordinary ASCII text files. This directory should normally be
+ `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
+ using Autoconf, write it as `@sysconfdir@'.)
+
+ Do not install executables here in this directory (they probably
+ belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
+ files that are modified in the normal course of their use (programs
+ whose purpose is to change the configuration of the system
+ excluded). Those probably belong in `$(localstatedir)'.
+
+`sharedstatedir'
+ The directory for installing architecture-independent data files
+ which the programs modify while they run. This should normally be
+ `/usr/local/com', but write it as `$(prefix)/com'. (If you are
+ using Autoconf, write it as `@sharedstatedir@'.)
+
+`localstatedir'
+ The directory for installing data files which the programs modify
+ while they run, and that pertain to one specific machine. Users
+ should never need to modify files in this directory to configure
+ the package's operation; put such configuration information in
+ separate files that go in `$(datadir)' or `$(sysconfdir)'.
+ `$(localstatedir)' should normally be `/usr/local/var', but write
+ it as `$(prefix)/var'. (If you are using Autoconf, write it as
+ `@localstatedir@'.)
+
+ These variables specify the directory for installing certain specific
+types of files, if your program has them. Every GNU package should
+have Info files, so every program needs `infodir', but not all need
+`libdir' or `lispdir'.
+
+`includedir'
+ The directory for installing header files to be included by user
+ programs with the C `#include' preprocessor directive. This
+ should normally be `/usr/local/include', but write it as
+ `$(prefix)/include'. (If you are using Autoconf, write it as
+ `@includedir@'.)
+
+ Most compilers other than GCC do not look for header files in
+ directory `/usr/local/include'. So installing the header files
+ this way is only useful with GCC. Sometimes this is not a problem
+ because some libraries are only really intended to work with GCC.
+ But some libraries are intended to work with other compilers.
+ They should install their header files in two places, one
+ specified by `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+ The directory for installing `#include' header files for use with
+ compilers other than GCC. This should normally be `/usr/include'.
+ (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+ The Makefile commands should check whether the value of
+ `oldincludedir' is empty. If it is, they should not try to use
+ it; they should cancel the second installation of the header files.
+
+ A package should not replace an existing header in this directory
+ unless the header came from the same package. Thus, if your Foo
+ package provides a header file `foo.h', then it should install the
+ header file in the `oldincludedir' directory if either (1) there
+ is no `foo.h' there or (2) the `foo.h' that exists came from the
+ Foo package.
+
+ To tell whether `foo.h' came from the Foo package, put a magic
+ string in the file--part of a comment--and `grep' for that string.
+
+`docdir'
+ The directory for installing documentation files (other than Info)
+ for this package. By default, it should be
+ `/usr/local/share/doc/YOURPKG', but it should be written as
+ `$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write
+ it as `@docdir@'.) The YOURPKG subdirectory, which may include a
+ version number, prevents collisions among files with common names,
+ such as `README'.
+
+`infodir'
+ The directory for installing the Info files for this package. By
+ default, it should be `/usr/local/share/info', but it should be
+ written as `$(datarootdir)/info'. (If you are using Autoconf,
+ write it as `@infodir@'.) `infodir' is separate from `docdir' for
+ compatibility with existing practice.
+
+`htmldir'
+`dvidir'
+`pdfdir'
+`psdir'
+ Directories for installing documentation files in the particular
+ format. They should all be set to `$(docdir)' by default. (If
+ you are using Autoconf, write them as `@htmldir@', `@dvidir@',
+ etc.) Packages which supply several translations of their
+ documentation should install them in `$(htmldir)/'LL,
+ `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
+ `en' or `pt_BR'.
+
+`libdir'
+ The directory for object files and libraries of object code. Do
+ not install executables here, they probably ought to go in
+ `$(libexecdir)' instead. The value of `libdir' should normally be
+ `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
+ are using Autoconf, write it as `@libdir@'.)
+
+`lispdir'
+ The directory for installing any Emacs Lisp files in this package.
+ By default, it should be `/usr/local/share/emacs/site-lisp', but
+ it should be written as `$(datarootdir)/emacs/site-lisp'.
+
+ If you are using Autoconf, write the default as `@lispdir@'. In
+ order to make `@lispdir@' work, you need the following lines in
+ your `configure.in' file:
+
+ lispdir='${datarootdir}/emacs/site-lisp'
+ AC_SUBST(lispdir)
+
+`localedir'
+ The directory for installing locale-specific message catalogs for
+ this package. By default, it should be `/usr/local/share/locale',
+ but it should be written as `$(datarootdir)/locale'. (If you are
+ using Autoconf, write it as `@localedir@'.) This directory
+ usually has a subdirectory per locale.
+
+ Unix-style man pages are installed in one of the following:
+
+`mandir'
+ The top-level directory for installing the man pages (if any) for
+ this package. It will normally be `/usr/local/share/man', but you
+ should write it as `$(datarootdir)/man'. (If you are using
+ Autoconf, write it as `@mandir@'.)
+
+`man1dir'
+ The directory for installing section 1 man pages. Write it as
+ `$(mandir)/man1'.
+
+`man2dir'
+ The directory for installing section 2 man pages. Write it as
+ `$(mandir)/man2'
+
+`...'
+ *Don't make the primary documentation for any GNU software be a
+ man page. Write a manual in Texinfo instead. Man pages are just
+ for the sake of people running GNU software on Unix, which is a
+ secondary application only.*
+
+`manext'
+ The file name extension for the installed man page. This should
+ contain a period followed by the appropriate digit; it should
+ normally be `.1'.
+
+`man1ext'
+ The file name extension for installed section 1 man pages.
+
+`man2ext'
+ The file name extension for installed section 2 man pages.
+
+`...'
+ Use these names instead of `manext' if the package needs to
+ install man pages in more than one section of the manual.
+
+ And finally, you should set the following variable:
+
+`srcdir'
+ The directory for the sources being compiled. The value of this
+ variable is normally inserted by the `configure' shell script.
+ (If you are using Autoconf, use `srcdir = @srcdir@'.)
+
+ For example:
+
+ # Common prefix for installation directories.
+ # NOTE: This directory must exist when you start the install.
+ prefix = /usr/local
+ datarootdir = $(prefix)/share
+ datadir = $(datarootdir)
+ exec_prefix = $(prefix)
+ # Where to put the executable for the command `gcc'.
+ bindir = $(exec_prefix)/bin
+ # Where to put the directories used by the compiler.
+ libexecdir = $(exec_prefix)/libexec
+ # Where to put the Info files.
+ infodir = $(datarootdir)/info
+
+ If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the `install' rule to create these subdirectories.
+
+ Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above. The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+ At times, not all of these variables may be implemented in the
+current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
+believe all of them are. When any are missing, the descriptions here
+serve as specifications for what Autoconf will implement. As a
+programmer, you can either use a development version of Autoconf or
+avoid using these variables until a stable release is made which
+supports them.
+
+
+File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
+
+7.2.6 Standard Targets for Users
+--------------------------------
+
+All GNU programs should have the following targets in their Makefiles:
+
+`all'
+ Compile the entire program. This should be the default target.
+ This target need not rebuild any documentation files; Info files
+ should normally be included in the distribution, and DVI (and other
+ documentation format) files should be made only when explicitly
+ asked for.
+
+ By default, the Make rules should compile and link with `-g', so
+ that executable programs have debugging symbols. Users who don't
+ mind being helpless can strip the executables later if they wish.
+
+`install'
+ Compile the program and copy the executables, libraries, and so on
+ to the file names where they should reside for actual use. If
+ there is a simple test to verify that a program is properly
+ installed, this target should run that test.
+
+ Do not strip executables when installing them. Devil-may-care
+ users can use the `install-strip' target to do that.
+
+ If possible, write the `install' target rule so that it does not
+ modify anything in the directory where the program was built,
+ provided `make all' has just been done. This is convenient for
+ building the program under one user name and installing it under
+ another.
+
+ The commands should create all the directories in which files are
+ to be installed, if they don't already exist. This includes the
+ directories specified as the values of the variables `prefix' and
+ `exec_prefix', as well as all subdirectories that are needed. One
+ way to do this is by means of an `installdirs' target as described
+ below.
+
+ Use `-' before any command for installing a man page, so that
+ `make' will ignore any errors. This is in case there are systems
+ that don't have the Unix man page documentation system installed.
+
+ The way to install Info files is to copy them into `$(infodir)'
+ with `$(INSTALL_DATA)' (*note Command Variables::), and then run
+ the `install-info' program if it is present. `install-info' is a
+ program that edits the Info `dir' file to add or update the menu
+ entry for the given Info file; it is part of the Texinfo package.
+ Here is a sample rule to install an Info file:
+
+ $(DESTDIR)$(infodir)/foo.info: foo.info
+ $(POST_INSTALL)
+ # There may be a newer info file in . than in srcdir.
+ -if test -f foo.info; then d=.; \
+ else d=$(srcdir); fi; \
+ $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
+ # Run install-info only if it exists.
+ # Use `if' instead of just prepending `-' to the
+ # line so we notice real errors from install-info.
+ # We use `$(SHELL) -c' because some shells do not
+ # fail gracefully when there is an unknown command.
+ if $(SHELL) -c 'install-info --version' \
+ >/dev/null 2>&1; then \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/foo.info; \
+ else true; fi
+
+ When writing the `install' target, you must classify all the
+ commands into three categories: normal ones, "pre-installation"
+ commands and "post-installation" commands. *Note Install Command
+ Categories::.
+
+`install-html'
+`install-dvi'
+`install-pdf'
+`install-ps'
+ These targets install documentation in formats other than Info;
+ they're intended to be called explicitly by the person installing
+ the package, if that format is desired. GNU prefers Info files,
+ so these must be installed by the `install' target.
+
+ When you have many documentation files to install, we recommend
+ that you avoid collisions and clutter by arranging for these
+ targets to install in subdirectories of the appropriate
+ installation directory, such as `htmldir'. As one example, if
+ your package has multiple manuals, and you wish to install HTML
+ documentation with many files (such as the "split" mode output by
+ `makeinfo --html'), you'll certainly want to use subdirectories,
+ or two nodes with the same name in different manuals will
+ overwrite each other.
+
+ Please make these `install-FORMAT' targets invoke the commands for
+ the FORMAT target, for example, by making FORMAT a dependency.
+
+`uninstall'
+ Delete all the installed files--the copies that the `install' and
+ `install-*' targets create.
+
+ This rule should not modify the directories where compilation is
+ done, only the directories where files are installed.
+
+ The uninstallation commands are divided into three categories,
+ just like the installation commands. *Note Install Command
+ Categories::.
+
+`install-strip'
+ Like `install', but strip the executable files while installing
+ them. In simple cases, this target can use the `install' target in
+ a simple way:
+
+ install-strip:
+ $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+ install
+
+ But if the package installs scripts as well as real executables,
+ the `install-strip' target can't just refer to the `install'
+ target; it has to strip the executables but not the scripts.
+
+ `install-strip' should not strip the executables in the build
+ directory which are being copied for installation. It should only
+ strip the copies that are installed.
+
+ Normally we do not recommend stripping an executable unless you
+ are sure the program has no bugs. However, it can be reasonable
+ to install a stripped executable for actual execution while saving
+ the unstripped executable elsewhere in case there is a bug.
+
+`clean'
+ Delete all files in the current directory that are normally
+ created by building the program. Also delete files in other
+ directories if they are created by this makefile. However, don't
+ delete the files that record the configuration. Also preserve
+ files that could be made by building, but normally aren't because
+ the distribution comes with them. There is no need to delete
+ parent directories that were created with `mkdir -p', since they
+ could have existed anyway.
+
+ Delete `.dvi' files here if they are not part of the distribution.
+
+`distclean'
+ Delete all files in the current directory (or created by this
+ makefile) that are created by configuring or building the program.
+ If you have unpacked the source and built the program without
+ creating any other files, `make distclean' should leave only the
+ files that were in the distribution. However, there is no need to
+ delete parent directories that were created with `mkdir -p', since
+ they could have existed anyway.
+
+`mostlyclean'
+ Like `clean', but may refrain from deleting a few files that people
+ normally don't want to recompile. For example, the `mostlyclean'
+ target for GCC does not delete `libgcc.a', because recompiling it
+ is rarely necessary and takes a lot of time.
+
+`maintainer-clean'
+ Delete almost everything that can be reconstructed with this
+ Makefile. This typically includes everything deleted by
+ `distclean', plus more: C source files produced by Bison, tags
+ tables, Info files, and so on.
+
+ The reason we say "almost everything" is that running the command
+ `make maintainer-clean' should not delete `configure' even if
+ `configure' can be remade using a rule in the Makefile. More
+ generally, `make maintainer-clean' should not delete anything that
+ needs to exist in order to run `configure' and then begin to build
+ the program. Also, there is no need to delete parent directories
+ that were created with `mkdir -p', since they could have existed
+ anyway. These are the only exceptions; `maintainer-clean' should
+ delete everything else that can be rebuilt.
+
+ The `maintainer-clean' target is intended to be used by a
+ maintainer of the package, not by ordinary users. You may need
+ special tools to reconstruct some of the files that `make
+ maintainer-clean' deletes. Since these files are normally
+ included in the distribution, we don't take care to make them easy
+ to reconstruct. If you find you need to unpack the full
+ distribution again, don't blame us.
+
+ To help make users aware of this, the commands for the special
+ `maintainer-clean' target should start with these two:
+
+ @echo 'This command is intended for maintainers to use; it'
+ @echo 'deletes files that may need special tools to rebuild.'
+
+`TAGS'
+ Update a tags table for this program.
+
+`info'
+ Generate any Info files needed. The best way to write the rules
+ is as follows:
+
+ info: foo.info
+
+ foo.info: foo.texi chap1.texi chap2.texi
+ $(MAKEINFO) $(srcdir)/foo.texi
+
+ You must define the variable `MAKEINFO' in the Makefile. It should
+ run the `makeinfo' program, which is part of the Texinfo
+ distribution.
+
+ Normally a GNU distribution comes with Info files, and that means
+ the Info files are present in the source directory. Therefore,
+ the Make rule for an info file should update it in the source
+ directory. When users build the package, ordinarily Make will not
+ update the Info files because they will already be up to date.
+
+`dvi'
+`html'
+`pdf'
+`ps'
+ Generate documentation files in the given format. These targets
+ should always exist, but any or all can be a no-op if the given
+ output format cannot be generated. These targets should not be
+ dependencies of the `all' target; the user must manually invoke
+ them.
+
+ Here's an example rule for generating DVI files from Texinfo:
+
+ dvi: foo.dvi
+
+ foo.dvi: foo.texi chap1.texi chap2.texi
+ $(TEXI2DVI) $(srcdir)/foo.texi
+
+ You must define the variable `TEXI2DVI' in the Makefile. It should
+ run the program `texi2dvi', which is part of the Texinfo
+ distribution.(1) Alternatively, write just the dependencies, and
+ allow GNU `make' to provide the command.
+
+ Here's another example, this one for generating HTML from Texinfo:
+
+ html: foo.html
+
+ foo.html: foo.texi chap1.texi chap2.texi
+ $(TEXI2HTML) $(srcdir)/foo.texi
+
+ Again, you would define the variable `TEXI2HTML' in the Makefile;
+ for example, it might run `makeinfo --no-split --html' (`makeinfo'
+ is part of the Texinfo distribution).
+
+`dist'
+ Create a distribution tar file for this program. The tar file
+ should be set up so that the file names in the tar file start with
+ a subdirectory name which is the name of the package it is a
+ distribution for. This name can include the version number.
+
+ For example, the distribution tar file of GCC version 1.40 unpacks
+ into a subdirectory named `gcc-1.40'.
+
+ The easiest way to do this is to create a subdirectory
+ appropriately named, use `ln' or `cp' to install the proper files
+ in it, and then `tar' that subdirectory.
+
+ Compress the tar file with `gzip'. For example, the actual
+ distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
+
+ The `dist' target should explicitly depend on all non-source files
+ that are in the distribution, to make sure they are up to date in
+ the distribution. *Note Making Releases: Releases.
+
+`check'
+ Perform self-tests (if any). The user must build the program
+ before running the tests, but need not install the program; you
+ should write the self-tests so that they work when the program is
+ built but not installed.
+
+ The following targets are suggested as conventional names, for
+programs in which they are useful.
+
+`installcheck'
+ Perform installation tests (if any). The user must build and
+ install the program before running the tests. You should not
+ assume that `$(bindir)' is in the search path.
+
+`installdirs'
+ It's useful to add a target named `installdirs' to create the
+ directories where files are installed, and their parent
+ directories. There is a script called `mkinstalldirs' which is
+ convenient for this; you can find it in the Texinfo package. You
+ can use a rule like this:
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+ $(libdir) $(infodir) \
+ $(mandir)
+
+ or, if you wish to support `DESTDIR',
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs \
+ $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+ $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+ $(DESTDIR)$(mandir)
+
+ This rule should not modify the directories where compilation is
+ done. It should do nothing but create installation directories.
+
+ ---------- Footnotes ----------
+
+ (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
+not distributed with Texinfo.
+
+
+File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
+
+7.2.7 Install Command Categories
+--------------------------------
+
+When writing the `install' target, you must classify all the commands
+into three categories: normal ones, "pre-installation" commands and
+"post-installation" commands.
+
+ Normal commands move files into their proper places, and set their
+modes. They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+ Pre-installation and post-installation commands may alter other
+files; in particular, they can edit global configuration files or data
+bases.
+
+ Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+ The most common use for a post-installation command is to run
+`install-info'. This cannot be done with a normal command, since it
+alters a file (the Info directory) which does not come entirely and
+solely from the package being installed. It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+ Most programs don't need any pre-installation commands, but we have
+the feature just in case it is needed.
+
+ To classify the commands in the `install' rule into these three
+categories, insert "category lines" among them. A category line
+specifies the category for the commands that follow.
+
+ A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end. There are three
+variables you can use, one for each category; the variable name
+specifies the category. Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+_should not_ define them in the makefile).
+
+ Here are the three possible category lines, each with a comment that
+explains what it means:
+
+ $(PRE_INSTALL) # Pre-install commands follow.
+ $(POST_INSTALL) # Post-install commands follow.
+ $(NORMAL_INSTALL) # Normal commands follow.
+
+ If you don't use a category line at the beginning of the `install'
+rule, all the commands are classified as normal until the first category
+line. If you don't use any category lines, all the commands are
+classified as normal.
+
+ These are the category lines for `uninstall':
+
+ $(PRE_UNINSTALL) # Pre-uninstall commands follow.
+ $(POST_UNINSTALL) # Post-uninstall commands follow.
+ $(NORMAL_UNINSTALL) # Normal commands follow.
+
+ Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+ If the `install' or `uninstall' target has any dependencies which
+act as subroutines of installation, then you should start _each_
+dependency's commands with a category line, and start the main target's
+commands with a category line also. This way, you can ensure that each
+command is placed in the right category regardless of which of the
+dependencies actually run.
+
+ Pre-installation and post-installation commands should not run any
+programs except for these:
+
+ [ basename bash cat chgrp chmod chown cmp cp dd diff echo
+ egrep expand expr false fgrep find getopt grep gunzip gzip
+ hostname install install-info kill ldconfig ln ls md5sum
+ mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+ test touch true uname xargs yes
+
+ The reason for distinguishing the commands in this way is for the
+sake of making binary packages. Typically a binary package contains
+all the executables and other files that need to be installed, and has
+its own method of installing them--so it does not need to run the normal
+installation commands. But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+ Programs to build binary packages work by extracting the
+pre-installation and post-installation commands. Here is one way of
+extracting the pre-installation commands (the `-s' option to `make' is
+needed to silence messages about entering subdirectories):
+
+ make -s -n install -o all \
+ PRE_INSTALL=pre-install \
+ POST_INSTALL=post-install \
+ NORMAL_INSTALL=normal-install \
+ | gawk -f pre-install.awk
+
+where the file `pre-install.awk' could contain this:
+
+ $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
+ on {print $0}
+ $0 ~ /^pre-install[ \t]*$/ {on = 1}
+
+
+File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
+
+7.3 Making Releases
+===================
+
+You should identify each release with a pair of version numbers, a
+major version and a minor. We have no objection to using more than two
+numbers, but it is very unlikely that you really need them.
+
+ Package the distribution of `Foo version 69.96' up in a gzipped tar
+file with the name `foo-69.96.tar.gz'. It should unpack into a
+subdirectory named `foo-69.96'.
+
+ Building and installing the program should never modify any of the
+files contained in the distribution. This means that all the files
+that form part of the program in any way must be classified into "source
+files" and "non-source files". Source files are written by humans and
+never changed automatically; non-source files are produced from source
+files by programs under the control of the Makefile.
+
+ The distribution should contain a file named `README' which gives
+the name of the package, and a general description of what it does. It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any. The `README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+ The `README' file should refer to the file `INSTALL', which should
+contain an explanation of the installation procedure.
+
+ The `README' file should also refer to the file which contains the
+copying conditions. The GNU GPL, if used, should be in a file called
+`COPYING'. If the GNU LGPL is used, it should be in a file called
+`COPYING.LIB'.
+
+ Naturally, all the source files must be in the distribution. It is
+okay to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them. We commonly include non-source files
+produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+ Non-source files that might actually be modified by building and
+installing the program should *never* be included in the distribution.
+So if you do distribute non-source files, always make sure they are up
+to date when you make a new distribution.
+
+ Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of `tar' which preserve the ownership and
+permissions of the files from the tar archive will be able to extract
+all the files even if the user is unprivileged.
+
+ Make sure that all the files in the distribution are world-readable.
+
+ Don't include any symbolic links in the distribution itself. If the
+tar file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the distribution.
+
+ Try to make sure that all the file names will be unique on MS-DOS. A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters. MS-DOS will truncate extra
+characters both before and after the period. Thus, `foobarhacker.c'
+and `foobarhacker.o' are not ambiguous; they are truncated to
+`foobarha.c' and `foobarha.o', which are distinct.
+
+ Include in your distribution a copy of the `texinfo.tex' you used to
+test print any `*.texinfo' or `*.texi' files.
+
+ Likewise, if your program uses small GNU software packages like
+regex, getopt, obstack, or termcap, include them in the distribution
+file. Leaving them out would make the distribution file a little
+smaller at the expense of possible inconvenience to a user who doesn't
+know what other files to get.
+
+
+File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Releases, Up: Top
+
+8 References to Non-Free Software and Documentation
+***************************************************
+
+A GNU program should not recommend use of any non-free program. We
+can't stop some people from writing proprietary programs, or stop other
+people from using them, but we can and should refuse to advertise them
+to new potential customers. Proprietary software is a social and
+ethical problem, and the point of GNU is to solve that problem.
+
+ The GNU definition of free software is found on the GNU web site at
+`http://www.gnu.org/philosophy/free-sw.html', and the definition of
+free documentation is found at
+`http://www.gnu.org/philosophy/free-doc.html'. A list of important
+licenses and whether they qualify as free is in
+`http://www.gnu.org/licenses/license-list.html'. The terms "free" and
+"non-free", used in this document, refer to that definition. If it is
+not clear whether a license qualifies as free under this definition,
+please ask the GNU Project by writing to <licensing@gnu.org>. We will
+answer, and if the license is an important one, we will add it to the
+list.
+
+ When a non-free program or system is well known, you can mention it
+in passing--that is harmless, since users who might want to use it
+probably already know about it. For instance, it is fine to explain
+how to build your package on top of some widely used non-free operating
+system, or how to use it together with some widely used non-free
+program.
+
+ However, you should give only the necessary information to help those
+who already use the non-free program to use your program with it--don't
+give, or refer to, any further information about the proprietary
+program, and don't imply that the proprietary program enhances your
+program, or that its existence is in any way a good thing. The goal
+should be that people already using the proprietary program will get
+the advice they need about how to use your free program with it, while
+people who don't already use the proprietary program will not see
+anything to lead them to take an interest in it.
+
+ If a non-free program or system is obscure in your program's domain,
+your program should not mention or support it at all, since doing so
+would tend to popularize the non-free program more than it popularizes
+your program. (You cannot hope to find many additional users among the
+users of Foobar if the users of Foobar are few.)
+
+ Sometimes a program is free software in itself but depends on a
+non-free platform in order to run. For instance, many Java programs
+depend on the parts of Sun's Java implementation which are not yet free
+software, and won't run on the GNU Java Compiler (which does not yet
+have all the features) or won't run with the GNU Java libraries. We
+hope this particular problem will be gone in a few months, when Sun
+makes the standard Java libraries free software, but of course the
+general principle remains: you should not recommend programs that
+depend on non-free software to run.
+
+ Some free programs encourage the use of non-free software. A typical
+example is `mplayer'. It is free software in itself, and the free code
+can handle some kinds of files. However, `mplayer' recommends use of
+non-free codecs for other kinds of files, and users that install
+`mplayer' are very likely to install those codecs along with it. To
+recommend `mplayer' is, in effect, to recommend the non-free codecs.
+We must not do that, so we cannot recommend `mplayer' either.
+
+ In general, you should also not recommend programs that themselves
+strongly recommend the use of non-free software.
+
+ A GNU package should not refer the user to any non-free documentation
+for free software. Free documentation that can be included in free
+operating systems is essential for completing the GNU system, or any
+free operating system, so it is a major focus of the GNU Project; to
+recommend use of documentation that we are not allowed to use in GNU
+would weaken the impetus for the community to produce documentation
+that we can include. So GNU packages should never recommend non-free
+documentation.
+
+ By contrast, it is ok to refer to journal articles and textbooks in
+the comments of a program for explanation of how it functions, even
+though they be non-free. This is because we don't include such things
+in the GNU system even if we are allowed to--they are outside the scope
+of an operating system project.
+
+ Referring to a web site that describes or recommends a non-free
+program is in effect promoting that software, so please do not make
+links (or mention by name) web sites that contain such material. This
+policy is relevant particularly for the web pages for a GNU package.
+
+ Following links from nearly any web site can lead to non-free
+software; this is an inescapable aspect of the nature of the web, and
+in itself is no objection to linking to a site. As long as the site
+does not itself recommend a non-free program, there is no need be
+concerned about the sites it links to for other reasons.
+
+ Thus, for example, you should not make a link to AT&T's web site,
+because that recommends AT&T's non-free software packages; you should
+not make a link to a site that links to AT&T's site saying it is a
+place to get a non-free program; but if a site you want to link to
+refers to AT&T's web site in some other context (such as long-distance
+telephone service), that is not a problem.
+
+
+File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: Top
+
+Appendix A GNU Free Documentation License
+*****************************************
+
+ Version 1.2, November 2002
+
+ Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the
+ author and publisher a way to get credit for their work, while not
+ being considered responsible for modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book.
+ We recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it
+ can be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ "Document", below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as "you". You
+ accept the license if you copy, modify or distribute the work in a
+ way requiring permission under copyright law.
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in
+ the notice that says that the Document is released under this
+ License. If a section does not fit the above definition of
+ Secondary then it is not allowed to be designated as Invariant.
+ The Document may contain zero Invariant Sections. If the Document
+ does not identify any Invariant Sections then there are none.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images
+ composed of pixels) generic paint programs or (for drawings) some
+ widely available drawing editor, and that is suitable for input to
+ text formatters or for automatic translation to a variety of
+ formats suitable for input to text formatters. A copy made in an
+ otherwise Transparent file format whose markup, or absence of
+ markup, has been arranged to thwart or discourage subsequent
+ modification by readers is not Transparent. An image format is
+ not Transparent if used for any substantial amount of text. A
+ copy that is not "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML, PostScript or PDF designed for
+ human modification. Examples of transparent image formats include
+ PNG, XCF and JPG. Opaque formats include proprietary formats that
+ can be read and edited only by proprietary word processors, SGML or
+ XML for which the DTD and/or processing tools are not generally
+ available, and the machine-generated HTML, PostScript or PDF
+ produced by some word processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ A section "Entitled XYZ" means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ "Acknowledgements", "Dedications", "Endorsements", or "History".)
+ To "Preserve the Title" of such a section when you modify the
+ Document means that it remains a section "Entitled XYZ" according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow
+ the conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the
+ title equally prominent and visible. You may add other material
+ on the covers in addition. Copying with changes limited to the
+ covers, as long as they preserve the title of the Document and
+ satisfy these conditions, can be treated as verbatim copying in
+ other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a
+ machine-readable Transparent copy along with each Opaque copy, or
+ state in or with each Opaque copy a computer-network location from
+ which the general network-using public has access to download
+ using public-standard network protocols a complete Transparent
+ copy of the Document, free of added material. If you use the
+ latter option, you must take reasonably prudent steps, when you
+ begin distribution of Opaque copies in quantity, to ensure that
+ this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you
+ distribute an Opaque copy (directly or through your agents or
+ retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of
+ copies, to give them a chance to provide you with an updated
+ version of the Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with
+ the Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version to
+ whoever possesses a copy of it. In addition, you must do these
+ things in the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of
+ previous versions (which should, if there were any, be listed
+ in the History section of the Document). You may use the
+ same title as a previous version if the original publisher of
+ that version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has fewer than five), unless they release you
+ from this requirement.
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section Entitled "History", Preserve its Title,
+ and add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on
+ the Title Page. If there is no section Entitled "History" in
+ the Document, create one stating the title, year, authors,
+ and publisher of the Document as given on its Title Page,
+ then add an item describing the Modified Version as stated in
+ the previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in
+ the "History" section. You may omit a network location for a
+ work that was published at least four years before the
+ Document itself, or if the original publisher of the version
+ it refers to gives permission.
+
+ K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the
+ section all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section
+ titles.
+
+ M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section to be Entitled
+ "Endorsements" or to conflict in title with any Invariant
+ Section.
+
+ O. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option
+ designate some or all of these sections as invariant. To do this,
+ add their titles to the list of Invariant Sections in the Modified
+ Version's license notice. These titles must be distinct from any
+ other section titles.
+
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end
+ of the list of Cover Texts in the Modified Version. Only one
+ passage of Front-Cover Text and one of Back-Cover Text may be
+ added by (or through arrangements made by) any one entity. If the
+ Document already includes a cover text for the same cover,
+ previously added by you or by arrangement made by the same entity
+ you are acting on behalf of, you may not add another; but you may
+ replace the old one, on explicit permission from the previous
+ publisher that added the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination
+ all of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ "History" in the various original documents, forming one section
+ Entitled "History"; likewise combine any sections Entitled
+ "Acknowledgements", and any sections Entitled "Dedications". You
+ must delete all sections Entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the
+ documents in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow
+ this License in all other respects regarding verbatim copying of
+ that document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of
+ a storage or distribution medium, is called an "aggregate" if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation's users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document's Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided for under this License. Any other
+ attempt to copy, modify, sublicense or distribute the Document is
+ void, and will automatically terminate your rights under this
+ License. However, parties who have received copies, or rights,
+ from you under this License will not have their licenses
+ terminated so long as such parties remain in full compliance.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ `http://www.gnu.org/copyleft/'.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by the
+ Free Software Foundation.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ being LIST.
+
+ If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* #endif, commenting: Comments. (line 60)
+* --help output: --help. (line 6)
+* --version output: --version. (line 6)
+* -Wall compiler option: Syntactic Conventions.
+ (line 10)
+* accepting contributions: Contributions. (line 6)
+* address for bug reports: --help. (line 11)
+* ANSI C standard: Standard C. (line 6)
+* arbitrary limits on data: Semantics. (line 6)
+* ASCII characters: Character Set. (line 6)
+* autoconf: System Portability. (line 23)
+* avoiding proprietary code: Reading Non-Free Code.
+ (line 6)
+* behavior, dependent on program's name: User Interfaces. (line 6)
+* binary packages: Install Command Categories.
+ (line 80)
+* bindir: Directory Variables. (line 54)
+* braces, in C source: Formatting. (line 6)
+* bug reports: --help. (line 11)
+* canonical name of a program: --version. (line 12)
+* casting pointers to integers: CPU Portability. (line 90)
+* CGI programs, standard options for: Command-Line Interfaces.
+ (line 31)
+* change logs: Change Logs. (line 6)
+* change logs, conditional changes: Conditional Changes. (line 6)
+* change logs, style: Style of Change Logs.
+ (line 6)
+* character set: Character Set. (line 6)
+* command-line arguments, decoding: Semantics. (line 46)
+* command-line interface: Command-Line Interfaces.
+ (line 6)
+* commenting: Comments. (line 6)
+* compatibility with C and POSIX standards: Compatibility. (line 6)
+* compiler warnings: Syntactic Conventions.
+ (line 10)
+* conditional changes, and change logs: Conditional Changes. (line 6)
+* conditionals, comments for: Comments. (line 60)
+* configure: Configuration. (line 6)
+* control-L: Formatting. (line 118)
+* conventions for makefiles: Makefile Conventions.
+ (line 6)
+* corba: Graphical Interfaces.
+ (line 16)
+* credits for manuals: Manual Credits. (line 6)
+* data types, and portability: CPU Portability. (line 6)
+* declaration for system functions: System Functions. (line 21)
+* DESTDIR: DESTDIR. (line 6)
+* documentation: Documentation. (line 6)
+* doschk: Names. (line 38)
+* downloading this manual: Preface. (line 17)
+* encodings: Character Set. (line 6)
+* error messages: Semantics. (line 19)
+* error messages, formatting: Errors. (line 6)
+* exec_prefix: Directory Variables. (line 36)
+* expressions, splitting: Formatting. (line 81)
+* FDL, GNU Free Documentation License: GNU Free Documentation License.
+ (line 6)
+* file usage: File Usage. (line 6)
+* file-name limitations: Names. (line 38)
+* formatting error messages: Errors. (line 6)
+* formatting source code: Formatting. (line 6)
+* formfeed: Formatting. (line 118)
+* function argument, declaring: Syntactic Conventions.
+ (line 6)
+* function prototypes: Standard C. (line 17)
+* getopt: Command-Line Interfaces.
+ (line 6)
+* gettext: Internationalization.
+ (line 6)
+* gnome: Graphical Interfaces.
+ (line 16)
+* graphical user interface: Graphical Interfaces.
+ (line 6)
+* grave accent: Quote Characters. (line 6)
+* gtk+: Graphical Interfaces.
+ (line 6)
+* GUILE: Source Language. (line 38)
+* implicit int: Syntactic Conventions.
+ (line 6)
+* impossible conditions: Semantics. (line 70)
+* installations, staged: DESTDIR. (line 6)
+* internationalization: Internationalization.
+ (line 6)
+* left quote: Quote Characters. (line 6)
+* legal aspects: Legal Issues. (line 6)
+* legal papers: Contributions. (line 6)
+* libexecdir: Directory Variables. (line 67)
+* libraries: Libraries. (line 6)
+* library functions, and portability: System Functions. (line 6)
+* license for manuals: License for Manuals. (line 6)
+* lint: Syntactic Conventions.
+ (line 109)
+* locale-specific quote characters: Quote Characters. (line 6)
+* long option names: Option Table. (line 6)
+* long-named options: Command-Line Interfaces.
+ (line 12)
+* makefile, conventions for: Makefile Conventions.
+ (line 6)
+* malloc return value: Semantics. (line 25)
+* man pages: Man Pages. (line 6)
+* manual structure: Manual Structure Details.
+ (line 6)
+* memory allocation failure: Semantics. (line 25)
+* memory usage: Memory Usage. (line 6)
+* message text, and internationalization: Internationalization.
+ (line 29)
+* mmap: Mmap. (line 6)
+* multiple variables in a line: Syntactic Conventions.
+ (line 35)
+* names of variables, functions, and files: Names. (line 6)
+* NEWS file: NEWS File. (line 6)
+* non-ASCII characters: Character Set. (line 6)
+* non-POSIX systems, and portability: System Portability. (line 32)
+* non-standard extensions: Using Extensions. (line 6)
+* NUL characters: Semantics. (line 11)
+* open brace: Formatting. (line 6)
+* optional features, configure-time: Configuration. (line 83)
+* options for compatibility: Compatibility. (line 14)
+* options, standard command-line: Command-Line Interfaces.
+ (line 31)
+* output device and program's behavior: User Interfaces. (line 13)
+* packaging: Releases. (line 6)
+* PATH_INFO, specifying standard options as: Command-Line Interfaces.
+ (line 31)
+* portability, and data types: CPU Portability. (line 6)
+* portability, and library functions: System Functions. (line 6)
+* portability, between system types: System Portability. (line 6)
+* POSIX compatibility: Compatibility. (line 6)
+* POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
+* post-installation commands: Install Command Categories.
+ (line 6)
+* pre-installation commands: Install Command Categories.
+ (line 6)
+* prefix: Directory Variables. (line 26)
+* program configuration: Configuration. (line 6)
+* program design: Design Advice. (line 6)
+* program name and its behavior: User Interfaces. (line 6)
+* program's canonical name: --version. (line 12)
+* programming languages: Source Language. (line 6)
+* proprietary programs: Reading Non-Free Code.
+ (line 6)
+* quote characters: Quote Characters. (line 6)
+* README file: Releases. (line 21)
+* references to non-free material: References. (line 6)
+* releasing: Managing Releases. (line 6)
+* sbindir: Directory Variables. (line 60)
+* signal handling: Semantics. (line 59)
+* spaces before open-paren: Formatting. (line 75)
+* staged installs: DESTDIR. (line 6)
+* standard command-line options: Command-Line Interfaces.
+ (line 31)
+* standards for makefiles: Makefile Conventions.
+ (line 6)
+* string library functions: System Functions. (line 55)
+* syntactic conventions: Syntactic Conventions.
+ (line 6)
+* table of long options: Option Table. (line 6)
+* temporary files: Semantics. (line 84)
+* temporary variables: Syntactic Conventions.
+ (line 23)
+* texinfo.tex, in a distribution: Releases. (line 70)
+* TMPDIR environment variable: Semantics. (line 84)
+* trademarks: Trademarks. (line 6)
+* where to obtain standards.texi: Preface. (line 17)
+
+
+
+Tag Table:
+Node: Top797
+Node: Preface2053
+Node: Legal Issues4168
+Node: Reading Non-Free Code4638
+Node: Contributions6368
+Node: Trademarks8606
+Node: Design Advice10241
+Node: Source Language10833
+Node: Compatibility12845
+Node: Using Extensions14473
+Node: Standard C16049
+Node: Conditional Compilation18452
+Node: Program Behavior19850
+Node: Non-GNU Standards20906
+Node: Semantics23187
+Node: Libraries27906
+Node: Errors29151
+Node: User Interfaces31644
+Node: Graphical Interfaces33249
+Node: Command-Line Interfaces34285
+Node: --version36317
+Node: --help42210
+Node: Option Table42764
+Node: Memory Usage57705
+Node: File Usage58736
+Node: Writing C59486
+Node: Formatting60458
+Node: Comments64747
+Node: Syntactic Conventions68299
+Node: Names71761
+Node: System Portability73973
+Node: CPU Portability76863
+Node: System Functions80775
+Node: Internationalization85972
+Node: Character Set89966
+Node: Quote Characters90779
+Node: Mmap92299
+Node: Documentation93007
+Node: GNU Manuals94113
+Node: Doc Strings and Manuals99851
+Node: Manual Structure Details101404
+Node: License for Manuals102822
+Node: Manual Credits103796
+Node: Printed Manuals104189
+Node: NEWS File104875
+Node: Change Logs105553
+Node: Change Log Concepts106307
+Node: Style of Change Logs108396
+Node: Simple Changes110896
+Node: Conditional Changes112338
+Node: Indicating the Part Changed113760
+Node: Man Pages114287
+Node: Reading other Manuals116599
+Node: Managing Releases117390
+Node: Configuration118171
+Node: Makefile Conventions125891
+Node: Makefile Basics126773
+Node: Utilities in Makefiles129947
+Node: Command Variables132092
+Node: DESTDIR135314
+Node: Directory Variables137463
+Node: Standard Targets151956
+Ref: Standard Targets-Footnote-1165471
+Node: Install Command Categories165571
+Node: Releases170104
+Node: References174031
+Node: GNU Free Documentation License179526
+Node: Index201958
+
+End Tag Table
View Lorry Controller Status