@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 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2016 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
Manipulate Windows resources
@item windmc
-Genertor for Windows message resources
+Generator for Windows message resources
@item dlltool
Create the files needed to build and use Dynamic Link Libraries
* 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
@c man title ar create, modify, and extract from archives
@smallexample
-ar [@option{--plugin} @var{name}] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @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
@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.
@smallexample
@c man begin SYNOPSIS ar
-ar [@option{--plugin} @var{name}] [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @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
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
@samp{r} to indicate whether the file was appended (no old member
deleted) or replaced.
+@item s
+@cindex ranlib
+Add an index to the archive, or update it if it already exists. Note
+this command is an exception to the rule that there can only be one
+command letter, as it is possible to use it as either a command or a
+modifier. In either case it does the same thing.
+
@item t
@cindex contents of archive
Display a @emph{table} listing the contents of @var{archive}, or those
Files cannot be extracted from a thin archive.
+@item --help
+Displays the list of command line options supported by @command{ar}
+and then exits.
+
+@item --version
+Displays the version information of @command{ar} and then exits.
+
@end table
A number of modifiers (@var{mod}) may immediately follow the @var{p}
@item D
@cindex deterministic archives
+@kindex --enable-deterministic-archives
Operate in @emph{deterministic} mode. When adding files and the archive
index use zero for UIDs, GIDs, timestamps, and use consistent file modes
for all files. When this option is used, if @command{ar} is used with
identical output files regardless of the input files' owners, groups,
file modes, or modification times.
+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} modifier, below.
+
@item f
Truncate names in the archive. @sc{gnu} @command{ar} will normally permit file
names of any length. This will cause it to create archives which are
not allowed, since checking the timestamps would lose any speed
advantage from the operation @samp{q}.
+@item U
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
+Do @emph{not} operate in @emph{deterministic} mode. This is the inverse
+of the @samp{D} modifier, above: added files and the archive index will
+get their actual UID, GID, timestamp, and file mode values.
+
+This is the default unless @file{binutils} was configured with
+@option{--enable-deterministic-archives}.
+
@item v
This modifier requests the @emph{verbose} version of an operation. Many
operations display additional information, such as filenames processed,
for more file formats. This option is only available if the toolchain
has been built with plugin support enabled.
+The optional command line switch @option{--target} @var{bfdname}
+specifies that the archive members are in an object code format
+different from your system's default format. See
+@xref{Target Selection}, for more information.
+
@c man end
@ignore
@smallexample
@c man begin SYNOPSIS nm
-nm [@option{-a}|@option{--debug-syms}]
- [@option{-g}|@option{--extern-only}][@option{--plugin} @var{name}]
- [@option{-B}] [@option{-C}|@option{--demangle}[=@var{style}]] [@option{-D}|@option{--dynamic}]
- [@option{-S}|@option{--print-size}] [@option{-s}|@option{--print-armap}]
- [@option{-A}|@option{-o}|@option{--print-file-name}][@option{--special-syms}]
- [@option{-n}|@option{-v}|@option{--numeric-sort}] [@option{-p}|@option{--no-sort}]
- [@option{-r}|@option{--reverse-sort}] [@option{--size-sort}] [@option{-u}|@option{--undefined-only}]
- [@option{-t} @var{radix}|@option{--radix=}@var{radix}] [@option{-P}|@option{--portability}]
- [@option{--target=}@var{bfdname}] [@option{-f}@var{format}|@option{--format=}@var{format}]
- [@option{--defined-only}] [@option{-l}|@option{--line-numbers}] [@option{--no-demangle}]
- [@option{-V}|@option{--version}] [@option{-X 32_64}] [@option{--help}] [@var{objfile}@dots{}]
+nm [@option{-A}|@option{-o}|@option{--print-file-name}] [@option{-a}|@option{--debug-syms}]
+ [@option{-B}|@option{--format=bsd}] [@option{-C}|@option{--demangle}[=@var{style}]]
+ [@option{-D}|@option{--dynamic}] [@option{-f}@var{format}|@option{--format=}@var{format}]
+ [@option{-g}|@option{--extern-only}] [@option{-h}|@option{--help}]
+ [@option{-l}|@option{--line-numbers}] [@option{-n}|@option{-v}|@option{--numeric-sort}]
+ [@option{-P}|@option{--portability}] [@option{-p}|@option{--no-sort}]
+ [@option{-r}|@option{--reverse-sort}] [@option{-S}|@option{--print-size}]
+ [@option{-s}|@option{--print-armap}] [@option{-t} @var{radix}|@option{--radix=}@var{radix}]
+ [@option{-u}|@option{--undefined-only}] [@option{-V}|@option{--version}]
+ [@option{-X 32_64}] [@option{--defined-only}] [@option{--no-demangle}]
+ [@option{--plugin} @var{name}] [@option{--size-sort}] [@option{--special-syms}]
+ [@option{--synthetic}] [@option{--target=}@var{bfdname}]
+ [@var{objfile}@dots{}]
@c man end
@end smallexample
@item
The symbol type. At least the following types are used; others are, as
well, depending on the object file format. If lowercase, the symbol is
-local; if uppercase, the symbol is global (external).
+usually local; if uppercase, the symbol is global (external). There
+are however a few lowercase symbols that are shown for special global
+symbols (@code{u}, @code{v} and @code{w}).
@c Some more detail on exactly what these symbol types are used for
@c would be nice.
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.
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.
@cindex external symbols
Display only external symbols.
-@item --plugin @var{name}
-@cindex load plugin
-Load the plugin called @var{name} to add support for extra target
-types. This option is only available if the toolchain has been built
-with plugin support enabled.
+@item -h
+@itemx --help
+Show a summary of the options to @command{nm} and exit.
@item -l
@itemx --line-numbers
Use the POSIX.2 standard output format instead of the default format.
Equivalent to @samp{-f posix}.
+@item -r
+@itemx --reverse-sort
+Reverse the order of the sort (whether numeric or alphabetic); let the
+last come first.
+
@item -S
@itemx --print-size
Print both value and size of defined symbols for the @code{bsd} output style.
(stored in the archive by @command{ar} or @command{ranlib}) of which modules
contain definitions for which names.
-@item -r
-@itemx --reverse-sort
-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. If the @code{bsd} output format is used the size of the symbol
-is printed, rather than the value, and @samp{-S} must be used in order
-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.
-
@item -t @var{radix}
@itemx --radix=@var{radix}
Use @var{radix} as the radix for printing the symbol values. It must be
@samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
-@item --target=@var{bfdname}
-@cindex object code format
-Specify an object code format other than your system's default format.
-@xref{Target Selection}, for more information.
-
@item -u
@itemx --undefined-only
@cindex external symbols
@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 @command{nm} and exit.
@option{32_64}. The default mode of AIX @command{nm} corresponds
to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}.
-@item --help
-Show a summary of the options to @command{nm} and exit.
+@item --defined-only
+@cindex external symbols
+@cindex undefined symbols
+Display only defined symbols for each object file.
+
+@item --plugin @var{name}
+@cindex load plugin
+Load the plugin called @var{name} to add support for extra target
+types. This option is only available if the toolchain has been built
+with plugin support enabled.
+
+@item --size-sort
+Sort symbols by size. For ELF objects symbol sizes are read from the
+ELF, for other object types the symbol sizes are computed as the
+difference between the value of the symbol and the value of the symbol
+with the next higher value. If the @code{bsd} output format is used
+the size of the symbol is printed, rather than the value, and
+@samp{-S} must be used in order 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 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
+created by the linker for various purposes. They are not shown by
+default since they are not part of the binary's original source code.
+
+@item --target=@var{bfdname}
+@cindex object code format
+Specify an object code format other than your system's default format.
+@xref{Target Selection}, for more information.
+
@end table
@c man end
[@option{-x}|@option{--discard-all}]
[@option{-X}|@option{--discard-locals}]
[@option{-b} @var{byte}|@option{--byte=}@var{byte}]
- [@option{-i} @var{interleave}|@option{--interleave=}@var{interleave}]
- [@option{-j} @var{sectionname}|@option{--only-section=}@var{sectionname}]
- [@option{-R} @var{sectionname}|@option{--remove-section=}@var{sectionname}]
+ [@option{-i} [@var{breadth}]|@option{--interleave}[=@var{breadth}]]
+ [@option{--interleave-width=}@var{width}]
+ [@option{-j} @var{sectionpattern}|@option{--only-section=}@var{sectionpattern}]
+ [@option{-R} @var{sectionpattern}|@option{--remove-section=}@var{sectionpattern}]
+ [@option{--remove-relocations=}@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{--update-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}]
[@option{--localize-symbols=}@var{filename}]
[@option{--globalize-symbols=}@var{filename}]
[@option{--weaken-symbols=}@var{filename}]
+ [@option{--add-symbol} @var{name}=[@var{section}:]@var{value}[,@var{flags}]
[@option{--alt-machine-code=}@var{index}]
[@option{--prefix-symbols=}@var{string}]
[@option{--prefix-sections=}@var{string}]
[@option{--add-gnu-debuglink=}@var{path-to-file}]
[@option{--keep-file-symbols}]
[@option{--only-keep-debug}]
+ [@option{--strip-dwo}]
+ [@option{--extract-dwo}]
[@option{--extract-symbol}]
[@option{--writable-text}]
[@option{--readonly-text}]
[@option{--section-alignment=}@var{num}]
[@option{--stack=}@var{size}]
[@option{--subsystem=}@var{which}:@var{major}.@var{minor}]
+ [@option{--compress-debug-sections}]
+ [@option{--decompress-debug-sections}]
+ [@option{--elf-stt-common=@var{val}}]
[@option{-v}|@option{--verbose}]
[@option{-V}|@option{--version}]
[@option{--help}] [@option{--info}]
_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.
+If the first character of @var{sectionpattern} is the exclamation
+point (!) then matching sections will not be copied, even if earlier
+use of @option{--only-section} on the same command line would
+otherwise copy it. For example:
+
+@smallexample
+ --only-section=.text.* --only-section=!.text.foo
+@end smallexample
+
+will copy all sectinos maching '.text.*' but not the section
+'.text.foo'.
+
+@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.
+
+If the first character of @var{sectionpattern} is the exclamation
+point (!) then matching sections will not be removed even if an
+earlier use of @option{--remove-section} on the same command line
+would otherwise remove it. For example:
+
+@smallexample
+ --remove-section=.text.* --remove-section=!.text.foo
+@end smallexample
+
+will remove all sections matching the pattern '.text.*', but will not
+remove the section '.text.foo'.
+
+@item --remove-relocations=@var{sectionpattern}
+Remove relocations from the output file for any section matching
+@var{sectionpattern}. 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}.
+For example:
+
+@smallexample
+ --remove-relocations=.text.*
+@end smallexample
+
+will remove the relocations for all sections matching the patter
+'.text.*'.
+
+If the first character of @var{sectionpattern} is the exclamation
+point (!) then matching sections will not have their relocation
+removed even if an earlier use of @option{--remove-relocations} on the
+same command line would otherwise cause the relocations to be removed.
+For example:
+
+@smallexample
+ --remove-relocations=.text.* --remove-relocations=!.text.foo
+@end smallexample
+
+will remove all relocations for sections matching the pattern
+'.text.*', but will not remove relocations for the section
+'.text.foo'.
@item -S
@itemx --strip-all
@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.
+Convert a global or weak symbol called @var{symbolname} into a local
+symbol, so that it is not visible externally. This option may be
+given more than once. Note - unique symbols are not converted.
@item -W @var{symbolname}
@itemx --weaken-symbol=@var{symbolname}
@item -b @var{byte}
@itemx --byte=@var{byte}
-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 @option{-i} or @option{--interleave}
-option, or the default of 4. This option is useful for creating files
-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. Select which byte to
-copy with the @option{-b} or @option{--byte} option. The default is 4.
-@command{objcopy} ignores this option if you do not specify either @option{-b} or
-@option{--byte}.
+If interleaving has been enabled via the @option{--interleave} option
+then start the range of bytes to keep at the @var{byte}th byte.
+@var{byte} can be in the range from 0 to @var{breadth}-1, where
+@var{breadth} is the value given by the @option{--interleave} option.
+
+@item -i [@var{breadth}]
+@itemx --interleave[=@var{breadth}]
+Only copy a range out of every @var{breadth} bytes. (Header data is
+not affected). Select which byte in the range begins the copy with
+the @option{--byte} option. Select the width of the range with the
+@option{--interleave-width} option.
+
+This option is useful for creating files to program @sc{rom}. It is
+typically used with an @code{srec} output target. Note that
+@command{objcopy} will complain if you do not specify the
+@option{--byte} option as well.
+
+The default interleave breadth is 4, so with @option{--byte} set to 0,
+@command{objcopy} would copy the first byte out of every four bytes
+from the input to the output.
+
+@item --interleave-width=@var{width}
+When used with the @option{--interleave} option, copy @var{width}
+bytes at a time. The start of the range of bytes to be copied is set
+by the @option{--byte} option, and the extent of the range is set with
+the @option{--interleave} option.
+
+The default value for this option is 1. The value of @var{width} plus
+the @var{byte} value set by the @option{--byte} option must not exceed
+the interleave breadth set by the @option{--interleave} option.
+
+This option can be used to create images for two 16-bit flashes interleaved
+in a 32-bit bus by passing @option{-b 0 -i 4 --interleave-width=2}
+and @option{-b 2 -i 4 --interleave-width=2} to two @command{objcopy}
+commands. If the input was '12345678' then the outputs would be
+'1256' and '3478' respectively.
@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 -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
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 --update-section @var{sectionname}=@var{filename}
+Replace the existing contents of a section named @var{sectionname}
+with the contents of file @var{filename}. The size of the section
+will be adjusted to the size of the file. The section flags for
+@var{sectionname} will be unchanged. For ELF format files the section
+to segment mapping will also remain unchanged, something which is not
+possible using @option{--remove-section} followed by
+@option{--add-section}. The option can be specified more than once.
+
+Note - it is possible to use @option{--rename-section} and
+@option{--update-section} to both update and rename a section from one
+command line. In this case, pass the original section name to
+@option{--update-section}, and the original and new section names to
+@option{--rename-section}.
+
+@item --add-symbol @var{name}=[@var{section}:]@var{value}[,@var{flags}]
+Add a new symbol named @var{name} while copying the file. This option may be
+specified multiple times. If the @var{section} is given, the symbol will be
+associated with and relative to that section, otherwise it will be an ABS
+symbol. Specifying an undefined section will result in a fatal error. There
+is no check for the value, it will be taken as specified. Symbol flags can
+be specified and not all flags will be meaningful for all object file
+formats. By default, the symbol will be global. The special flag
+'before=@var{othersym}' will insert the new symbol in front of the specified
+@var{othersym}, otherwise the symbol(s) will be added at the end of the
+symbol table in the order they appear.
@item --rename-section @var{oldname}=@var{newname}[,@var{flags}]
Rename a section from @var{oldname} to @var{newname}, optionally
is in effect, any long section names in the input object will be truncated.
The @samp{enable} option will only emit long section names if any are
present in the inputs; this is mostly the same as @samp{keep}, but it
-is left undefined whether the @samp{enable} option might force the
+is left undefined whether the @samp{enable} option might force the
creation of an empty string table in the output file.
@item --change-leading-char
@var{string}.
@item --add-gnu-debuglink=@var{path-to-file}
-Creates a .gnu_debuglink section which contains a reference to @var{path-to-file}
-and adds it to the output file.
+Creates a .gnu_debuglink section which contains a reference to
+@var{path-to-file} and adds it to the output file. Note: the file at
+@var{path-to-file} must exist. Part of the process of adding the
+.gnu_debuglink section involves embedding a checksum of the contents
+of the debug info file into the section.
+
+If the debug info file is built in one location but it is going to be
+installed at a later time into a different location then do not use
+the path to the installed location. The @option{--add-gnu-debuglink}
+option will fail because the installed file does not exist yet.
+Instead put the debug info file in the current directory and use the
+@option{--add-gnu-debuglink} option without any directory components,
+like this:
+
+@smallexample
+ objcopy --add-gnu-debuglink=foo.debug
+@end smallexample
+
+At debug time the debugger will attempt to look for the separate debug
+info file in a set of known locations. The exact set of these
+locations varies depending upon the distribution being used, but it
+typically includes:
+
+@table @code
+
+@item * The same directory as the executable.
+
+@item * A sub-directory of the directory containing the executable
+called .debug
+
+@item * A global debug directory such as /usr/lib/debug.
+@end table
+
+As long as the debug info file has been installed into one of these
+locations before the debugger is run everything should work
+correctly.
@item --keep-file-symbols
When stripping a file, perhaps with @option{--strip-debug} or
stripped by @option{--strip-debug} and leaving the debugging sections
intact. In ELF files, this preserves all note sections in the output.
+Note - the section headers of the stripped sections are preserved,
+including their sizes, but the contents of the section are discarded.
+The section headers are preserved so that other tools can match up the
+debuginfo file with the real executable, even if that executable has
+been relocated to a different address space.
+
The intention is that this option will be used in conjunction with
@option{--add-gnu-debuglink} to create a two part executable. One a
stripped binary which will occupy less space in RAM and in a
debugging information, not multiple filenames on a one-per-object-file
basis.
+@item --strip-dwo
+Remove the contents of all DWARF .dwo sections, leaving the
+remaining debugging sections and all symbols intact.
+This option is intended for use by the compiler as part of
+the @option{-gsplit-dwarf} option, which splits debug information
+between the .o file and a separate .dwo file. The compiler
+generates all debug information in the same file, then uses
+the @option{--extract-dwo} option to copy the .dwo sections to
+the .dwo file, then the @option{--strip-dwo} option to remove
+those sections from the original .o file.
+
+@item --extract-dwo
+Extract the contents of all DWARF .dwo sections. See the
+@option{--strip-dwo} option for more information.
+
@item --file-alignment @var{num}
Specify the file alignment. Sections in the file will always begin at
file offsets which are multiples of this number. This defaults to
It can also be a useful way of reducing the size of a @option{--just-symbols}
linker input file.
+@item --compress-debug-sections
+Compress DWARF debug sections using zlib with SHF_COMPRESSED from the
+ELF ABI. Note - if compression would actually make a section
+@emph{larger}, then it is not compressed.
+
+@item --compress-debug-sections=none
+@itemx --compress-debug-sections=zlib
+@itemx --compress-debug-sections=zlib-gnu
+@itemx --compress-debug-sections=zlib-gabi
+For ELF files, these options control how DWARF debug sections are
+compressed. @option{--compress-debug-sections=none} is equivalent
+to @option{--decompress-debug-sections}.
+@option{--compress-debug-sections=zlib} and
+@option{--compress-debug-sections=zlib-gabi} are equivalent to
+@option{--compress-debug-sections}.
+@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
+sections using zlib. The debug sections are renamed to begin with
+@samp{.zdebug} instead of @samp{.debug}. Note - if compression would
+actually make a section @emph{larger}, then it is not compressed nor
+renamed.
+
+@item --decompress-debug-sections
+Decompress DWARF debug sections using zlib. The original section
+names of the compressed sections are restored.
+
+@item --elf-stt-common=yes
+@itemx --elf-stt-common=no
+For ELF files, these options control whether common symbols should be
+converted to the @code{STT_COMMON} or @code{STT_OBJECT} type.
+@option{--elf-stt-common=yes} converts common symbol type to
+@code{STT_COMMON}. @option{--elf-stt-common=no} converts common symbol
+type to @code{STT_OBJECT}.
+
@item -V
@itemx --version
Show the version number of @command{objcopy}.
[@option{-m} @var{machine}|@option{--architecture=}@var{machine}]
[@option{-M} @var{options}|@option{--disassembler-options=}@var{options}]
[@option{-p}|@option{--private-headers}]
+ [@option{-P} @var{options}|@option{--private=}@var{options}]
[@option{-r}|@option{--reloc}]
[@option{-R}|@option{--dynamic-reloc}]
[@option{-s}|@option{--full-contents}]
[@option{-W[lLiaprmfFsoRt]}|
- @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]]
+ @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames]
+ [=aranges,=macro,=frames,=frames-interp,=str,=loc]
+ [=Ranges,=pubtypes,=trace_info,=trace_abbrev]
+ [=trace_aranges,=gdb_index]
[@option{-G}|@option{--stabs}]
[@option{-t}|@option{--syms}]
[@option{-T}|@option{--dynamic-syms}]
[@option{--prefix-addresses}]
[@option{--[no-]show-raw-insn}]
[@option{--adjust-vma=}@var{offset}]
+ [@option{--dwarf-depth=@var{n}}]
+ [@option{--dwarf-start=@var{n}}]
[@option{--special-syms}]
[@option{--prefix=}@var{prefix}]
[@option{--prefix-strip=}@var{level}]
The long and short forms of options, shown here as alternatives, are
equivalent. At least one option from the list
-@option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x} must be given.
+@option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-P,-r,-R,-s,-S,-t,-T,-V,-x} must be given.
@table @env
@item -a
Like @option{-d}, but disassemble the contents of all sections, not just
those expected to contain instructions.
+This option also has a subtle effect on the disassembly of
+instructions in code sections. When option @option{-d} is in effect
+objdump will assume that any symbols present in a code section occur
+on the boundary between instructions and it will refuse to disassemble
+across such a boundary. When option @option{-D} is in effect however
+this assumption is supressed. This means that it is possible for the
+output of @option{-d} and @option{-D} to differ if, for example, data
+is stored in code sections.
+
If the target is an ARM architecture this switch also has the effect
of forcing the disassembler to decode pieces of data found in code
sections as if they were instructions.
Instead, it shows the usual addresses, which are implicit for the
target.
+Note, in some cases it is possible for a section to have both the
+READONLY and the NOREAD attributes set. In such cases the NOREAD
+attribute takes precedence, but @command{objdump} will report both
+since the exact setting of the flag bits might be important.
+
@item -H
@itemx --help
Print a summary of the options to @command{objdump} and exit.
disassembler option then multiple @option{-M} options can be used or
can be placed together into a comma separated list.
+For the ARC architecture the option can be used to specify the extra
+instruction classes that should be disassembled. A comma separated
+list of one or more of the following values should be used:
+
+@table @code
+@item dsp
+Recognize DSP instructions.
+@item spfp
+Recognize FPX SP instructions.
+@item dpfp
+Recognize FPX DP instructions.
+@item quarkse_em
+Recognize FPU QuarkSE-EM instructions.
+@item fpuda
+Recognize double assist FPU instructions.
+@item fpus
+Recognize single precision FPU instructions.
+@item fpud
+Recognize double precision FPU instructions.
+@end table
+
If the target is an ARM architecture then this switch can be used to
select which register name set is used during disassembler. Specifying
@option{-M reg-names-std} (the default) will select the register names as
For the x86, some of the options duplicate functions of the @option{-m}
switch, but allow finer grained control. Multiple selections from the
following may be specified as a comma separated string.
-@option{x86-64}, @option{i386} and @option{i8086} select disassembly for
-the given architecture. @option{intel} and @option{att} select between
-intel syntax mode and AT&T syntax mode.
-@option{intel-mnemonic} and @option{att-mnemonic} select between
-intel mnemonic mode and AT&T mnemonic mode. @option{intel-mnemonic}
-implies @option{intel} and @option{att-mnemonic} implies @option{att}.
-@option{addr64}, @option{addr32},
-@option{addr16}, @option{data32} and @option{data16} specify the default
-address size and operand size. These four options will be overridden if
-@option{x86-64}, @option{i386} or @option{i8086} appear later in the
-option string. Lastly, @option{suffix}, when in AT&T mode,
-instructs the disassembler to print a mnemonic suffix even when the
-suffix could be inferred by the operands.
+@table @code
+@item x86-64
+@itemx i386
+@itemx i8086
+Select disassembly for the given architecture.
+
+@item intel
+@itemx att
+Select between intel syntax mode and AT&T syntax mode.
+
+@item amd64
+@itemx intel64
+Select between AMD64 ISA and Intel64 ISA.
+
+@item intel-mnemonic
+@itemx att-mnemonic
+Select between intel mnemonic mode and AT&T mnemonic mode.
+Note: @code{intel-mnemonic} implies @code{intel} and
+@code{att-mnemonic} implies @code{att}.
+
+@item addr64
+@itemx addr32
+@itemx addr16
+@itemx data32
+@itemx data16
+Specify the default address size and operand size. These four options
+will be overridden if @code{x86-64}, @code{i386} or @code{i8086}
+appear later in the option string.
+
+@item suffix
+When in AT&T mode, instructs the disassembler to print a mnemonic
+suffix even when the suffix could be inferred by the operands.
+@end table
For PowerPC, @option{booke} controls the disassembly of BookE
instructions. @option{32} and @option{64} select PowerPC and
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
be decoded as VAX instructions, which would probably lead the rest
of the function being wrongly disassembled.
+For ARC, @option{dsp} controls the printing of DSP instructions,
+@option{spfp} selects the printing of FPX single precision FP
+instructions, @option{dpfp} selects the printing of FPX double
+precision FP instructions, @option{quarkse_em} selects the printing of
+special QuarkSE-EM instructions, @option{fpuda} selects the printing
+of double precision assist instructions, @option{fpus} selects the
+printing of FPU single precision FP instructions, while @option{fpud}
+selects the printing of FPU souble precision FP instructions.
+
@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 -P @var{options}
+@itemx --private=@var{options}
+Print information that is specific to the object file format. The
+argument @var{options} is a comma separated list that depends on the
+format (the lists of options is displayed with the help).
+
+For XCOFF, the available options are:
+@table @code
+@item header
+@item aout
+@item sections
+@item syms
+@item relocs
+@item lineno,
+@item loader
+@item except
+@item typchk
+@item traceback
+@item toc
+@item ldinfo
+@end table
+
+Not all object formats support this option. In particular the ELF
+format does not use it.
+
@item -r
@itemx --reloc
@cindex relocation entries, in object file
@item --prefix=@var{prefix}
@cindex Add prefix to absolute paths
Specify @var{prefix} to add to the absolute paths when used with
-@option{-S}.
+@option{-S}.
@item --prefix-strip=@var{level}
@cindex Strip absolute paths
This is the default when @option{--prefix-addresses} is used.
@item --insn-width=@var{width}
-@cindex Instruction width
+@cindex Instruction width
Display @var{width} bytes on a single line when disassembling
instructions.
@item -W[lLiaprmfFsoRt]
-@itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]
+@itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames]
+@itemx --dwarf[=aranges,=macro,=frames,=frames-interp,=str,=loc]
+@itemx --dwarf[=Ranges,=pubtypes,=trace_info,=trace_abbrev]
+@itemx --dwarf[=trace_aranges,=gdb_index]
@cindex DWARF
@cindex debug symbols
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.
+Note that there is no single letter option to display the content of
+trace sections or .gdb_index.
+
+Note: the output from the @option{=info} option can also be affected
+by the options @option{--dwarf-depth}, the @option{--dwarf-start} and
+the @option{--dwarf-check}.
+
+@item --dwarf-depth=@var{n}
+Limit the dump of the @code{.debug_info} section to @var{n} children.
+This is only useful with @option{--dwarf=info}. The default is
+to print all DIEs; the special value 0 for @var{n} will also have this
+effect.
+
+With a non-zero value for @var{n}, DIEs at or deeper than @var{n}
+levels will not be printed. The range for @var{n} is zero-based.
+
+@item --dwarf-start=@var{n}
+Print only DIEs beginning with the DIE numbered @var{n}. This is only
+useful with @option{--dwarf=info}.
+
+If specified, this option will suppress printing of any header
+information and all DIEs before the DIE numbered @var{n}. Only
+siblings and children of the specified DIE will be printed.
+
+This can be used in conjunction with @option{--dwarf-depth}.
+
+@item --dwarf-check
+Enable additional checks for consistency of Dwarf information.
+
@item -G
@itemx --stabs
@cindex stab
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
@smallexample
@c man begin SYNOPSIS ranlib
-ranlib [@option{-vVt}] @var{archive}
+ranlib [@option{--plugin} @var{name}] [@option{-DhHvVt}] @var{archive}
@c man end
@end smallexample
@c man begin OPTIONS ranlib
@table @env
+@item -h
+@itemx -H
+@itemx --help
+Show usage information for @command{ranlib}.
+
@item -v
@itemx -V
@itemx --version
Show the version number of @command{ranlib}.
+@item -D
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
+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.
+
+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.
+
+@item -U
+@cindex deterministic archives
+@kindex --enable-deterministic-archives
+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.
+
+If @file{binutils} was configured @emph{without}
+@option{--enable-deterministic-archives}, then this mode is on by
+default.
+
@end table
@c man end
[@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{-s}] [@option{--output-separator}@var{sep_string}]
[@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.
-@command{strings} is mainly useful for determining the contents of non-text
-files.
+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.
@c man end
@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
@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.
+
+@item -s
+@itemx --output-separator
+By default, output strings are delimited by a new-line. This option
+allows you to supply any string to be used as the output record
+separator. Useful with --include-all-whitespace where strings
+may contain new-lines internally.
@end table
@c man end
[@option{-O} @var{bfdname} |@option{--output-target=}@var{bfdname}]
[@option{-s}|@option{--strip-all}]
[@option{-S}|@option{-g}|@option{-d}|@option{--strip-debug}]
+ [@option{--strip-dwo}]
[@option{-K} @var{symbolname} |@option{--keep-symbol=}@var{symbolname}]
[@option{-N} @var{symbolname} |@option{--strip-symbol=}@var{symbolname}]
[@option{-w}|@option{--wildcard}]
[@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
[@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
+ [@option{--remove-relocations=}@var{sectionpattern}]
[@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}]
@item -R @var{sectionname}
@itemx --remove-section=@var{sectionname}
-Remove any section named @var{sectionname} from the output file. This
+Remove any section named @var{sectionname} from the output file, in
+addition to whatever sections would otherwise be removed. 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.
+
+If the first character of @var{sectionpattern} is the exclamation
+point (!) then matching sections will not be removed even if an
+earlier use of @option{--remove-section} on the same command line
+would otherwise remove it. For example:
+
+@smallexample
+ --remove-section=.text.* --remove-section=!.text.foo
+@end smallexample
+
+will remove all sections matching the pattern '.text.*', but will not
+remove the section '.text.foo'.
+
+@item --remove-relocations=@var{sectionpattern}
+Remove relocations from the output file for any section matching
+@var{sectionpattern}. 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}.
+For example:
+
+@smallexample
+ --remove-relocations=.text.*
+@end smallexample
+
+will remove the relocations for all sections matching the patter
+'.text.*'.
+
+If the first character of @var{sectionpattern} is the exclamation
+point (!) then matching sections will not have their relocation
+removed even if an earlier use of @option{--remove-relocations} on the
+same command line would otherwise cause the relocations to be removed.
+For example:
+
+@smallexample
+ --remove-relocations=.text.* --remove-relocations=!.text.foo
+@end smallexample
+
+will remove all relocations for sections matching the pattern
+'.text.*', but will not remove relocations for the section
+'.text.foo'.
@item -s
@itemx --strip-all
@itemx --strip-debug
Remove debugging symbols only.
+@item --strip-dwo
+Remove the contents of all DWARF .dwo sections, leaving the
+remaining debugging sections and all symbols intact.
+See the description of this option in the @command{objcopy} section
+for more information.
+
@item --strip-unneeded
Remove all symbols that are not needed for relocation processing.
@itemx --preserve-dates
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
which would otherwise get stripped.
@item --only-keep-debug
-Strip a file, removing contents of any sections that would not be
+Strip a file, emptying the contents of any sections that would not be
stripped by @option{--strip-debug} and leaving the debugging sections
-intact. In ELF files, this preserves all note sections in the output.
+intact. In ELF files, this preserves all the note sections in the
+output as well.
+
+Note - the section headers of the stripped sections are preserved,
+including their sizes, but the contents of the section are discarded.
+The section headers are preserved so that other tools can match up the
+debuginfo file with the real executable, even if that executable has
+been relocated to a different address space.
The intention is that this option will be used in conjunction with
@option{--add-gnu-debuglink} to create a two part executable. One a
@c man end
@end ignore
-@node c++filt, addr2line, elfedit, Top
+@node c++filt, addr2line, strip, Top
@chapter c++filt
@kindex c++filt
@smallexample
@c man begin SYNOPSIS cxxfilt
-c++filt [@option{-_}|@option{--strip-underscores}]
- [@option{-n}|@option{--no-strip-underscores}]
+c++filt [@option{-_}|@option{--strip-underscore}]
+ [@option{-n}|@option{--no-strip-underscore}]
[@option{-p}|@option{--no-params}]
[@option{-t}|@option{--types}]
[@option{-i}|@option{--no-verbose}]
@table @env
@item -_
-@itemx --strip-underscores
+@itemx --strip-underscore
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. Whether
@command{c++filt} removes the underscore by default is target dependent.
@item -n
-@itemx --no-strip-underscores
+@itemx --no-strip-underscore
Do not remove the initial underscore.
@item -p
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 address is printed on a separate line. If the
-@command{-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 @command{-a} option is used, then the
-address read is first printed.
+The format of the output is @samp{FILENAME:LINENO}. By default
+each input address generates one line of output.
+
+Two options can generate additional lines before each
+@samp{FILENAME:LINENO} line (in that order).
+
+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.
+
+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.
+
+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
@table @env
@item -a
@itemx --addresses
-Display address before function names or file and line number
+Display the address before the function name, file and line number
information. The address is printed with a @samp{0x} prefix to easily
identify it.
@c man title windmc generates Windows message resources.
@smallexample
-@c man begin SYNOPSIS windres
+@c man begin SYNOPSIS windmc
windmc [options] input-file
@c man end
@end smallexample
@table @env
@item -a
@itemx --ascii_in
-Specifies that the input file specified is ANSI. This is the default
+Specifies that the input file specified is ASCII. This is the default
behaviour.
@item -A
@itemx --ascii_out
-Specifies that messages in the output @code{bin} files should be in ANSI
+Specifies that messages in the output @code{bin} files should be in ASCII
format.
@item -b
to use, including any leading arguments. The default preprocessor
argument is @code{gcc -E -xc-header -DRC_INVOKED}.
+@item --preprocessor-arg @var{option}
+When @command{windres} reads an @code{rc} file, it runs it through
+the C preprocessor first. This option may be used to specify additional
+text to be passed to preprocessor on its command line.
+This option can be used multiple times to add multiple options to the
+preprocessor command line.
+
@item -I @var{directory}
@itemx --include-dir @var{directory}
Specify an include directory to use when reading an @code{rc} file.
@command{dlltool} may also be used to query an existing import library
-to determine the name of the DLL to which it is associated. See the
+to determine the name of the DLL to which it is associated. See the
description of the @option{-I} or @option{--identify} option.
-
+
@c man end
@c man begin OPTIONS dlltool
@item -k
@itemx --kill-at
-Specifies that when @command{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.
+Specifies that @samp{@@<number>} suffixes should be omitted from the names
+of stdcall functions that will be imported from the DLL. This is
+useful when creating an import library for a DLL which exports stdcall
+functions but without the usual @samp{@@<number>} symbol name suffix.
+
+This does not change the naming of symbols provided by the import library
+to programs linked against it, but only the entries in the import table
+(ie the .idata section).
@item -A
@itemx --add-stdcall-alias
@item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]}
The result is going to be named @var{name}@code{.dll}.
+Note: If you want to use LIBRARY as name then you need to quote. Otherwise
+this will fail due a necessary hack for libtool (see PR binutils/13710 for more
+details).
@item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) ) [ == } @var{its_name} @code{]}
@item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *}
(forward) of the function @var{external-name} in the DLL.
If @var{its_name} is specified, this name is used as string in export table.
@var{module-name}.
+Note: The @code{EXPORTS} has to be the last command in .def file, as keywords
+are treated - beside @code{LIBRARY} - as simple name-identifiers.
+If you want to use LIBRARY as name then you need to quote it.
@item @code{IMPORTS ( (} @var{internal-name} @code{=} @var{module-name} @code{.} @var{integer} @code{) | [} @var{internal-name} @code{= ]} @var{module-name} @code{.} @var{external-name} @code{) [ == ) @var{its_name} @code{]} *}
Declares that @var{external-name} or the exported function whose
the name that the imported function will be referred to in the body of
the DLL.
If @var{its_name} is specified, this name is used as string in import table.
+Note: The @code{IMPORTS} has to be the last command in .def file, as keywords
+are treated - beside @code{LIBRARY} - as simple name-identifiers.
+If you want to use LIBRARY as name then you need to quote it.
@item @code{DESCRIPTION} @var{string}
Puts @var{string} into the output @file{.exp} file in the
[@option{-t}|@option{--section-details}]
[@option{-e}|@option{--headers}]
[@option{-s}|@option{--syms}|@option{--symbols}]
+ [@option{--dyn-syms}]
[@option{-n}|@option{--notes}]
[@option{-r}|@option{--relocs}]
[@option{-u}|@option{--unwind}]
[@option{-x} <number or name>|@option{--hex-dump=}<number or name>]
[@option{-p} <number or name>|@option{--string-dump=}<number or name>]
[@option{-R} <number or name>|@option{--relocated-dump=}<number or name>]
+ [@option{-z}|@option{--decompress}]
[@option{-c}|@option{--archive-index}]
[@option{-w[lLiaprmfFsoRt]}|
- @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]]
- [@option{-I}|@option{-histogram}]
+ @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index]]
+ [@option{--dwarf-depth=@var{n}}]
+ [@option{--dwarf-start=@var{n}}]
+ [@option{-I}|@option{--histogram}]
[@option{-v}|@option{--version}]
[@option{-W}|@option{--wide}]
[@option{-H}|@option{--help}]
@cindex ELF symbol table information
Displays the entries in symbol table section of the file, if it has one.
+@item --dyn-syms
+@cindex ELF dynamic symbol table information
+Displays the entries in dynamic symbol table section of the file, if it
+has one.
+
@item -e
@itemx --headers
Display all the headers in the file. Equivalent to @option{-h -l -S}.
@itemx --unwind
@cindex unwind information
Displays the contents of the file's unwind section, if it has one. Only
-the unwind sections for IA64 ELF files are currently supported.
+the unwind sections for IA64 ELF files, as well as ARM unwind tables
+(@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported.
@item -d
@itemx --dynamic
@item -V
@itemx --version-info
-@cindex ELF version sections informations
+@cindex ELF version sections information
Displays the contents of the version sections in the file, it they
exist.
@item -D
@itemx --use-dynamic
When displaying symbols, this option makes @command{readelf} use the
-symbol table in the file's dynamic section, rather than the one in the
-symbols section.
+symbol hash tables in the file's dynamic section, rather than the
+symbol table sections.
@item -x <number or name>
@itemx --hex-dump=<number or name>
A number identifies a particular section by index in the section table;
any other string identifies all sections with that name in the object file.
+@item -z
+@itemx --decompress
+Requests that the section(s) being dumped by @option{x}, @option{R} or
+@option{p} options are decompressed before being displayed. If the
+section(s) are not compressed then they are displayed as is.
+
@item -c
@itemx --archive-index
@cindex Archive file symbol index information
-Displays the file symbol index infomation contained in the header part
+Displays the file symbol index information contained in the header part
of binary archives. Performs the same function as the @option{t}
command to @command{ar}, but without using the BFD library. @xref{ar}.
@item -w[lLiaprmfFsoRt]
-@itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]
+@itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index]
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.
+Note that there is no single letter option to display the content of
+trace sections or .gdb_index.
+
Note: the @option{=decodedline} option will display the interpreted
contents of a .debug_line section whereas the @option{=rawline} option
dumps the contents in a raw format.
contents of a .debug_frame section whereas the @option{=frames} option
dumps the contents in a raw format.
+Note: the output from the @option{=info} option can also be affected
+by the options @option{--dwarf-depth} and @option{--dwarf-start}.
+
+@item --dwarf-depth=@var{n}
+Limit the dump of the @code{.debug_info} section to @var{n} children.
+This is only useful with @option{--debug-dump=info}. The default is
+to print all DIEs; the special value 0 for @var{n} will also have this
+effect.
+
+With a non-zero value for @var{n}, DIEs at or deeper than @var{n}
+levels will not be printed. The range for @var{n} is zero-based.
+
+@item --dwarf-start=@var{n}
+Print only DIEs beginning with the DIE numbered @var{n}. This is only
+useful with @option{--debug-dump=info}.
+
+If specified, this option will suppress printing of any header
+information and all DIEs before the DIE numbered @var{n}. Only
+siblings and children of the specified DIE will be printed.
+
+This can be used in conjunction with @option{--dwarf-depth}.
+
@item -I
@itemx --histogram
Display a histogram of bucket list lengths when displaying the contents
@smallexample
@c man begin SYNOPSIS elfedit
elfedit [@option{--input-mach=}@var{machine}]
- @option{--output-machine=}@var{machine}
+ [@option{--input-type=}@var{type}]
+ [@option{--input-osabi=}@var{osabi}]
+ @option{--output-mach=}@var{machine}
+ @option{--output-type=}@var{type}
+ @option{--output-osabi=}@var{osabi}
[@option{-v}|@option{--version}]
[@option{-h}|@option{--help}]
@var{elffile}@dots{}
@c man begin DESCRIPTION elfedit
-@command{elfedit} updates the ELF header of ELF files. The
-options control how and which fields in the ELF header should be
-updated.
+@command{elfedit} updates the ELF header of ELF files which have
+the matching ELF machine and file types. The options control how and
+which fields in the ELF header should be updated.
@var{elffile}@dots{} are the ELF files to be updated. 32-bit and
64-bit ELF files are supported, as are archives containing ELF files.
@c man begin OPTIONS elfedit
The long and short forms of options, shown here as alternatives, are
-equivalent. The @option{--output-mach} option must be given.
+equivalent. At least one of the @option{--output-mach},
+@option{--output-type} and @option{--output-osabi} options must be given.
@table @env
-@itemx --input-mach=@var{machine}
-Only the input files with ELF machine type, @var{machine}, will be
-updated. If @option{--input-mach} isn't specified, any ELF file
-will be updated.
+@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.
-The supported ELF machine types are, @var{L1OM} and @var{x86-64}.
+The supported ELF machine types are, @var{i386}, @var{IAMCU}, @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}.
+@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}.
+
+@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}.
+
+@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.
+
+The supported ELF OSABIs are, @var{none}, @var{HPUX}, @var{NetBSD},
+@var{GNU}, @var{Linux} (alias for @var{GNU}),
+@var{Solaris}, @var{AIX}, @var{Irix},
+@var{FreeBSD}, @var{TRU64}, @var{Modesto}, @var{OpenBSD}, @var{OpenVMS},
+@var{NSK}, @var{AROS} and @var{FenixOS}.
+
+@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}.
+
@item -v
@itemx --version
Display the version number of @command{elfedit}.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
-
+
@include fdl.texi
@node Binutils Index
projects / deliverable / binutils-gdb.git / blobdiff