X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=binutils%2Fbinutils.texi;h=535df3f6b8a0f0a16ec7119dd44e407e91e13631;hb=dd92f6397700e5478ae02b7dfad416181d04ef22;hp=c590e84fb06cacef0c3322e2d4f4d31c76d84c9c;hpb=10f2a7f6ac81c5e6af927c19773fc098bfed530e;p=deliverable%2Fbinutils-gdb.git

diff --git a/binutils/binutils.texi b/binutils/binutils.texi
index c590e84fb0..535df3f6b8 100644
--- a/binutils/binutils.texi
+++ b/binutils/binutils.texi
@@ -1,17 +1,19 @@
 \input texinfo       @c                    -*- Texinfo -*-
 @setfilename binutils.info
+@include config.texi
 
 @ifinfo
 @format
 START-INFO-DIR-ENTRY
-* Binutils::                    The GNU binary utilities "ar", "ld", "objcopy",
-				"objdump", "nm", "size", "strings", "strip", and "ranlib".
+* Binutils: (binutils).         The GNU binary utilities "ar", "objcopy",
+				"objdump", "nm", "nlmconv", "size", "readelf"
+                                "strings", "strip", "ranlib" and "dlltool".
 END-INFO-DIR-ENTRY
 @end format
 @end ifinfo
 
 @ifinfo
-Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -37,22 +39,20 @@ into another language, under the above conditions for modified versions.
 @synindex ky cp
 @c
 @c This file documents the GNU binary utilities "ar", "ld", "objcopy",
-@c  "objdump", "nm", "size", "strings", "strip", and "ranlib".
+@c  "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib".
 @c
-@c Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
+@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
 @c 
 @c This text may be freely distributed under the terms of the GNU
 @c General Public License.
 @c
 
 @setchapternewpage odd
-@settitle GNU Binary Utilities
-@c @smallbook
-@c @cropmarks
+@settitle @sc{gnu} Binary Utilities
 @titlepage
 @finalout
-@title The GNU Binary Utilities
-@subtitle Version 2.2
+@title The @sc{gnu} Binary Utilities
+@subtitle Version @value{VERSION}
 @sp 1
 @subtitle May 1993
 @author Roland H. Pesch
@@ -66,7 +66,7 @@ into another language, under the above conditions for modified versions.
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -82,12 +82,11 @@ into another language, under the above conditions for modified versions.
 @end titlepage
 
 @node Top
-@top
-@chapter Introduction
+@top Introduction
 
 @cindex version
-This brief manual contains preliminary documentation for the GNU binary
-utilities (collectively version 2.2): 
+This brief manual contains preliminary documentation for the @sc{gnu} binary
+utilities (collectively version @value{VERSION}): 
 
 @iftex
 @table @code
@@ -106,6 +105,9 @@ Display information from object files
 @item ranlib
 Generate index to archive contents
 
+@item readelf
+Display the contents of ELF format files.
+
 @item size
 List file section sizes and total size
 
@@ -118,8 +120,17 @@ Discard symbols
 @item c++filt
 Demangle encoded C++ symbols
 
+@item addr2line
+Convert addresses into file names and line numbers
+
 @item nlmconv
 Convert object code into a Netware Loadable Module
+
+@item windres
+Manipulate Windows resources
+
+@item dlltool
+Create the files needed to build and use Dynamic Link Libraries
 @end table
 @end iftex
 
@@ -129,13 +140,18 @@ Convert object code into a Netware Loadable Module
 * objcopy::			Copy and translate object files
 * objdump::                     Display information from object files
 * ranlib::                      Generate index to archive contents
+* readelf::			Display the contents of ELF format files.
 * size::                        List section sizes and total size
 * strings::                     List printable strings from files
 * strip::                       Discard symbols
 * c++filt::			Filter to demangle encoded C++ symbols
+* addr2line::			Convert addresses to file and line
 * nlmconv::                     Converts object code into an NLM
+* windres::			Manipulate Windows resources
+* dlltool::			Create files needed to build and use DLLs
 * Selecting The Target System:: How these utilities determine the target.
-* Index::                       
+* Reporting Bugs::              Reporting Bugs
+* Index::                       Index
 @end menu
 
 @node ar
@@ -149,7 +165,7 @@ ar [-]@var{p}[@var{mod} [@var{relpos}]] @var{archive} [@var{member}@dots{}]
 ar -M [ <mri-script ]
 @end smallexample
 
-The GNU @code{ar} program creates, modifies, and extracts from
+The @sc{gnu} @code{ar} program creates, modifies, and extracts from
 archives.  An @dfn{archive} is a single file holding a collection of
 other files in a structure that makes it possible to retrieve
 the original individual files (called @dfn{members} of the archive).
@@ -159,7 +175,7 @@ group are preserved in the archive, and can be restored on
 extraction.  
 
 @cindex name length
-GNU @code{ar} can maintain archives whose members have names of any
+@sc{gnu} @code{ar} can maintain archives whose members have names of any
 length; however, depending on how @code{ar} is configured on your
 system, a limit on member-name length may be imposed for compatibility
 with archive formats maintained with other tools.  If it exists, the
@@ -186,7 +202,7 @@ table.  If an archive lacks the table, another form of @code{ar} called
 
 @cindex compatibility, @code{ar}
 @cindex @code{ar} compatibility
-GNU @code{ar} is designed to be compatible with two different
+@sc{gnu} @code{ar} is designed to be compatible with two different
 facilities.  You can control its activity using command-line options,
 like the different varieties of @code{ar} on Unix systems; or, if you
 specify the single command-line option @samp{-M}, you can control it
@@ -215,7 +231,7 @@ arguments to execute: one keyletter specifying the @emph{operation}
 Most operations can also accept further @var{member} arguments,
 specifying particular files to operate on.
 
-GNU @code{ar} allows you to mix the operation code @var{p} and modifier
+@sc{gnu} @code{ar} allows you to mix the operation code @var{p} and modifier
 flags @var{mod} in any order, within the first command-line argument.
 
 If you wish, you may begin the first command-line argument with a
@@ -259,7 +275,7 @@ printed.
 
 @item q
 @cindex quick append to archive
-@emph{Quick append}; add the files @var{member}@dots{} to the end of
+@emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
 @var{archive}, without checking for replacement.
 
 The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
@@ -271,6 +287,9 @@ Since the point of this operation is speed, the archive's symbol table
 index is not updated, even if it already existed; you can use @samp{ar s} or
 @code{ranlib} explicitly to update the symbol table index.
 
+However, too many different systems assume quick append rebuilds the
+index, so GNU ar implements @code{q} as a synonym for @code{r}.
+
 @item r
 @cindex replacement in archive
 Insert the files @var{member}@dots{} into @var{archive} (with
@@ -346,6 +365,13 @@ created if it did not exist, when you request an update.  But a warning is
 issued unless you specify in advance that you expect to create it, by
 using this modifier.
 
+@item f
+Truncate names in the archive.  @sc{gnu} @code{ar} will normally permit file
+names of any length.  This will cause it to create archives which are
+not compatible with the native @code{ar} program on some systems.  If
+this is a concern, the @samp{f} modifier may be used to truncate file
+names when putting them in the archive.
+
 @item i
 Insert new files @emph{before} an existing member of the
 archive.  If you use the modifier @samp{i}, the name of an existing archive
@@ -355,7 +381,7 @@ member must be present as the @var{relpos} argument, before the
 @item l
 This modifier is accepted but not used.
 @c whaffor ar l modifier??? presumably compat; with
-@c what???---pesch@@cygnus.com, 25jan91 
+@c what???---doc@@cygnus.com, 25jan91 
 
 @item o
 @cindex dates in archive
@@ -370,6 +396,14 @@ even if no other change is made to the archive.  You may use this modifier
 flag either with any operation, or alone.  Running @samp{ar s} on an
 archive is equivalent to running @samp{ranlib} on it.
 
+@item S
+@cindex not writing archive index
+Do not generate an archive symbol table.  This can speed up building a
+large library in several steps.  The resulting archive can not be used
+with the linker.  In order to build a symbol table, you must omit the
+@samp{S} modifier on the last execution of @samp{ar}, or you must run
+@samp{ranlib} on the archive.
+
 @item u
 @cindex updating an archive
 Normally, @samp{ar r}@dots{} inserts all files
@@ -410,7 +444,7 @@ on any error.
 The @code{ar} command language is @emph{not} designed to be equivalent
 to the command-line options; in fact, it provides somewhat less control
 over archives.  The only purpose of the command language is to ease the
-transition to GNU @code{ar} for developers who already have scripts
+transition to @sc{gnu} @code{ar} for developers who already have scripts
 written for the MRI ``librarian'' program.
 
 The syntax for the @code{ar} command language is straightforward:
@@ -468,7 +502,7 @@ Add each named @var{member} as a module in the current archive.
 Requires prior use of @code{OPEN} or @code{CREATE}.
 
 @item CLEAR
-Discard the contents of the current archive, cancelling the effect of
+Discard the contents of the current archive, canceling the effect of
 any operations since the last @code{SAVE}.  May be executed (with no
 effect) even if  no current archive is specified.
 
@@ -520,7 +554,7 @@ Requires prior use of @code{OPEN} or @code{CREATE}.
 @item LIST
 Display full contents of the current archive, in ``verbose'' style
 regardless of the state of @code{VERBOSE}.  The effect is like @samp{ar
-tv @var{archive}}).  (This single command is a GNU @code{ld}
+tv @var{archive}}.  (This single command is a @sc{gnu} @code{ar}
 enhancement, rather than present for MRI compatibility.)
 
 Requires prior use of @code{OPEN} or @code{CREATE}.
@@ -557,8 +591,8 @@ Requires prior use of @code{OPEN} or @code{CREATE}.
 @chapter ld
 @cindex linker
 @kindex ld
