Applies a series of patches for PR 17512 and 17533 which fix invalid memory accesses.
[platform/upstream/binutils.git] / binutils / doc / binutils.texi
index e1dfff2..39eb1d2 100644 (file)
 
 @copying
 @c man begin COPYRIGHT
-Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010, 2011, 2012
-Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2014 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
@@ -148,18 +145,18 @@ in the section entitled ``GNU Free Documentation License''.
 * 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
-* elfedit::                     Update the ELF header of ELF files
 * c++filt::                    Filter to demangle encoded C++ symbols
 * cxxfilt: c++filt.             MS-DOS name for c++filt
 * addr2line::                  Convert addresses to file and line
 * nlmconv::                     Converts object code into an NLM
-* windres::                    Manipulate Windows resources
 * windmc::                     Generator for Windows message resources
+* windres::                    Manipulate Windows resources
 * dlltool::                    Create files needed to build and use DLLs
+* readelf::                     Display the contents of ELF format files
+* elfedit::                     Update the ELF header of ELF files
 * Common Options::              Command-line options for all utilities
 * Selecting the Target System:: How these utilities determine the target
 * Reporting Bugs::              Reporting Bugs
@@ -177,7 +174,7 @@ in the section entitled ``GNU Free Documentation License''.
 @c man title ar create, modify, and extract from archives
 
 @smallexample
-ar [@option{--plugin} @var{name}] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] [@option{--target} @var{bfdname}] @var{archive} [@var{member}@dots{}]
+ar [-]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
 ar -M [ <mri-script ]
 @end smallexample
 
@@ -221,14 +218,24 @@ table.  If an archive lacks the table, another form of @command{ar} called
 @cindex thin archives
 @sc{gnu} @command{ar} can optionally create a @emph{thin} archive,
 which contains a symbol index and references to the original copies
-of the member files of the archives.  Such an archive is useful
-for building libraries for use within a local build, where the
-relocatable objects are expected to remain available, and copying the
-contents of each object would only waste time and space.  Thin archives
-are also @emph{flattened}, so that adding one or more archives to a
-thin archive will add the elements of the nested archive individually.
+of the member files of the archive.  This is useful for building
+libraries for use within a local build tree, where the relocatable
+objects are expected to remain available, and copying the contents of
+each object would only waste time and space.
+
+An archive can either be @emph{thin} or it can be normal.  It cannot
+be both at the same time.  Once an archive is created its format
+cannot be changed without first deleting it and then creating a new
+archive in its place.
+
+Thin archives are also @emph{flattened}, so that adding one thin
+archive to another thin archive does not nest it, as would happen with
+a normal archive.  Instead the elements of the first archive are added
+individually to the second archive.
+
 The paths to the elements of the archive are stored relative to the
-archive itself.
+archive itself.  For security reasons absolute paths and paths with a
+@code{/../} component are not allowed.
 
 @cindex compatibility, @command{ar}
 @cindex @command{ar} compatibility
@@ -252,7 +259,7 @@ program.
 
 @smallexample
 @c man begin SYNOPSIS ar
-ar [@option{--plugin} @var{name}] [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] [@option{--target} @var{bfdname}] @var{archive} [@var{member}@dots{}]
+ar [@option{-X32_64}] [@option{-}]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
 @c man end
 @end smallexample
 
@@ -319,12 +326,15 @@ operation; new members are always placed at the end of the archive.
 
 The modifier @samp{v} makes @command{ar} list each file as it is appended.
 
-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
-@command{ranlib} explicitly to update the symbol table index.
+Since the point of this operation is speed, implementations of
+@command{ar} have the option of not updating the archive's symbol
+table if one exists.  Too many different systems however assume that
+symbol tables are always up-to-date, so @sc{gnu} @command{ar} will
+rebuild the table even with a quick append.
 
-However, too many different systems assume quick append rebuilds the
-index, so @sc{gnu} @command{ar} implements @samp{q} as a synonym for @samp{r}.
+Note - @sc{gnu} @command{ar} treats the command @samp{qs} as a
+synonym for @samp{r} - replacing already existing files in the
+archive and appending new ones at the end.
 
 @item r
 @cindex replacement in archive