-The GNU linker @code{ld} is now described in a separate manual.
-@xref{Top,, Overview,, Using LD: the GNU linker}.
+The @sc{gnu} linker @code{ld} is now described in a separate manual.
+@xref{Top,, Overview,, Using LD: the @sc{gnu} linker}.
 @end iftex
 
 @node nm
@@ -568,16 +602,17 @@ The GNU linker @code{ld} is now described in a separate manual.
 
 @smallexample
 nm [ -a | --debug-syms ]  [ -g | --extern-only ]
-   [ -B ]  [ -C | --demangle ]
-   [ -s | --print-armap ]  [ -A | -o | --print-file-name ]  
+   [ -B ]  [ -C | --demangle ] [ -D | --dynamic ]
+   [ -s | --print-armap ]  [ -A | -o | --print-file-name ]
    [ -n | -v | --numeric-sort ]  [ -p | --no-sort ]
-   [ -r | --reverse-sort ]  [ -u | --undefined-only ]  
+   [ -r | --reverse-sort ]  [ --size-sort ] [ -u | --undefined-only ]
    [ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
    [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
-   [ -V | --version ]  [ --help ]  [ @var{objfile}@dots{} ]
+   [ --defined-only ] [-l | --line-numbers ]
+   [ --no-demangle ] [ -V | --version ]  [ --help ]  [ @var{objfile}@dots{} ]
 @end smallexample
 
-GNU @code{nm} lists the symbols from object files @var{objfile}@dots{}.
+@sc{gnu} @code{nm} lists the symbols from object files @var{objfile}@dots{}.
 If no object files are listed as arguments, @code{nm} assumes
 @file{a.out}.
 
@@ -597,25 +632,61 @@ local; if uppercase, the symbol is global (external).
 @c would be nice.
 @table @code
 @item A
-Absolute.
+The symbol's value is absolute, and will not be changed by further
+linking.
 
 @item B
-BSS (uninitialized data).
+The symbol is in the uninitialized data section (known as BSS).
 
 @item C
-Common.
+The symbol is common.  Common symbols are uninitialized data.  When
+linking, multiple common symbols may appear with the same name.  If the
+symbol is defined anywhere, the common symbols are treated as undefined
+references.  For more details on common symbols, see the discussion of
+--warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
 
 @item D
-Initialized data.
+The symbol is in the initialized data section.
+
+@item G
+The symbol is in an initialized data section for small objects.  Some
+object file formats permit more efficient access to small data objects,
+such as a global int variable as opposed to a large global array.
 
 @item I
-Indirect reference.
+The symbol is an indirect reference to another symbol.  This is a GNU
+extension to the a.out object file format which is rarely used.
+
+@item N
+The symbol is a debugging symbol.
+
+@item R
+The symbol is in a read only data section.
+
+@item S
+The symbol is in an uninitialized data section for small objects.
 
 @item T
-Text (program code).
+The symbol is in the text (code) section.
 
 @item U
-Undefined.
+The symbol is undefined.
+
+@item W
+The symbol is weak.  When a weak defined symbol is linked with a normal
+defined symbol, the normal defined symbol is used with no error.  When a
+weak undefined symbol is linked and the symbol is not defined, the value
+of the weak symbol becomes zero with no error.
+
+@item -
+The symbol is a stabs symbol in an a.out object file.  In this case, the
+next values printed are the stabs other field, the stabs desc field, and
+the stab type.  Stabs symbols are used to hold debugging information;
+for more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The
+``stabs'' debug format}.
+
+@item ?
+The symbol type is unknown, or object file format specific.
 @end table
 
 @item
@@ -649,12 +720,22 @@ The same as @samp{--format=bsd} (for compatibility with the MIPS @code{nm}).
 
 @item -C
 @itemx --demangle
-@cindex demangling C++ symbols
+@cindex demangling in nm
 Decode (@dfn{demangle}) low-level symbol names into user-level names.
 Besides removing any initial underscore prepended by the system, this
 makes C++ function names readable.  @xref{c++filt}, for more information
 on demangling.
 
+@item --no-demangle
+Do not demangle low-level symbol names.  This is the default.
+
+@item -D
+@itemx --dynamic
+@cindex dynamic symbols
+Display the dynamic symbols rather than the normal symbols.  This is
+only meaningful for dynamic objects, such as certain types of shared
+libraries.
+
 @item -f @var{format}
 @itemx --format=@var{format}
 @cindex @code{nm} format
@@ -669,6 +750,15 @@ either upper or lower case.
 @cindex external symbols
 Display only external symbols.
 
+@item -l
+@itemx --line-numbers
+@cindex symbol line numbers
+For each symbol, use debugging information to try to find a filename and
+line number.  For a defined symbol, look for the line number of the
+address of the symbol.  For an undefined symbol, look for the line
+number of a relocation entry which refers to the symbol.  If line number
+information can be found, print it after the other symbol information.
+
 @item -n
 @itemx -v
 @itemx --numeric-sort 
@@ -698,6 +788,11 @@ contain definitions for which names.
 Reverse the order of the sort (whether numeric or alphabetic); let the
 last come first.
 
+@item --size-sort
+Sort symbols by size.  The size is computed as the difference between
+the value of the symbol and the value of the symbol with the next higher
+value.  The size of the symbol is printed, rather than the value.
+
 @item -t @var{radix}
 @itemx --radix=@var{radix}
 Use @var{radix} as the radix for printing the symbol values.  It must be
@@ -714,6 +809,11 @@ Specify an object code format other than your system's default format.
 @cindex undefined symbols
 Display only undefined symbols (those external to each object file).
 
+@item --defined-only
+@cindex external symbols
+@cindex undefined symbols
+Display only defined symbols for each object file.
+
 @item -V
 @itemx --version
 Show the version number of @code{nm} and exit.
@@ -730,32 +830,65 @@ objcopy [ -F @var{bfdname} | --target=@var{bfdname} ]
         [ -I @var{bfdname} | --input-target=@var{bfdname} ]
         [ -O @var{bfdname} | --output-target=@var{bfdname} ]
         [ -S | --strip-all ]  [ -g | --strip-debug ]
+        [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
+        [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
+        [ -L @var{symbolname} | --localize-symbol=@var{symbolname} ]
+        [ -W @var{symbolname} | --weaken-symbol=@var{symbolname} ]
         [ -x | --discard-all ]  [ -X | --discard-locals ]
         [ -b @var{byte} | --byte=@var{byte} ]
         [ -i @var{interleave} | --interleave=@var{interleave} ]
+        [ -j @var{sectionname} | --only-section=@var{sectionname} ]
+        [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
+        [ -p | --preserve-dates ] [ --debugging ]
+        [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ]
+        [ --set-start=@var{val} ] [ --adjust-start=@var{incr} ]
+        [ --change-addresses=@var{incr} ]
+        [ --change-section-address=@var{section}@{=,+,-@}@var{val} ]
+        [ --change-section-lma=@var{section}@{=,+,-@}@var{val} ]
+        [ --change-section-vma=@var{section}@{=,+,-@}@var{val} ]
+        [ --change-warnings ] [ --no-change-warnings ]
+        [ --set-section-flags=@var{section}=@var{flags} ]
+        [ --add-section=@var{sectionname}=@var{filename} ]
+        [ --change-leading-char ] [ --remove-leading-char ]
+        [ --weaken ]
         [ -v | --verbose ] [ -V | --version ]  [ --help ]
         @var{infile} [@var{outfile}]
 @end smallexample
 
-The GNU @code{objcopy} utility copies the contents of an object file to
-another.  @code{objcopy} uses the GNU BFD Library to read and write the
-object files.  It can write the destination object file in a format
-different from that of the source object file.  The exact behavior of
-@code{objcopy} is controlled by command-line options.
+The @sc{gnu} @code{objcopy} utility copies the contents of an object
+file to another.  @code{objcopy} uses the @sc{gnu} @sc{bfd} Library to
+read and write the object files.  It can write the destination object
+file in a format different from that of the source object file.  The
+exact behavior of @code{objcopy} is controlled by command-line options.
 
 @code{objcopy} creates temporary files to do its translations and
-deletes them afterward.  @code{objcopy} uses BFD to do all its
-translation work; it knows about all the formats BFD knows about, and
-thus is able to recognize most formats without being told explicitly.
-@xref{BFD,,BFD,ld.info,Using LD}.
+deletes them afterward.  @code{objcopy} uses @sc{bfd} to do all its
+translation work; it has access to all the formats described in @sc{bfd}
+and thus is able to recognize most formats without being told
+explicitly.  @xref{BFD,,BFD,ld.info,Using LD}.
+
+@code{objcopy} can be used to generate S-records by using an output
+target of @samp{srec} (e.g., use @samp{-O srec}).
+
+@code{objcopy} can be used to generate a raw binary file by using an
+output target of @samp{binary} (e.g., use @samp{-O binary}).  When
+@code{objcopy} generates a raw binary file, it will essentially produce
+a memory dump of the contents of the input object file.  All symbols and
+relocation information will be discarded.  The memory dump will start at
+the load address of the lowest section copied into the output file.
+
+When generating an S-record or a raw binary file, it may be helpful to
+use @samp{-S} to remove sections containing debugging information.  In
+some cases @samp{-R} will be useful to remove sections which contain
+information which is not needed by the binary file.
 
 @table @code
 @item @var{infile}
 @itemx @var{outfile}
-The source and output files respectively.
+The source and output files, respectively.
 If you do not specify @var{outfile}, @code{objcopy} creates a
 temporary file and destructively renames the result with
-the name of the input file.
+the name of @var{infile}.
 
 @item -I @var{bfdname}	
 @itemx --input-target=@var{bfdname}
@@ -773,6 +906,18 @@ Use @var{bfdname} as the object format for both the input and the output
 file; i.e., simply transfer data from source to destination with no
 translation.  @xref{Target Selection}, for more information.
 
+@item -j @var{sectionname}
+@itemx --only-section=@var{sectionname}
+Copy only the named section from the input file to the output file.
+This option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.
+
+@item -R @var{sectionname}
+@itemx --remove-section=@var{sectionname}
+Remove any section named @var{sectionname} from the output file.  This
+option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.
+
 @item -S
 @itemx --strip-all
 Do not copy relocation and symbol information from the source file.
@@ -781,6 +926,28 @@ Do not copy relocation and symbol information from the source file.
 @itemx --strip-debug
 Do not copy debugging symbols from the source file.
 
+@item --strip-unneeded
+Strip all symbols that are not needed for relocation processing.
+
+@item -K @var{symbolname}
+@itemx --keep-symbol=@var{symbolname}
+Copy only symbol @var{symbolname} from the source file.  This option may
+be given more than once.
+
+@item -N @var{symbolname}
+@itemx --strip-symbol=@var{symbolname}
+Do not copy symbol @var{symbolname} from the source file.  This option
+may be given more than once.
+
+@item -L @var{symbolname}
+@itemx --localize-symbol=@var{symbolname}
+Make symbol @var{symbolname} local to the file, so that it is not
+visible externally.  This option may be given more than once.
+
+@item -W @var{symbolname}
+@itemx --weaken-symbol=@var{symbolname}
+Make symbol @var{symbolname} weak. This option may be given more than once.
+
 @item -x
 @itemx --discard-all
 Do not copy non-global symbols from the source file.
@@ -797,14 +964,148 @@ Keep only every @var{byte}th byte of the input file (header data is not
 affected).  @var{byte} can be in the range from 0 to @var{interleave}-1,
 where @var{interleave} is given by the @samp{-i} or @samp{--interleave}
 option, or the default of 4.  This option is useful for creating files
-to program ROMs.  It is typically used with an @code{srec} output
+to program @sc{rom}.  It is typically used with an @code{srec} output
 target.
 
 @item -i @var{interleave}
 @itemx --interleave=@var{interleave}
-Only copy one out of every @var{interleave} bytes.  Which one to copy is
-selected by the @var{-b} or @samp{--byte} option.  The default is 4.
-The interleave is ignored if neither @samp{-b} nor @samp{--byte} is given.
+Only copy one out of every @var{interleave} bytes.  Select which byte to
+copy with the @var{-b} or @samp{--byte} option.  The default is 4.
+@code{objcopy} ignores this option if you do not specify either @samp{-b} or
+@samp{--byte}.
+
+@item -p
+@itemx --preserve-dates
+Set the access and modification dates of the output file to be the same
+as those of the input file.
+
+@item --debugging
+Convert debugging information, if possible.  This is not the default
+because only certain debugging formats are supported, and the
+conversion process can be time consuming.
+
+@item --gap-fill @var{val}
+Fill gaps between sections with @var{val}.  This operation applies to
+the @emph{load address} (LMA) of the sections.  It is done by increasing
+the size of the section with the lower address, and filling in the extra
+space created with @var{val}.
+
+@item --pad-to @var{address}
+Pad the output file up to the load address @var{address}.  This is
+done by increasing the size of the last section.  The extra space is
+filled in with the value specified by @samp{--gap-fill} (default zero).
+
+@item --set-start @var{val}
+Set the address of the new file to @var{val}.  Not all object file
+formats support setting the start address.
+
+@item --change-start @var{incr}
+@itemx --adjust-start @var{incr}
+@cindex changing start address
+Change the start address by adding @var{incr}.  Not all object file
+formats support setting the start address.
+
+@item --change-addresses @var{incr}
+@itemx --adjust-vma @var{incr}
+@cindex changing object addresses
+Change the VMA and LMA addresses of all sections, as well as the start
+address, by adding @var{incr}.  Some object file formats do not permit
+section addresses to be changed arbitrarily.  Note that this does not
+relocate the sections; if the program expects sections to be loaded at a
+certain address, and this option is used to change the sections such
+that they are loaded at a different address, the program may fail. 
+
+@item --change-section-address @var{section}@{=,+,-@}@var{val}
+@itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val}
+@cindex changing section address
+Set or change both the VMA address and the LMA address of the named
+@var{section}.  If @samp{=} is used, the section address is set to
+@var{val}.  Otherwise, @var{val} is added to or subtracted from the
+section address.  See the comments under @samp{--change-addresses},
+above. If @var{section} does not exist in the input file, a warning will
+be issued, unless @samp{--no-change-warnings} is used.
+
+@item --change-section-lma @var{section}@{=,+,-@}@var{val}
+@cindex changing section LMA
+Set or change the LMA address of the named @var{section}.  The LMA
+address is the address where the section will be loaded into memory at
+program load time.  Normally this is the same as the VMA address, which
+is the address of the section at program run time, but on some systems,
+especially those where a program is held in ROM, the two can be
+different.  If @samp{=} is used, the section address is set to
+@var{val}.  Otherwise, @var{val} is added to or subtracted from the
+section address.  See the comments under @samp{--change-addresses},
+above.  If @var{section} does not exist in the input file, a warning
+will be issued, unless @samp{--no-change-warnings} is used.  
+
+@item --change-section-vma @var{section}@{=,+,-@}@var{val}
+@cindex changing section VMA
+Set or change the VMA address of the named @var{section}.  The VMA
+address is the address where the section will be located once the
+program has started executing.  Normally this is the same as the LMA
+address, which is the address where the section will be loaded into
+memory, but on some systems, especially those where a program is held in
+ROM, the two can be different.  If @samp{=} is used, the section address
+is set to @var{val}.  Otherwise, @var{val} is added to or subtracted
+from the section address.  See the comments under
+@samp{--change-addresses}, above.  If @var{section} does not exist in
+the input file, a warning will be issued, unless
+@samp{--no-change-warnings} is used.   
+
+@item --change-warnings
+@itemx --adjust-warnings
+If @samp{--change-section-address} or @samp{--change-section-lma} or
+@samp{--change-section-vma} is used, and the named section does not
+exist, issue a warning.  This is the default. 
+
+@item --no-change-warnings
+@itemx --no-adjust-warnings
+Do not issue a warning if @samp{--change-section-address} or
+@samp{--adjust-section-lma} or @samp{--adjust-section-vma} is used, even
+if the named section does not exist. 
+
+@item --set-section-flags @var{section}=@var{flags}
+Set the flags for the named section.  The @var{flags} argument is a
+comma separated string of flag names.  The recognized names are
+@samp{alloc}, @samp{contents}, @samp{load}, @samp{readonly},
+@samp{code}, @samp{data}, and @samp{rom}.  You can set the
+@samp{contents} flag for a section which does not have contents, but it
+is not meaningful to clear the @samp{contents} flag of a section which
+does have contents--just remove the section instead.  Not all flags are
+meaningful for all object file formats.
+
+@item --add-section @var{sectionname}=@var{filename}
+Add a new section named @var{sectionname} while copying the file.  The
+contents of the new section are taken from the file @var{filename}.  The
+size of the section will be the size of the file.  This option only
+works on file formats which can support sections with arbitrary names.
+
+@item --change-leading-char
+Some object file formats use special characters at the start of
+symbols.  The most common such character is underscore, which compilers
+often add before every symbol.  This option tells @code{objcopy} to
+change the leading character of every symbol when it converts between
+object file formats.  If the object file formats use the same leading
+character, this option has no effect.  Otherwise, it will add a
+character, or remove a character, or change a character, as
+appropriate.
+
+@item --remove-leading-char
+If the first character of a global symbol is a special symbol leading
+character used by the object file format, remove the character.  The
+most common symbol leading character is underscore.  This option will
+remove a leading underscore from all global symbols.  This can be useful
+if you want to link together objects of different file formats with
+different conventions for symbol names.  This is different from
+@code{--change-leading-char} because it always changes the symbol name
+when appropriate, regardless of the object file format of the output
+file.
+
+@item --weaken
+Change all global symbols in the file to be weak.  This can be useful
+when building an object which will be linked against other objects using
+the @code{-R} option to the linker.  This option is only effective when
+using an object file format which supports weak symbols.
 
 @item -V
 @itemx --version
@@ -827,14 +1128,25 @@ Show a summary of the options to @code{objcopy}.
 
 @smallexample
 objdump [ -a | --archive-headers ] 
-        [ -b @var{bfdname} | --target=@var{bfdname} ]
-        [ -d | --disassemble ]  [ -f | --file-headers ]
+        [ -b @var{bfdname} | --target=@var{bfdname} ] [ --debugging ]
+        [ -C | --demangle ] [ -d | --disassemble ]
+        [ -D | --disassemble-all ] [ --disassemble-zeroes ]
+        [ -EB | -EL | --endian=@{big | little @} ]
+        [ -f | --file-headers ]
         [ -h | --section-headers | --headers ]  [ -i | --info ]
         [ -j @var{section} | --section=@var{section} ]
-        [ -l | --line-numbers ]
-        [ -m @var{machine} | --architecture=@var{machine} ]  [ -r | --reloc ]
-        [ -s | --full-contents ]  [ --stabs ] [ -t | --syms ]
-        [ -x | --all-headers ]  [ --version ]  [ --help ]
+        [ -l | --line-numbers ] [ -S | --source ]
+        [ -m @var{machine} | --architecture=@var{machine} ]
+        [ -M @var{options} | --disassembler-options=@var{options}]
+        [ -p | --private-headers ]
+        [ -r | --reloc ] [ -R | --dynamic-reloc ]
+        [ -s | --full-contents ]  [ --stabs ]
+        [ -t | --syms ] [ -T | --dynamic-syms ] [ -x | --all-headers ]
+        [ -w | --wide ] [ --start-address=@var{address} ]
+        [ --stop-address=@var{address} ]
+        [ --prefix-addresses] [ --[no-]show-raw-insn ]
+        [ --adjust-vma=@var{offset} ]
+        [ --version ]  [ --help ]
         @var{objfile}@dots{}
 @end smallexample
 
@@ -860,6 +1172,15 @@ header information (in a format similar to @samp{ls -l}).  Besides the
 information you could list with @samp{ar tv}, @samp{objdump -a} shows
 the object file format of each archive member.
 
+@item --adjust-vma=@var{offset}
+@cindex section addresses in objdump
+@cindex VMA in objdump
+When dumping information, first add @var{offset} to all the section
+addresses.  This is useful if the section addresses do not correspond to
+the symbol table, which can happen when putting sections at particular
+addresses when using a format which can not represent section addresses,
+such as a.out.
+
 @item -b @var{bfdname}
 @itemx --target=@var{bfdname}
 @cindex object code format
@@ -878,12 +1199,49 @@ file in the format produced by Oasys compilers.  You can list the
 formats available with the @samp{-i} option.
 @xref{Target Selection}, for more information.
 
+@item -C
+@itemx --demangle
+@cindex demangling in objdump
+Decode (@dfn{demangle}) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes C++ function names readable.  @xref{c++filt}, for more information
+on demangling.
+
+@item --debugging
+Display debugging information.  This attempts to parse debugging
+information stored in the file and print it out using a C like syntax.
+Only certain types of debugging information have been implemented.
+
 @item -d
 @itemx --disassemble
 @cindex disassembling object code
 @cindex machine instructions
-Display the assembler mnemonics for the machine
-instructions from @var{objfile}.
+Display the assembler mnemonics for the machine instructions from
+@var{objfile}.  This option only disassembles those sections which are
+expected to contain instructions.
+
+@item -D
+@itemx --disassemble-all
+Like @samp{-d}, but disassemble the contents of all sections, not just
+those expected to contain instructions.
+
+@item --prefix-addresses
+When disassembling, print the complete address on each line.  This is
+the older disassembly format.
+
+@item --disassemble-zeroes
+Normally the disassembly output will skip blocks of zeroes.  This
+option directs the disassembler to disassemble those blocks, just like
+any other data.
+
+@item -EB
+@itemx -EL
+@itemx --endian=@{big|little@}
+@cindex endianness
+@cindex disassembly endianness
+Specify the endianness of the object files.  This only affects
+disassembly.  This can be useful when disassembling a file format which
+does not describe endianness information, such as S-records.
 
 @item -f
 @itemx --file-header
@@ -925,21 +1283,53 @@ Display information only for section @var{name}.
 @item -l
 @itemx --line-numbers
 @cindex source filenames for object files
-Label the display (using debugging information) with the filename
-and source line numbers corresponding to the object code shown.
-Only useful with @samp{-d}.
+Label the display (using debugging information) with the filename and
+source line numbers corresponding to the object code or relocs shown.
+Only useful with @samp{-d}, @samp{-D}, or @samp{-r}.
 
 @item -m @var{machine}
 @itemx --architecture=@var{machine}
 @cindex architecture
-Specify that the object files @var{objfile} are for architecture
-@var{machine}.  You can list available architectures using the @samp{-i}
-option. 
+@cindex disassembly architecture
+Specify the architecture to use when disassembling object files.  This
+can be useful when disassembling object files which do not describe
+architecture information, such as S-records.  You can list the available
+architectures with the @samp{-i} option.
+
+@item -M @var{options}
+@itemx --disassembler-options=@var{options}
+Pass target specific information to the disassembler.  Only supported on
+some targets.
+
+If the target is an ARM architecture then this switch can be used to
+select which register name set is used during disassembler.  Specifying
+@samp{--disassembler-options=reg-name-std} (the default) will select the
+register names as used in ARM's instruction set documentation, but with
+register 13 called 'sp', register 14 called 'lr' and register 15 called
+'pc'.  Specifying @samp{--disassembler-options=reg-names-apcs} will
+select the name set used by the ARM Procedure Call Standard, whilst
+specifying @samp{--disassembler-options=reg-names-raw} will just use
+@samp{r} followed by the register number.
+
+@item -p
+@itemx --private-headers
+Print information that is specific to the object file format.  The exact
+information printed depends upon the object file format.  For some
+object file formats, no additional information is printed.
 
 @item -r
 @itemx --reloc
 @cindex relocation entries, in object file
-Print the relocation entries of the file.
+Print the relocation entries of the file.  If used with @samp{-d} or
+@samp{-D}, the relocations are printed interspersed with the
+disassembly.
+
+@item -R
+@itemx --dynamic-reloc
+@cindex dynamic relocation entries, in object file
+Print the dynamic relocation entries of the file.  This is only
+meaningful for dynamic objects, such as certain types of shared
+libraries.
 
 @item -s
 @itemx --full-contents
@@ -947,6 +1337,22 @@ Print the relocation entries of the file.
 @cindex object file sections
 Display the full contents of any sections requested.
 
+@item -S
+@itemx --source
+@cindex source disassembly
+@cindex disassembly, with source
+Display source code intermixed with disassembly, if possible.  Implies
+@samp{-d}.
+
+@item --show-raw-insn
+When disassembling instructions, print the instruction in hex as well as
+in symbolic form.  This is the default except when
+@code{--prefix-addresses} is used.
+
+@item --no-show-raw-insn
+When disassembling instructions, do not print the instruction bytes.
+This is the default when @code{--prefix-addresses} is used.
+
 @item --stabs
 @cindex stab
 @cindex .stab
@@ -958,7 +1364,18 @@ ELF file.  This is only useful on systems (such as Solaris 2.0) in which
 @code{.stab} debugging symbol-table entries are carried in an ELF
 section.  In most other file formats, debugging symbol-table entries are
 interleaved with linkage symbols, and are visible in the @samp{--syms}
-output.
+output.  For more information on stabs symbols, see @ref{Top,Stabs,Stabs
+Overview,stabs.info, The ``stabs'' debug format}.
+
+@item --start-address=@var{address}
+@cindex start-address
+Start displaying data at the specified address.  This affects the output
+of the @code{-d}, @code{-r} and @code{-s} options.
+
+@item --stop-address=@var{address}
+@cindex stop-address
+Stop displaying data at the specified address.  This affects the output
+of the @code{-d}, @code{-r} and @code{-s} options.
 
 @item -t
 @itemx --syms
@@ -966,6 +1383,14 @@ output.
 Print the symbol table entries of the file.
 This is similar to the information provided by the @samp{nm} program.
 
+@item -T
+@itemx --dynamic-syms
+@cindex dynamic symbol table entries, printing
+Print the dynamic symbol table entries of the file.  This is only
+meaningful for dynamic objects, such as certain types of shared
+libraries.  This is similar to the information provided by the @samp{nm}
+program when given the @samp{-D} (@samp{--dynamic}) option.
+
 @item --version
 Print the version number of @code{objdump} and exit.
 
@@ -976,6 +1401,11 @@ Print the version number of @code{objdump} and exit.
 Display all available header information, including the symbol table and
 relocation entries.  Using @samp{-x} is equivalent to specifying all of
 @samp{-a -f -h -r -t}.
+
+@item -w
+@itemx --wide
+@cindex wide output, printing
+Format some lines for output devices that have more than 80 columns.
 @end table
 
 @node ranlib
@@ -999,7 +1429,7 @@ An archive with such an index speeds up linking to the library and
 allows routines in the library to call each other without regard to
 their placement in the archive.
 
-The GNU @code{ranlib} program is another form of GNU @code{ar}; running
+The @sc{gnu} @code{ranlib} program is another form of @sc{gnu} @code{ar}; running
 @code{ranlib} is completely equivalent to executing @samp{ar -s}.
 @xref{ar}.
 
@@ -1019,15 +1449,16 @@ Show the version number of @code{ranlib}.
 size [ -A | -B | --format=@var{compatibility} ]
      [ --help ]  [ -d | -o | -x | --radix=@var{number} ]
      [ --target=@var{bfdname} ]  [ -V | --version ]  
-     @var{objfile}@dots{}
+     [ @var{objfile}@dots{} ]
 @end smallexample
 
-The GNU @code{size} utility lists the section sizes---and the total
+The @sc{gnu} @code{size} utility lists the section sizes---and the total
 size---for each of the object or archive files @var{objfile} in its
 argument list.  By default, one line of output is generated for each
 object file or each module in an archive.
 
 @var{objfile}@dots{} are the object files to be examined.
+If none are specified, the file @code{a.out} will be used.
 
 The command line options have the following meanings:
 
@@ -1036,7 +1467,7 @@ The command line options have the following meanings:
 @itemx -B
 @itemx --format=@var{compatibility}
 @cindex @code{size} display format
-Using one of these options, you can choose whether the output from GNU
+Using one of these options, you can choose whether the output from @sc{gnu}
 @code{size} resembles output from System V @code{size} (using @samp{-A},
 or @samp{--format=sysv}), or Berkeley @code{size} (using @samp{-B}, or
 @samp{--format=berkeley}).  The default is the one-line format similar to
@@ -1118,12 +1549,12 @@ strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-]
         [--help] [--version] @var{file}@dots{}
 @end smallexample
 
-For each @var{file} given, GNU @code{strings} prints the printable
+For each @var{file} given, @sc{gnu} @code{strings} prints the printable
 character sequences that are at least 4 characters long (or the number
-given with the options below) and are followed by a NUL or newline
+given with the options below) and are followed by an unprintable
 character.  By default, it only prints the strings from the initialized
-data sections of object files; for other types of files, it prints the
-strings from the whole file.
+and loaded sections of object files; for other types of files, it prints
+the strings from the whole file.
 
 @code{strings} is mainly useful for determining the contents of non-text
 files.
@@ -1132,8 +1563,8 @@ files.
 @item -a
 @itemx --all
 @itemx -
-Do not scan only the initialized data section of object files; scan
-the whole files.
+Do not scan only the initialized and loaded sections of object files;
+scan the whole files.
 
 @item -f
 @itemx --print-file-name
@@ -1142,8 +1573,8 @@ Print the name of the file before each string.
 @item --help
 Print a summary of the program usage on the standard output and exit.
 
-@itemx -@var{min-len}
-@item -n @var{min-len}
+@item -@var{min-len}
+@itemx -n @var{min-len}
 @itemx --bytes=@var{min-len}
 Print sequences of characters that are at least @var{min-len} characters
 long, instead of the default 4.
@@ -1178,16 +1609,20 @@ Print the program version number on the standard output and exit.
 @cindex symbols, discarding
 
 @smallexample
-strip [ -F @var{bfdname} | --target=@var{bfdname} | --target=@var{bfdname} ]
+strip [ -F @var{bfdname} | --target=@var{bfdname} ]
       [ -I @var{bfdname} | --input-target=@var{bfdname} ]
       [ -O @var{bfdname} | --output-target=@var{bfdname} ]
       [ -s | --strip-all ] [ -S | -g | --strip-debug ]
+      [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
+      [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
       [ -x | --discard-all ] [ -X | --discard-locals ]
+      [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
+      [ -o @var{file} ] [ -p | --preserve-dates ]
       [ -v | --verbose ]  [ -V | --version ]  [ --help ]
       @var{objfile}@dots{}
 @end smallexample
 
-GNU @code{strip} discards all symbols from object files
+@sc{gnu} @code{strip} discards all symbols from object files
 @var{objfile}.  The list of object files may include archives.
 At least one object file must be given.
 
@@ -1215,6 +1650,12 @@ code format @var{bfdname}.
 Replace @var{objfile} with a file in the output format @var{bfdname}.
 @xref{Target Selection}, for more information.
 
+@item -R @var{sectionname}
+@itemx --remove-section=@var{sectionname}
+Remove any section named @var{sectionname} from the output file.  This
+option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.
+
 @item -s
 @itemx --strip-all
 Remove all symbols.
@@ -1224,6 +1665,29 @@ Remove all symbols.
 @itemx --strip-debug
 Remove debugging symbols only.
 
+@item --strip-unneeded
+Remove all symbols that are not needed for relocation processing.
+
+@item -K @var{symbolname}
+@itemx --keep-symbol=@var{symbolname}
+Keep only symbol @var{symbolname} from the source file.  This option may
+be given more than once.
+
+@item -N @var{symbolname}
+@itemx --strip-symbol=@var{symbolname}
+Remove symbol @var{symbolname} from the source file. This option may be
+given more than once, and may be combined with strip options other than
+@code{-K}.
+
+@item -o @var{file}
+Put the stripped output in @var{file}, rather than replacing the
+existing file.  When this argument is used, only one @var{objfile}
+argument may be specified.
+
+@item -p
+@itemx --preserve-dates
+Preserve the access and modification dates of the file.
+
 @item -x
 @itemx --discard-all
 Remove non-global symbols.
@@ -1251,14 +1715,16 @@ archives, @samp{strip -v} lists all members of the archive.
 
 @smallexample
 c++filt [ -_ | --strip-underscores ]
+        [ -j | --java ]
+	[ -n | --no-strip-underscores ]
         [ -s @var{format} | --format=@var{format} ]
         [ --help ]  [ --version ]  [ @var{symbol}@dots{} ]
 @end smallexample
 
-The C++ language provides function overloading, which means that you can
-write many functions with the same name (providing each takes parameters
-of different types).  All C++ function names are encoded into a
-low-level assembly label (this process is known as
+The C++ and Java languages provides function overloading, which means
+that you can write many functions with the same name (providing each
+takes parameters of different types).  All C++ and Java function names
+are encoded into a low-level assembly label (this process is known as
 @dfn{mangling}). The @code{c++filt} program does the inverse mapping: it
 decodes (@dfn{demangles}) low-level names into user-level names so that
 the linker can keep these overloaded functions from clashing.
@@ -1283,21 +1749,35 @@ standard output.  All results are printed on the standard output.
 @itemx --strip-underscores
 On some systems, both the C and C++ compilers put an underscore in front
 of every name.  For example, the C name @code{foo} gets the low-level
-name @code{_foo}.  This option removes the initial underscore.
+name @code{_foo}.  This option removes the initial underscore.  Whether
+@code{c++filt} removes the underscore by default is target dependent.
+
+@item -j
+@itemx --java
+Prints demangled names using Java syntax.  The default is to use C++
+syntax.
+
+@item -n
+@itemx --no-strip-underscores
+Do not remove the initial underscore.
 
 @item -s @var{format}
 @itemx --format=@var{format}
-GNU @code{nm} can decode three different methods of mangling, used by
+@sc{gnu} @code{nm} can decode three different methods of mangling, used by
 different C++ compilers.  The argument to this option selects which
 method it uses:
 
 @table @code
 @item gnu
-the one used by the GNU compiler (the default method)
+the one used by the @sc{gnu} compiler (the default method)
 @item lucid
 the one used by the Lucid compiler
 @item arm
 the one specified by the C++ Annotated Reference Manual
+@item hp
+the one used by the HP compiler
+@item edg
+the one used by the EDG compiler
 @end table
 
 @item --help
@@ -1325,16 +1805,96 @@ c++filt @var{option} @var{symbol}
 @end example
 @end quotation
 
+@node addr2line
+@chapter addr2line
+
+@kindex addr2line
+@cindex address to file name and line number
+
+@smallexample
+addr2line [ -b @var{bfdname} | --target=@var{bfdname} ]
+          [ -C | --demangle ]
+          [ -e @var{filename} | --exe=@var{filename} ]
+          [ -f | --functions ] [ -s | --basename ]
+          [ -H | --help ] [ -V | --version ]
+          [ addr addr ... ]
+@end smallexample
+
+@code{addr2line} translates program addresses into file names and line
+numbers.  Given an address and an executable, it uses the debugging
+information in the executable to figure out which file name and line
+number are associated with a given address.
+
+The executable to use is specified with the @code{-e} option.  The
+default is @file{a.out}.
+
+@code{addr2line} has two modes of operation.
+
+In the first, hexadecimal addresses are specified on the command line,
+and @code{addr2line} displays the file name and line number for each
+address.
+
+In the second, @code{addr2line} reads hexadecimal addresses from
+standard input, and prints the file name and line number for each
+address on standard output.  In this mode, @code{addr2line} may be used
+in a pipe to convert dynamically chosen addresses.
+
+The format of the output is @samp{FILENAME:LINENO}.  The file name and
+line number for each address is printed on a separate line.  If the
+@code{-f} option is used, then each @samp{FILENAME:LINENO} line is
+preceded by a @samp{FUNCTIONNAME} line which is the name of the function
+containing the address.
+
+If the file name or function name can not be determined,
+@code{addr2line} will print two question marks in their place.  If the
+line number can not be determined, @code{addr2line} will print 0.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item -b @var{bfdname}
+@itemx --target=@var{bfdname}
+@cindex object code format
+Specify that the object-code format for the object files is
+@var{bfdname}.
+
+@item -C
+@itemx --demangle
+@cindex demangling in objdump
+Decode (@dfn{demangle}) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes C++ function names readable.  @xref{c++filt}, for more information
+on demangling.
+
+@item -e @var{filename}
+@itemx --exe=@var{filename}
+Specify the name of the executable for which addresses should be
+translated.  The default file is @file{a.out}.
+
+@item -f
+@itemx --functions
+Display function names as well as file and line number information.
+
+@item -s
+@itemx --basenames
+Display only the base of each file name.
+@end table
+
 @node nlmconv
 @chapter nlmconv
 
 @code{nlmconv} converts a relocatable object file into a NetWare
-Loadable Module.  @code{nlmconv} currently works with @samp{i386} object
+Loadable Module.
+
+@ignore
+@code{nlmconv} currently works with @samp{i386} object
 files in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC}
 object files in @sc{elf}, or @code{a.out} format@footnote{
 @code{nlmconv} should work with any @samp{i386} or @sc{sparc} object
 format in the Binary File Descriptor library.  It has only been tested
 with the above formats.}.
+@end ignore
 
 @quotation
 @emph{Warning:} @code{nlmconv} is not always built as part of the binary
@@ -1345,6 +1905,7 @@ utilities, since it is only useful for NLM targets.
 nlmconv [ -I @var{bfdname} | --input-target=@var{bfdname} ]
         [ -O @var{bfdname} | --output-target=@var{bfdname} ]
         [ -T @var{headerfile} | --header-file=@var{headerfile} ]
+        [ -d | --debug]  [ -l @var{linker} | --linker=@var{linker} ]
         [ -h | --help ]  [ -V | --version ]
         @var{infile} @var{outfile}
 @end smallexample
@@ -1360,6 +1921,11 @@ Developer's Kit (``NLM SDK''), available from Novell, Inc.
 @var{infile}; see @ref{BFD,,BFD,ld.info,Using LD}, for
 more information.
 
+@code{nlmconv} can perform a link step.  In other words, you can list
+more than one object file for input if you list them in the definitions
+file (rather than simply specifying one input file on the command line).
+In this case, @code{nlmconv} calls the linker for you.
+
 @table @code
 @item -I @var{bfdname}
 @itemx --input-target=@var{bfdname}
@@ -1382,6 +1948,15 @@ writing the NLM command file language used in header files, see@ see the
 Overview}, which is part of the NLM Software Developer's Kit, available
 from Novell, Inc.
 
+@item -d
+@itemx --debug
+Displays (on standard error) the linker command line used by @code{nlmconv}.
+
+@item -l @var{linker}
+@itemx --linker=@var{linker}
+Use @var{linker} for any linking.  @var{linker} can be an absolute or a
+relative pathname.
+
 @item -h
 @itemx --help
 Prints a usage summary.
@@ -1391,34 +1966,529 @@ Prints a usage summary.
 Prints the version number for @code{nlmconv}.
 @end table
 
+@node windres
+@chapter windres
+
+@code{windres} may be used to manipulate Windows resources.
+
+@quotation
+@emph{Warning:} @code{windres} is not always built as part of the binary
+utilities, since it is only useful for Windows targets.
+@end quotation
+
+@smallexample
+windres [options] [input-file] [output-file]
+@end smallexample
+
+@code{windres} reads resources from an input file and copies them into
+an output file.  Either file may be in one of three formats:
+
+@table @code
+@item rc
+A text format read by the Resource Compiler.
+
+@item res
+A binary format generated by the Resource Compiler.
+
+@item coff
+A COFF object or executable.
+@end table
+
+The exact description of these different formats is available in
+documentation from Microsoft.
+
+When @code{windres} converts from the @code{rc} format to the @code{res}
+format, it is acting like the Windows Resource Compiler.  When
+@code{windres} converts from the @code{res} format to the @code{coff}
+format, it is acting like the Windows @code{CVTRES} program.
+
+When @code{windres} generates an @code{rc} file, the output is similar
+but not identical to the format expected for the input.  When an input
+@code{rc} file refers to an external filename, an output @code{rc} file
+will instead include the file contents.
+
+If the input or output format is not specified, @code{windres} will
+guess based on the file name, or, for the input file, the file contents.
+A file with an extension of @file{.rc} will be treated as an @code{rc}
+file, a file with an extension of @file{.res} will be treated as a
+@code{res} file, and a file with an extension of @file{.o} or
+@file{.exe} will be treated as a @code{coff} file.
+
+If no output file is specified, @code{windres} will print the resources
+in @code{rc} format to standard output.
+
+The normal use is for you to write an @code{rc} file, use @code{windres}
+to convert it to a COFF object file, and then link the COFF file into
+your application.  This will make the resources described in the
+@code{rc} file available to Windows.
+
+@table @code
+@item -i @var{filename}
+@itemx --input @var{filename}
+The name of the input file.  If this option is not used, then
+@code{windres} will use the first non-option argument as the input file
+name.  If there are no non-option arguments, then @code{windres} will
+read from standard input.  @code{windres} can not read a COFF file from
+standard input.
+
+@item -o @var{filename}
+@itemx --output @var{filename}
+The name of the output file.  If this option is not used, then
+@code{windres} will use the first non-option argument, after any used
+for the input file name, as the output file name.  If there is no
+non-option argument, then @code{windres} will write to standard output.
+@code{windres} can not write a COFF file to standard output.
+
+@item -I @var{format}
+@itemx --input-format @var{format}
+The input format to read.  @var{format} may be @samp{res}, @samp{rc}, or
+@samp{coff}.  If no input format is specified, @code{windres} will
+guess, as described above.
+
+@item -O @var{format}
+@itemx --output-format @var{format}
+The output format to generate.  @var{format} may be @samp{res},
+@samp{rc}, or @samp{coff}.  If no output format is specified,
+@code{windres} will guess, as described above.
+
+@item -F @var{target}
+@itemx --target @var{target}
+Specify the BFD format to use for a COFF file as input or output.  This
+is a BFD target name; you can use the @code{--help} option to see a list
+of supported targets.  Normally @code{windres} will use the default
+format, which is the first one listed by the @code{--help} option.
+@ref{Target Selection}.
+
+@item --preprocessor @var{program}
+When @code{windres} reads an @code{rc} file, it runs it through the C
+preprocessor first.  This option may be used to specify the preprocessor
+to use, including any leading arguments.  The default preprocessor
+argument is @code{gcc -E -xc-header -DRC_INVOKED}.
+
+@item --include-dir @var{directory}
+Specify an include directory to use when reading an @code{rc} file.
+@code{windres} will pass this to the preprocessor as an @code{-I}
+option.  @code{windres} will also search this directory when looking for
+files named in the @code{rc} file.
+
+@item -D @var{target}
+@itemx --define @var{sym[=val]}
+Specify a @code{-D} option to pass to the preprocessor when reading an
+@code{rc} file.
+
+@item -v
+Enable verbose mode.  This tells you what the preprocessor is if you
+didn't specify one.
+
+@item --language @var{val}
+Specify the default language to use when reading an @code{rc} file.
+@var{val} should be a hexadecimal language code.  The low eight bits are
+the language, and the high eight bits are the sublanguage.
+
+@item --help
+Prints a usage summary.
+
+@item --version
+Prints the version number for @code{windres}.
+
+@item --yydebug
+If @code{windres} is compiled with @code{YYDEBUG} defined as @code{1},
+this will turn on parser debugging.
+@end table
+
+
+@node dlltool
+@chapter Create files needed to build and use DLLs
+@cindex DLL
+@kindex dlltool
+
+@code{dlltool} may be used to create the files needed to build and use
+dynamic link libraries (DLLs).
+
+@quotation
+@emph{Warning:} @code{dlltool} is not always built as part of the binary
+utilities, since it is only useful for those targets which support DLLs.
+@end quotation
+
+@smallexample
+dlltool [-d|--input-def @var{def-file-name}]
+        [-b|--base-file @var{base-file-name}]
+        [-e|--output-exp @var{exports-file-name}]
+        [-z|--output-def @var{def-file-name}]
+        [-l|--output-lib @var{library-file-name}]        
+        [--export-all-symbols] [--no-export-all-symbols]
+        [--exclude-symbols @var{list}]
+        [--no-default-excludes]
+        [-S|--as @var{path-to-assembler}] [-f|--as-flags @var{options}]
+        [-D|--dllname @var{name}] [-m|--machine @var{machine}]
+        [-a|--add-indirect] [-U|--add-underscore] [-k|--kill-at]
+        [-A|--add-stdcall-alias]
+        [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork]
+        [-n|--nodelete] [-v|--verbose] [-h|--help] [-V|--version]
+        [object-file @dots{}]
+@end smallexample
+
+@code{dlltool} reads its inputs, which can come from the @samp{-d} and
+@samp{-b} options as well as object files specified on the command
+line.  It then processes these inputs and if the @samp{-e} option has
+been specified it creates a exports file.  If the @samp{-l} option
+has been specified it creates a library file and if the @samp{-z} option
+has been specified it creates a def file.  Any or all of the -e, -l
+and -z options can be present in one invocation of dlltool.
+
+When creating a DLL, along with the source for the DLL, it is necessary
+to have three other files.  @code{dlltool} can help with the creation of
+these files.
+
+The first file is a @samp{.def} file which specifies which functions are
+exported from the DLL, which functions the DLL imports, and so on.  This
+is a text file and can be created by hand, or @code{dlltool} can be used
+to create it using the @samp{-z} option.  In this case @code{dlltool}
+will scan the object files specified on its command line looking for
+those functions which have been specially marked as being exported and
+put entries for them in the .def file it creates.
+
+In order to mark a function as being exported from a DLL, it needs to
+have an @samp{-export:<name_of_function>} entry in the @samp{.drectve}
+section of the object file.  This can be done in C by using the
+asm() operator:
+
+@smallexample
+  asm (".section .drectve");  
+  asm (".ascii \"-export:my_func\"");
+
+  int my_func (void) @{ @dots{} @}
+@end smallexample
+
+The second file needed for DLL creation is an exports file.  This file
+is linked with the object files that make up the body of the DLL and it
+handles the interface between the DLL and the outside world.  This is a
+binary file and it can be created by giving the @samp{-e} option to
+@code{dlltool} when it is creating or reading in a .def file. 
+
+The third file needed for DLL creation is the library file that programs
+will link with in order to access the functions in the DLL.  This file
+can be created by giving the @samp{-l} option to dlltool when it
+is creating or reading in a .def file.
+
+@code{dlltool} builds the library file by hand, but it builds the
+exports file by creating temporary files containing assembler statements
+and then assembling these.  The @samp{-S} command line option can be
+used to specify the path to the assembler that dlltool will use,
+and the @samp{-f} option can be used to pass specific flags to that
+assembler.  The @samp{-n} can be used to prevent dlltool from deleting
+these temporary assembler files when it is done, and if @samp{-n} is
+specified twice then this will prevent dlltool from deleting the
+temporary object files it used to build the library.
+
+Here is an example of creating a DLL from a source file @samp{dll.c} and
+also creating a program (from an object file called @samp{program.o})
+that uses that DLL:
+
+@smallexample
+  gcc -c dll.c
+  dlltool -e exports.o -l dll.lib dll.o
+  gcc dll.o exports.o -o dll.dll
+  gcc program.o dll.lib -o program
+@end smallexample
+
+The command line options have the following meanings:
+
+@table @code
+
+@item -d @var{filename}
+@itemx --input-def @var{filename}
+@cindex input .def file
+Specifies the name of a .def file to be read in and processed.
+
+@item -b @var{filename}
+@itemx --base-file @var{filename}
+@cindex base files
+Specifies the name of a base file to be read in and processed.  The
+contents of this file will be added to the relocation section in the
+exports file generated by dlltool.
+
+@item -e @var{filename}
+@itemx --output-exp @var{filename}
+Specifies the name of the export file to be created by dlltool.
+
+@item -z @var{filename}
+@itemx --output-def @var{filename}
+Specifies the name of the .def file to be created by dlltool.
+
+@item -l @var{filename}
+@itemx --output-lib @var{filename}
+Specifies the name of the library file to be created by dlltool.
+
+@item --export-all-symbols
+Treat all global and weak defined symbols found in the input object
+files as symbols to be exported.  There is a small list of symbols which
+are not exported by default; see the @code{--no-default-excludes}
+option.  You may add to the list of symbols to not export by using the
+@code{--exclude-symbols} option.
+
+@item --no-export-all-symbols
+Only export symbols explicitly listed in an input .def file or in
+@samp{.drectve} sections in the input object files.  This is the default
+behaviour.  The @samp{.drectve} sections are created by @samp{dllexport}
+attributes in the source code.
+
+@item --exclude-symbols @var{list}
+Do not export the symbols in @var{list}.  This is a list of symbol names
+separated by comma or colon characters.  The symbol names should not
+contain a leading underscore.  This is only meaningful when
+@code{--export-all-symbols} is used.
+
+@item --no-default-excludes
+When @code{--export-all-symbols} is used, it will by default avoid
+exporting certain special symbols.  The current list of symbols to avoid
+exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
+@samp{impure_ptr}.  You may use the @code{--no-default-excludes} option
+to go ahead and export these special symbols.  This is only meaningful
+when @code{--export-all-symbols} is used.
+
+@item -S @var{path}
+@itemx --as @var{path}
+Specifies the path, including the filename, of the assembler to be used
+to create the exports file.
+
+@item -f @var{switches}
+@itemx --as-flags @var{switches}
+Specifies any specific command line switches to be passed to the
+assembler when building the exports file.  This option will work even if
+the @samp{-S} option is not used.  This option only takes one argument,
+and if it occurs more than once on the command line, then later
+occurrences will override earlier occurrences.  So if it is necessary to
+pass multiple switches to the assembler they should be enclosed in
+double quotes.
+
+@item -D @var{name}
+@itemx --dll-name @var{name}
+Specifies the name to be stored in the .def file as the name of the DLL
+when the @samp{-e} option is used.  If this option is not present, then
+the filename given to the @samp{-e} option will be used as the name of
+the DLL.
+
+@item -m @var{machine}
+@itemx -machine @var{machine}
+Specifies the type of machine for which the library file should be
+built.  @code{dlltool} has a built in default type, depending upon how
+it was created, but this option can be used to override that.  This is
+normally only useful when creating DLLs for an ARM processor, when the
+contents of the DLL are actually encode using THUMB instructions.
+
+@item -a
+@itemx --add-indirect
+Specifies that when @code{dlltool} is creating the exports file it
+should add a section which allows the exported functions to be
+referenced without using the import library.  Whatever the hell that
+means! 
+
+@item -U
+@itemx --add-underscore
+Specifies that when @code{dlltool} is creating the exports file it
+should prepend an underscore to the names of the exported functions. 
+
+@item -k
+@itemx --kill-at
+Specifies that when @code{dlltool} is creating the exports file it
+should not append the string @samp{@@ <number>}.  These numbers are
+called ordinal numbers and they represent another way of accessing the
+function in a DLL, other than by name.
+
+@item -A
+@itemx --add-stdcall-alias
+Specifies that when @code{dlltool} is creating the exports file it
+should add aliases for stdcall symbols without @samp{@@ <number>}
+in addition to the symbols with @samp{@@ <number>}.
+
+@item -x
+@itemx --no-idata4
+Specifies that when @code{dlltool} is creating the exports and library
+files it should omit the .idata4 section.  This is for compatibility
+with certain operating systems.
+
+@item -c
+@itemx --no-idata5
+Specifies that when @code{dlltool} is creating the exports and library
+files it should omit the .idata5 section.  This is for compatibility
+with certain operating systems.
+
+@item -i
+@itemx --interwork
+Specifies that @code{dlltool} should mark the objects in the library
+file and exports file that it produces as supporting interworking
+between ARM and THUMB code.
+
+@item -n
+@itemx --nodelete
+Makes @code{dlltool} preserve the temporary assembler files it used to
+create the exports file.  If this option is repeated then dlltool will
+also preserve the temporary object files it uses to create the library
+file. 
+
+@item -v
+@itemx --verbose
+Make dlltool describe what it is doing.
+
+@item -h
+@itemx --help
+Displays a list of command line options and then exits.
+
+@item -V
+@itemx --version
+Displays dlltool's version number and then exits.
+
+@end table
+
+@node readelf
+@chapter readelf
+
+@cindex ELF file information
+@kindex readelf
+
+@smallexample
+readelf [ -a | --all ] 
+        [ -h | --file-header]
+        [ -l | --program-headers | --segments]
+        [ -S | --section-headers | --sections]
+        [ -e | --headers]
+        [ -s | --syms | --symbols]
+        [ -r | --relocs]
+        [ -d | --dynamic]
+        [ -V | --version-info]
+        [ -D | --use-dynamic]
+        [ -x <number> | --hex-dump=<number>]
+        [ -w[liapr] | --debug-dump[=info,=line,=abbrev,=pubnames,=ranges]]
+        [      --histogram]
+        [ -v | --version]
+        [ -H | --help]
+        @var{elffile}@dots{}
+@end smallexample
+
+@code{readelf} displays information about one or more ELF format object
+files.  The options control what particular information to display.
+
+@var{elffile}@dots{} are the object files to be examined.  At the
+moment, @code{readelf} does not support examining archives, nor does it
+support examing 64 bit ELF files.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.  At least one option besides @samp{-v} or @samp{-H} must be
+given. 
+
+@table @code
+@item -a
+@itemx --all
+Equivalent to specifiying @samp{--file-header},
+@samp{--program-headers}, @samp{--sections}, @samp{--symbols},
+@samp{--relocs}, @samp{--dynamic} and @samp{--version-info}.
+
+@item -h
+@itemx --file-header
+@cindex ELF file header information
+Displays the information contained in the ELF header at the start of the
+file.
+
+@item -l
+@itemx --program-headers
+@itemx --segments
+@cindex ELF program header information
+@cindex ELF segment information
+Displays the information contained in the file's segment headers, if it
+has any.
+
+@item -S
+@itemx --sections
+@itemx --section-headers
+@cindex ELF section information
+Displays the information contained in the file's section headers, if it
+has any.
+
+@item -s
+@itemx --symbols
+@itemx --syms
+@cindex ELF symbol table information
+Displays the entries in symbol table section of the file, if it has one.
+
+@item -e
+@itemx --headers
+Display all the headers in the file.  Equivalent to @samp{-h -l -S}.
+
+@item -r
+@itemx --relocs
+@cindex ELF reloc information
+Displays the contents of the file's relocation section, if it ha one.
+
+@item -d
+@itemx --dynamic
+@cindex ELF dynamic section information
+Displays the contents of the file's dynamic section, if it has one.
+
+@item -V
+@itemx --version-info
+@cindex ELF version sections informations
+Displays the contents of the version sections in the file, it they
+exist.
+
+@item -D
+@itemx --use-dynamic
+When displaying symbols, this option makes @code{readelf} use the
+symblol table in the file's dynamic section, rather than the one in the
+symbols section.
+
+@item -x <number>
+@itemx --hex-dump=<number>
+Displays the contents of the indicated section as a hexadecimal dump.
+
+@item -w[liapr]
+@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=ranges]
+Displays the contents of the debug sections in the file, if any are
+present.  If one of the optional letters or words follows the switch
+then only data found in those specific sections will be dumped.
+
+@item --histogram
+Display a histogram of bucket list lengths when displaying the contents
+of the symbol tables.
+
+@item -v
+@itemx --version
+Display the version number of readelf.
+
+@item -H
+@itemx --help
+Display the command line options understood by @code{readelf}.
+
+@end table
+
+
 @node Selecting The Target System
 @chapter Selecting the target system
 
-You can specify three aspects of the target system to the GNU binary
-file utilities, each in several ways.  The three aspects of the target
-system that you can specify are
+You can specify three aspects of the target system to the @sc{gnu}
+binary file utilities, each in several ways:
 
 @itemize @bullet
 @item
-the target,
+the target
 
 @item
-the architecture, and
+the architecture
 
 @item
-the linker emulation (which applies to the linker only).
+the linker emulation (which applies to the linker only)
 @end itemize
 
 In the following summaries, the lists of ways to specify values are in
-order of decreasing precedence.  In other words, the ways listed earlier
-override the ways listed later.
+order of decreasing precedence.  The ways listed first override those
+listed later.
 
-The commands to list valid values only list the values that the programs
-you are running were configured for.  If they were configured with
-@samp{--with-targets=all}, the commands list most of the available
+The commands to list valid values only list the values for which the
+programs you are running were configured.  If they were configured with
+@samp{--enable-targets=all}, the commands list most of the available
 values, but a few are left out; not all targets can be configured in at
-once because some of them can only be compiled ``native'' (on hosts with
-the same type as the target system).
+once because some of them can only be configured @dfn{native} (on hosts
+with the same type as the target system).
 
 @menu
 * Target Selection::            
@@ -1427,34 +2497,36 @@ the same type as the target system).
 @end menu
 
 @node Target Selection
-@section Target selection
+@section Target Selection
 
 A @dfn{target} is an object file format.  A given target may be
 supported for multiple architectures (@pxref{Architecture Selection}).
-It may also have variations for different operating systems or architectures.
+A target selection may also have variations for different operating
+systems or architectures.
 
-Command to list valid values: @samp{objdump -i} (first column).
+The command to list valid target values is @samp{objdump -i}
+(the first column of output contains the relevant information).
 
 Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
 @samp{a.out-sunos-big}.
 
-@menu
-* objdump Target::              
-* objcopy strip Input Target::  
-* objcopy strip Output Target::  
-* nm size strings Target::  
-* Linker Input Target::         
-* Linker Output Target::        
-@end menu
+You can also specify a target using a configuration triplet.  This is
+the same sort of name that is passed to configure to specify a target.
+When you use a configuration triplet as an argument, it must be fully
+canonicalized.  You can see the canonical version of a triplet by
+running the shell script @file{config.sub} which is included with the
+sources.
+
+Some sample configuration triplets are: @samp{m68k-hp-bsd},
+@samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}.
 