@@ -798,6 +808,9 @@ symbol which if referenced by a relocation does not evaluate to its
 address, but instead must be invoked at runtime.  The runtime
 execution will then return the value to be used in the relocation.
 
+@item I
+The symbol is an indirect reference to another symbol.
+
 @item N
 The symbol is a debugging symbol.
 
@@ -847,10 +860,6 @@ specified.
 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.
-@ifclear man
-For more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The
-``stabs'' debug format}.
-@end ifclear
 
 @item ?
 The symbol type is unknown, or object file format specific.
@@ -1013,10 +1022,9 @@ both size and value to be printed.
 @item --special-syms
 Display symbols which have a target-specific special meaning.  These
 symbols are usually used by the target for some special processing and
-are not normally helpful when included included in the normal symbol
-lists.  For example for ARM targets this option would skip the mapping
-symbols used to mark transitions between ARM code, THUMB code and
-data.
+are not normally helpful when included in the normal symbol lists.
+For example for ARM targets this option would skip the mapping symbols
+used to mark transitions between ARM code, THUMB code and data.
 
 @item --synthetic
 Include synthetic symbols in the output.  These are special symbols
@@ -1065,22 +1073,24 @@ objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}]
         [@option{-b} @var{byte}|@option{--byte=}@var{byte}]
         [@option{-i} [@var{breadth}]|@option{--interleave}[=@var{breadth}]]
         [@option{--interleave-width=}@var{width}]
-        [@option{-j} @var{sectionname}|@option{--only-section=}@var{sectionname}]
-        [@option{-R} @var{sectionname}|@option{--remove-section=}@var{sectionname}]
+        [@option{-j} @var{sectionpattern}|@option{--only-section=}@var{sectionpattern}]
+        [@option{-R} @var{sectionpattern}|@option{--remove-section=}@var{sectionpattern}]
         [@option{-p}|@option{--preserve-dates}]
         [@option{-D}|@option{--enable-deterministic-archives}]
+        [@option{-U}|@option{--disable-deterministic-archives}]
         [@option{--debugging}]
         [@option{--gap-fill=}@var{val}]
         [@option{--pad-to=}@var{address}]
         [@option{--set-start=}@var{val}]
         [@option{--adjust-start=}@var{incr}]
         [@option{--change-addresses=}@var{incr}]
-        [@option{--change-section-address} @var{section}@{=,+,-@}@var{val}]
-        [@option{--change-section-lma} @var{section}@{=,+,-@}@var{val}]
-        [@option{--change-section-vma} @var{section}@{=,+,-@}@var{val}]
+        [@option{--change-section-address} @var{sectionpattern}@{=,+,-@}@var{val}]
+        [@option{--change-section-lma} @var{sectionpattern}@{=,+,-@}@var{val}]
+        [@option{--change-section-vma} @var{sectionpattern}@{=,+,-@}@var{val}]
         [@option{--change-warnings}] [@option{--no-change-warnings}]
-        [@option{--set-section-flags} @var{section}=@var{flags}]
+        [@option{--set-section-flags} @var{sectionpattern}=@var{flags}]
         [@option{--add-section} @var{sectionname}=@var{filename}]
+        [@option{--dump-section} @var{sectionname}=@var{filename}]
         [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]]
         [@option{--long-section-names} @{enable,disable,keep@}]
         [@option{--change-leading-char}] [@option{--remove-leading-char}]
@@ -1203,17 +1213,21 @@ called _binary_@var{objfile}_start, _binary_@var{objfile}_end and
 _binary_@var{objfile}_size.  e.g. you can transform a picture file into
 an object file and then access it in your code using these symbols.
 
-@item -j @var{sectionname}
-@itemx --only-section=@var{sectionname}
-Copy only the named section from the input file to the output file.
+@item -j @var{sectionpattern}
+@itemx --only-section=@var{sectionpattern}
+Copy only the indicated sections 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.
+inappropriately may make the output file unusable.  Wildcard
+characters are accepted in @var{sectionpattern}.
 
-@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 -R @var{sectionpattern}
+@itemx --remove-section=@var{sectionpattern}
+Remove any section matching @var{sectionpattern} from the output file.
+This option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.  Wildcard
+characters are accepted in @var{sectionpattern}.  Using both the
+@option{-j} and @option{-R} options together results in undefined
+behaviour.
 
 @item -S
 @itemx --strip-all
@@ -1337,10 +1351,28 @@ as those of the input file.
 
 @item -D
 @itemx --enable-deterministic-archives
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
 Operate in @emph{deterministic} mode.  When copying archive members
 and writing the archive index, use zero for UIDs, GIDs, timestamps,
 and use consistent file modes for all files.
 
+If @file{binutils} was configured with
+@option{--enable-deterministic-archives}, then this mode is on by default.
+It can be disabled with the @samp{-U} option, below.
+
+@item -U
+@itemx --disable-deterministic-archives
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
+Do @emph{not} operate in @emph{deterministic} mode.  This is the
+inverse of the @option{-D} option, above: when copying archive members
+and writing the archive index, use their actual UID, GID, timestamp,
+and file mode values.
+
+This is the default unless @file{binutils} was configured with
+@option{--enable-deterministic-archives}.
+
 @item --debugging
 Convert debugging information, if possible.  This is not the default
 because only certain debugging formats are supported, and the
@@ -1377,71 +1409,85 @@ 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}
+@item --change-section-address @var{sectionpattern}@{=,+,-@}@var{val}
+@itemx --adjust-section-vma @var{sectionpattern}@{=,+,-@}@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 @option{--change-addresses},
-above. If @var{section} does not exist in the input file, a warning will
-be issued, unless @option{--no-change-warnings} is used.
+Set or change both the VMA address and the LMA address of any section
+matching @var{sectionpattern}.  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
+@option{--change-addresses}, above. If @var{sectionpattern} does not
+match any sections in the input file, a warning will be issued, unless
+@option{--no-change-warnings} is used.
 