-@node objdump Target
-@subsection @code{objdump} target
+@subheading @code{objdump} Target
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-b}, @samp{--target}
+command line option: @samp{-b} or @samp{--target}
 
 @item
 environment variable @code{GNUTARGET}
@@ -1463,14 +2535,13 @@ environment variable @code{GNUTARGET}
 deduced from the input file
 @end enumerate
 
-@node objcopy strip Input Target
-@subsection @code{objcopy} and @code{strip} input target
+@subheading @code{objcopy} and @code{strip} Input Target
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-I}, @samp{--input-target}, @samp{-F}, @samp{--target}
+command line options: @samp{-I} or @samp{--input-target}, or @samp{-F} or @samp{--target}
 
 @item
 environment variable @code{GNUTARGET}
@@ -1479,17 +2550,16 @@ environment variable @code{GNUTARGET}
 deduced from the input file
 @end enumerate
 
-@node objcopy strip Output Target
-@subsection @code{objcopy} and @code{strip} output target
+@subheading @code{objcopy} and @code{strip} Output Target
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-O}, @samp{-F}, @samp{--output-target}, @samp{--target}
+command line options: @samp{-O} or @samp{--output-target}, or @samp{-F} or @samp{--target}
 
 @item
-the input target (@pxref{objcopy strip Input Target})
+the input target (see ``@code{objcopy} and @code{strip} Input Target'' above)
 
 @item
 environment variable @code{GNUTARGET}