-@item --change-section-lma @var{section}@{=,+,-@}@var{val}
+@item --change-section-lma @var{sectionpattern}@{=,+,-@}@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,
+Set or change the LMA address of any sections matching
+@var{sectionpattern}.  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 @option{--change-addresses}, above.  If
+@var{sectionpattern} does not match any sections in the input file, a
+warning will be issued, unless @option{--no-change-warnings} is used.
+
+@item --change-section-vma @var{sectionpattern}@{=,+,-@}@var{val}
+@cindex changing section VMA
+Set or change the VMA address of any section matching
+@var{sectionpattern}.  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 @option{--change-addresses},
-above.  If @var{section} does not exist in the input file, a warning
-will be issued, unless @option{--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
-@option{--change-addresses}, above.  If @var{section} does not exist in
-the input file, a warning will be issued, unless
+above.  If @var{sectionpattern} does not match any sections in the
+input file, a warning will be issued, unless
 @option{--no-change-warnings} is used.
 
 @item --change-warnings
 @itemx --adjust-warnings
 If @option{--change-section-address} or @option{--change-section-lma} or
-@option{--change-section-vma} is used, and the named section does not
-exist, issue a warning.  This is the default.
+@option{--change-section-vma} is used, and the section pattern does not
+match any sections, issue a warning.  This is the default.
 
 @item --no-change-warnings
 @itemx --no-adjust-warnings
 Do not issue a warning if @option{--change-section-address} or
 @option{--adjust-section-lma} or @option{--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{noload},
-@samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and
-@samp{debug}.  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.
+if the section pattern does not match any sections.
+
+@item --set-section-flags @var{sectionpattern}=@var{flags}
+Set the flags for any sections matching @var{sectionpattern}.  The
+@var{flags} argument is a comma separated string of flag names.  The
+recognized names are @samp{alloc}, @samp{contents}, @samp{load},
+@samp{noload}, @samp{readonly}, @samp{code}, @samp{data}, @samp{rom},
+@samp{share}, and @samp{debug}.  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.
+Note - it may be necessary to use the @option{--set-section-flags}
+option to set the attributes of the newly created section.
+
+@item --dump-section @var{sectionname}=@var{filename}
+Place the contents of section named @var{sectionname} into the file
+@var{filename}, overwriting any contents that may have been there
+previously.  This option is the inverse of @option{--add-section}.
+This option is similar to the @option{--only-section} option except
+that it does not create a formatted file, it just dumps the contents
+as raw binary data, without applying any relocations.  The option can
+be specified more than once.
 
 @item --rename-section @var{oldname}=@var{newname}[,@var{flags}]
 Rename a section from @var{oldname} to @var{newname}, optionally
@@ -2081,6 +2127,15 @@ Print the 'raw' instruction mnemonic instead of some pseudo
 instruction mnemonic.  I.e., print 'daddu' or 'or' instead of 'move',
 'sll' instead of 'nop', etc.
 
+@item msa
+Disassemble MSA instructions.
+
+@item virt
+Disassemble the virtualization ASE instructions.
+
+@item xpa
+Disassemble the eXtended Physical Address (XPA) ASE instructions.
+
 @item gpr-names=@var{ABI}
 Print GPR (general-purpose register) names as appropriate
 for the specified ABI.  By default, GPR names are selected according to
@@ -2138,8 +2193,8 @@ format (the lists of options is displayed with the help).
 
 For XCOFF, the available options are: @option{header}, @option{aout},
 @option{sections}, @option{syms}, @option{relocs}, @option{lineno},
-@option{loader}, @option{except}, @option{typchk}, @option{traceback}
-and @option{toc}.
+@option{loader}, @option{except}, @option{typchk}, @option{traceback},
+@option{toc} and @option{ldinfo}.
 
 @item -r
 @itemx --reloc
@@ -2245,10 +2300,6 @@ ELF file.  This is only useful on systems (such as Solaris 2.0) in which
 section.  In most other file formats, debugging symbol-table entries are
 interleaved with linkage symbols, and are visible in the @option{--syms}
 output.
-@ifclear man
-For more information on stabs symbols, see @ref{Top,Stabs,Stabs
-Overview,stabs.info, The ``stabs'' debug format}.
-@end ifclear
 
 @item --start-address=@var{address}
 @cindex start-address
@@ -2444,8 +2495,10 @@ Operate in @emph{deterministic} mode.  The symbol map archive member's
 header will show zero for the UID, GID, and timestamp.  When this
 option is used, multiple runs will produce identical output files.
 
-This is the default unless @file{binutils} was configured with
-@option{--enable-deterministic-archives}.
+If @file{binutils} was configured with
+@option{--enable-deterministic-archives}, then this mode is on by
+default.  It can be disabled with the @samp{-U} option, described
+below.
 
 @item -t
 Update the timestamp of the symbol map of an archive.
@@ -2457,8 +2510,10 @@ Do @emph{not} operate in @emph{deterministic} mode.  This is the
 inverse of the @samp{-D} option, above: the archive index will get
 actual UID, GID, timestamp, and file mode values.
 
-This is the default unless @file{binutils} was configured with
-@option{--enable-deterministic-archives}.
+If @file{binutils} was configured @emph{without}
+@option{--enable-deterministic-archives}, then this mode is on by
+default.
+
 @end table
 
 @c man end
@@ -2611,21 +2666,31 @@ strings [@option{-afovV}] [@option{-}@var{min-len}]
         [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}]
         [@option{-}] [@option{--all}] [@option{--print-file-name}]
         [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}]
+        [@option{-w}] [@option{--include-all-whitespace}]
         [@option{--help}] [@option{--version}] @var{file}@dots{}
 @c man end
 @end smallexample
 
 @c man begin DESCRIPTION strings
 