@@ -1498,14 +2568,13 @@ environment variable @code{GNUTARGET}
 deduced from the input file
 @end enumerate
 
-@node nm size strings Target
-@subsection @code{nm}, @code{size}, and @code{strings} target
+@subheading @code{nm}, @code{size}, and @code{strings} Target
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{--target}
+command line option: @samp{--target}
 
 @item
 environment variable @code{GNUTARGET}
@@ -1514,14 +2583,13 @@ environment variable @code{GNUTARGET}
 deduced from the input file
 @end enumerate
 
-@node Linker Input Target
-@subsection Linker input target
+@subheading Linker Input Target
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-b}, @samp{-format}
+command line option: @samp{-b} or @samp{--format}
 (@pxref{Options,,Options,ld.info,Using LD})
 
 @item
@@ -1537,14 +2605,13 @@ the default target of the selected linker emulation
 (@pxref{Linker Emulation Selection})
 @end enumerate
 
-@node Linker Output Target
-@subsection Linker output target
+@subheading Linker Output Target
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-oformat}
+command line option: @samp{-oformat}
 (@pxref{Options,,Options,ld.info,Using LD})
 
 @item
@@ -1552,42 +2619,34 @@ script command @code{OUTPUT_FORMAT}
 (@pxref{Option Commands,,Option Commands,ld.info,Using LD})
 
 @item
-the linker input target (@pxref{Linker Input Target})
+the linker input target (see ``Linker Input Target'' above)
 @end enumerate
 
 @node Architecture Selection
 @section Architecture selection
 
-An @dfn{architecture} is a type of CPU on which an object file is to
-run.  Its name may contain a colon, separating the name of the
-processor family from the name of the particular CPU.
+An @dfn{architecture} is a type of @sc{cpu} on which an object file is
+to run.  Its name may contain a colon, separating the name of the
+processor family from the name of the particular @sc{cpu}.
 
-Command to list valid values: @samp{objdump -i} (second column).
+The command to list valid architecture values is @samp{objdump -i} (the
+second column contains the relevant information).
 
 Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}.
 
-@menu
-* objdump Architecture::        
-* objcopy nm size strings Architecture::  
-* Linker Input Architecture::  
-* Linker Output Architecture::  
-@end menu
-
-@node objdump Architecture
-@subsection @code{objdump} architecture
+@subheading @code{objdump} Architecture
 
 Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-m}, @samp{--architecture}
+command line option: @samp{-m} or @samp{--architecture}
 
 @item
 deduced from the input file
 @end enumerate
 
-@node objcopy nm size strings Architecture
-@subsection @code{objcopy}, @code{nm}, @code{size}, @code{strings} architecture
+@subheading @code{objcopy}, @code{nm}, @code{size}, @code{strings} Architecture
 
 Ways to specify:
 