-For each @var{file} given, @sc{gnu} @command{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 an unprintable
-character.  By default, it only prints the strings from the initialized
-and loaded sections of object files; for other types of files, it prints
-the strings from the whole file.
+For each @var{file} given, @sc{gnu} @command{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 an
+unprintable character.
+
+Depending upon how the strings program was configured it will default
+to either displaying all the printable sequences that it can find in
+each file, or only those sequences that are in loadable, initialized
+data sections.  If the file type in unrecognizable, or if strings is
+reading from stdin then it will always display all of the printable
+sequences that it can find.
+
+For backwards compatibility any file that occurs after a command line
+option of just @option{-} will also be scanned in full, regardless of
+the presence of any @option{-d} option. 
 
-@command{strings} is mainly useful for determining the contents of non-text
-files.
+@command{strings} is mainly useful for determining the contents of
+non-text files.
 
 @c man end
 
@@ -2635,8 +2700,25 @@ files.
 @item -a
 @itemx --all
 @itemx -
-Do not scan only the initialized and loaded sections of object files;
-scan the whole files.
+Scan the whole file, regardless of what sections it contains or
+whether those sections are loaded or initialized.  Normally this is
+the default behaviour, but strings can be configured so that the
+@option{-d} is the default instead.
+
+The @option{-} option is position dependent and forces strings to
+perform full scans of any file that is mentioned after the @option{-}
+on the command line, even if the @option{-d} option has been
+specified.
+
+@item -d
+@itemx --data
+Only print strings from initialized, loaded data sections in the
+file.  This may reduce the amount of garbage in the output, but it
+also exposes the strings program to any security flaws that may be
+present in the BFD library used to scan and load sections.  Strings
+can be configured so that this option is the default behaviour.  In
+such cases the @option{-a} option can be used to avoid using the BFD
+library and instead just print all of the strings found in the file.
 
 @item -f
 @itemx --print-file-name
@@ -2682,6 +2764,13 @@ Specify an object code format other than your system's default format.
 @itemx -V
 @itemx --version
 Print the program version number on the standard output and exit.
+
+@item -w
+@itemx --include-all-whitespace
+By default tab and space characters are included in the strings that
+are displayed, but other whitespace characters, such a newlines and
+carriage returns, are not.  The @option{-w} option changes this so
+that all whitespace characters are considered to be part of a string.
 @end table
 
 @c man end
@@ -2718,6 +2807,7 @@ strip [@option{-F} @var{bfdname} |@option{--target=}@var{bfdname}]
       [@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
       [@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
       [@option{-D}|@option{--enable-deterministic-archives}]
+      [@option{-U}|@option{--disable-deterministic-archives}]
       [@option{--keep-file-symbols}]
       [@option{--only-keep-debug}]
       [@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}]
@@ -2767,7 +2857,9 @@ Replace @var{objfile} with a file in the output format @var{bfdname}.
 @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.
+inappropriately may make the output file unusable.  The wildcard
+character @samp{*} may be given at the end of @var{sectionname}.  If
+so, then any section starting with @var{sectionname} will be removed.
 
 @item -s
 @itemx --strip-all
@@ -2810,10 +2902,28 @@ Preserve the access and modification dates of the file.
 
 @item -D
 @itemx --enable-deterministic-archives
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
 Operate in @emph{deterministic} mode.  When copying archive members
 and writing the archive index, use zero for UIDs, GIDs, timestamps,
 and use consistent file modes for all files.
 
+If @file{binutils} was configured with
+@option{--enable-deterministic-archives}, then this mode is on by default.
+It can be disabled with the @samp{-U} option, below.
+
+@item -U
+@itemx --disable-deterministic-archives
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
+Do @emph{not} operate in @emph{deterministic} mode.  This is the
+inverse of the @option{-D} option, above: when copying archive members
+and writing the archive index, use their actual UID, GID, timestamp,
+and file mode values.
+
+This is the default unless @file{binutils} was configured with
+@option{--enable-deterministic-archives}.
+
 @item -w
 @itemx --wildcard
 Permit regular expressions in @var{symbolname}s used in other command
@@ -2907,7 +3017,7 @@ the Info entries for @file{binutils}.
 @c man end
 @end ignore
 
-@node c++filt, addr2line, elfedit, Top
+@node c++filt, addr2line, strip, Top
 @chapter c++filt
 
 @kindex c++filt
@@ -3131,26 +3241,33 @@ standard input, and prints the file name and line number for each
 address on standard output.  In this mode, @command{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 input address is printed on separate lines.
+The format of the output is @samp{FILENAME:LINENO}.  By default
+each input address generates one line of output.
 
-If the @option{-f} option is used, then each @samp{FILENAME:LINENO}
-line is preceded by @samp{FUNCTIONNAME} which is the name of the
-function containing the address.
+Two options can generate additional lines before each
+@samp{FILENAME:LINENO} line (in that order).
 
-If the @option{-i} option is used and the code at the given address is
-present there because of inlining by the compiler then the
-@samp{@{FUNCTIONNAME@} FILENAME:LINENO} information for the inlining
-function will be displayed afterwards.  This continues recursively
-until there is no more inlining to report.
+If the @option{-a} option is used then a line with the input address
+is displayed.
+
+If the @option{-f} option is used, then a line with the
+@samp{FUNCTIONNAME} is displayed.  This is the name of the function
+containing the address.
 
-If the @option{-a} option is used then the output is prefixed by the
-input address.
+One option can generate additional lines after the
+@samp{FILENAME:LINENO} line.
+
+If the @option{-i} option is used and the code at the given address is
+present there because of inlining by the compiler then additional
+lines are displayed afterwards.  One or two extra lines (if the
+@option{-f} option is used) are displayed for each inlined function.
 
-If the @option{-p} option is used then the output for each input
-address is displayed on one, possibly quite long, line.  If
-@option{-p} is not used then the output is broken up into multiple
-lines, based on the paragraphs above.
+Alternatively if the @option{-p} option is used then each input
+address generates a single, long, output line containing the address,
+the function name, the file name and the line number.  If the
+@option{-i} option has also been used then any inlined functions will
+be displayed in the same manner, but on separate lines, and prefixed
+by the text @samp{(inlined by)}.
 
 If the file name or function name can not be determined,
 @command{addr2line} will print two question marks in their place.  If the
@@ -4384,7 +4501,7 @@ equivalent. At least one of the @option{--output-mach},
 
 @table @env
 
-@itemx --input-mach=@var{machine}
+@item --input-mach=@var{machine}
 Set the matching input ELF machine type to @var{machine}.  If
 @option{--input-mach} isn't specified, it will match any ELF
 machine types.
@@ -4392,21 +4509,21 @@ machine types.
 The supported ELF machine types are, @var{L1OM}, @var{K1OM} and
 @var{x86-64}.
 
-@itemx --output-mach=@var{machine}
+@item --output-mach=@var{machine}
 Change the ELF machine type in the ELF header to @var{machine}.  The
 supported ELF machine types are the same as @option{--input-mach}.
 
-@itemx --input-type=@var{type}
+@item --input-type=@var{type}
 Set the matching input ELF file type to @var{type}.  If
 @option{--input-type} isn't specified, it will match any ELF file types.
 
 The supported ELF file types are, @var{rel}, @var{exec} and @var{dyn}.
 
-@itemx --output-type=@var{type}
+@item --output-type=@var{type}
 Change the ELF file type in the ELF header to @var{type}.  The
 supported ELF types are the same as @option{--input-type}.
 
-@itemx --input-osabi=@var{osabi}
+@item --input-osabi=@var{osabi}
 Set the matching input ELF file OSABI to @var{osabi}.  If
 @option{--input-osabi} isn't specified, it will match any ELF OSABIs.
 
@@ -4416,7 +4533,7 @@ The supported ELF OSABIs are, @var{none}, @var{HPUX}, @var{NetBSD},
 @var{FreeBSD}, @var{TRU64}, @var{Modesto}, @var{OpenBSD}, @var{OpenVMS},
 @var{NSK}, @var{AROS} and @var{FenixOS}.
 
-@itemx --output-osabi=@var{osabi}
+@item --output-osabi=@var{osabi}
 Change the ELF OSABI in the ELF header to @var{osabi}.  The
 supported ELF OSABI are the same as @option{--input-osabi}.