@@ -1596,8 +2655,7 @@ Ways to specify:
 deduced from the input file
 @end enumerate
 
-@node Linker Input Architecture
-@subsection Linker input architecture
+@subheading Linker Input Architecture
 
 Ways to specify:
 
@@ -1606,8 +2664,7 @@ Ways to specify:
 deduced from the input file
 @end enumerate
 
-@node Linker Output Architecture
-@subsection Linker output architecture
+@subheading Linker Output Architecture
 
 Ways to specify:
 
@@ -1618,7 +2675,7 @@ script command @code{OUTPUT_ARCH}
 
 @item
 the default architecture from the linker output target
-(@pxref{Linker Output Target})
+(@pxref{Target Selection})
 @end enumerate
 
 @node Linker Emulation Selection
@@ -1630,17 +2687,17 @@ In particular, it consists of
 
 @itemize @bullet
 @item
-the linker script,
+the linker script
 
 @item
-the target, and
+the target
 
 @item
 several ``hook'' functions that are run at certain stages of the linking
-process to do special things that some targets require.
+process to do special things that some targets require
 @end itemize
 
-Command to list valid values: @samp{ld -V}.
+The command to list valid linker emulation values is @samp{ld -V}.
 
 Sample values: @samp{hp300bsd}, @samp{mipslit}, @samp{sun4}.
 
@@ -1648,7 +2705,7 @@ Ways to specify:
 
 @enumerate
 @item
-command line option @samp{-m}
+command line option: @samp{-m}
 (@pxref{Options,,Options,ld.info,Using LD})
 
 @item
@@ -1659,6 +2716,213 @@ compiled-in @code{DEFAULT_EMULATION} from @file{Makefile},
 which comes from @code{EMUL} in @file{config/@var{target}.mt}
 @end enumerate
 
+@node Reporting Bugs
+@chapter Reporting Bugs
+@cindex bugs
+@cindex reporting bugs
+
+Your bug reports play an essential role in making the binary utilities
+reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or
+it may not.  But in any case the principal function of a bug report is
+to help the entire community by making the next version of the binary
+utilities work better.  Bug reports are your contribution to their
+maintenance.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria::                Have you found a bug?
+* Bug Reporting::               How to report bugs
+@end menu
+
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex crash
+@item
+If a binary utility gets a fatal signal, for any input whatever, that is
+a bug.  Reliable utilities never crash.
+
+@cindex error on valid input
+@item
+If a binary utility produces an error message for valid input, that is a
+bug.
+
+@item
+If you are an experienced user of binary utilities, your suggestions for
+improvement are welcome in any case.
+@end itemize
+
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex bugs, reporting
+
+A number of companies and individuals offer support for @sc{gnu}
+products.  If you obtained the binary utilities from a support
+organization, we recommend you contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+
+In any event, we also recommend that you send bug reports for the binary
+utilities to @samp{bug-gnu-utils@@gnu.org}.
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}.  If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter.  Thus, you might
+assume that the name of a file you use in an example does not matter.
+Well, probably it does not, but one cannot be sure.  Perhaps the bug is
+a stray memory reference which happens to fetch from the location where
+that pathname is stored in memory; perhaps, if the pathname were
+different, the contents of that location would fool the utility into
+doing the right thing despite the bug.  Play it safe and give a
+specific, complete example.  That is the easiest thing for you to do,
+and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the bug if
+it is new to us.  Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?''  Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of the utility.  Each utility announces it if you start it
+with the @samp{--version} argument.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of the binary utilities.
+
+@item
+Any patches you may have applied to the source, including any patches
+made to the @code{BFD} library.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+What compiler (and its version) was used to compile the utilities---e.g.
+``@code{gcc-2.7}''.
+
+@item
+The command arguments you gave the utility to observe the bug.  To
+guarantee you will not omit something important, list them all.  A copy
+of the Makefile (or the output from make) is sufficient.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input file, or set of input files, that will reproduce the
+bug.  If the utility is reading an object file or files, then it is
+generally most helpful to send the actual object files, uuencoded if
+necessary to get them through the mail system.  Making them available
+for anonymous FTP is not as good, but may be the only reasonable choice
+for large object files.
+
+If the source files were produced exclusively using @sc{gnu} programs
+(e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it
+may be OK to send the source files rather than the object files.  In
+this case, be sure to say exactly what version of @code{gcc}, or
+whatever, was used to produce the object files.  Also say how
+@code{gcc}, or whatever, was configured.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect.  For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that the utility gets a fatal signal, then we
+will certainly notice it.  But if the bug is incorrect output, we might
+not notice unless it is glaringly wrong.  You might as well not give us
+a chance to make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly.  Suppose something strange is going on, such as, your
+copy of the utility is out of synch, or you have encountered a bug in
+the C library on your system.  (This has happened!)  Your copy might
+crash and ours would not.  If you told us to expect a crash, then when
+ours fails to crash, we would know that the bug was not happening for
+us.  If you had not told us to expect a crash, then we would not be able
+to draw any conclusion from our observations.
+
+@item
+If you wish to suggest changes to the source, send us context diffs, as
+generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
+option.  Always send diffs from the old file to the new file.  If you
+even discuss something in the @code{ld} source, refer to it by context,
+not by line number.
+
+The line numbers in our development sources will not match those in your
+sources.  Your line numbers would convey no useful information to us.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us.  Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one.  But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need.  We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with programs as complicated as the binary utilities it is
+very hard to construct an example that will make the program follow a
+certain path through the code.  If you do not send us the example, we
+will not be able to construct one, so we will not be able to verify that
+the bug is fixed.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it.  A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong.  Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
 @node Index
 @unnumbered Index