@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2019 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
* size: (binutils)size. List section sizes and total size.
* strings: (binutils)strings. List printable strings from files.
* strip: (binutils)strip. Discard symbols.
-* elfedit: (binutils)elfedit. Update the ELF header of ELF files.
+* elfedit: (binutils)elfedit. Update ELF header and property of ELF files.
* windmc: (binutils)windmc. Generator for Windows message resources.
* windres: (binutils)windres. Manipulate Windows resources.
@end direntry
Discard symbols
@item elfedit
-Update the ELF header of ELF files.
+Update the ELF header and program property of ELF files.
@item c++filt
Demangle encoded C++ symbols (on MS-DOS, this program is named
* 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
+* elfedit:: Update ELF header and property 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
@item P
Use the full path name when matching names in the archive. @sc{gnu}
@command{ar} can not create an archive with a full path name (such archives
-are not POSIX complaint), but other archive creators can. This option
+are not POSIX compliant), but other archive creators can. This option
will cause @sc{gnu} @command{ar} to match file names using a complete path
name, which can be convenient when extracting a single file from an
archive created by another tool.
[@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{--plugin} @var{name}]
+ [@option{--no-recurse-limit}|@option{--recurse-limit}]]
+ [@option{--size-sort}] [@option{--special-syms}]
[@option{--synthetic}] [@option{--with-symbol-versions}] [@option{--target=}@var{bfdname}]
[@var{objfile}@dots{}]
@c man end
@item --no-demangle
Do not demangle low-level symbol names. This is the default.
+@item --recurse-limit
+@itemx --no-recurse-limit
+@itemx --recursion-limit
+@itemx --no-recursion-limit
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings. Since the name mangling formats allow for
+an inifinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault. The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names. Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+
@item -D
@itemx --dynamic
@cindex dynamic symbols
[@option{--localize-hidden}]
[@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}]
[@option{--globalize-symbol=}@var{symbolname}]
+ [@option{--globalize-symbols=}@var{filename}]
[@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}]
[@option{-w}|@option{--wildcard}]
[@option{-x}|@option{--discard-all}]
[@option{--strip-unneeded-symbols=}@var{filename}]
[@option{--keep-global-symbols=}@var{filename}]
[@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{--elf-stt-common=@var{val}}]
[@option{--merge-notes}]
[@option{--no-merge-notes}]
+ [@option{--verilog-data-width=@var{val}}]
[@option{-v}|@option{--verbose}]
[@option{-V}|@option{--version}]
[@option{--help}] [@option{--info}]
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}.
+Remove non-dynamic 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, and attempting to remove a dynamic relocation section
+such as @samp{.rela.plt} from an executable or shared library with
+@option{--remove-relocations=.plt} will not work. 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
+will remove the relocations for all sections matching the pattern
'.text.*'.
If the first character of @var{sectionpattern} is the exclamation
@itemx --keep-global-symbol=@var{symbolname}
Keep only symbol @var{symbolname} global. Make all other symbols local
to the file, so that they are not visible externally. This option may
-be given more than once.
+be given more than once. Note: this option cannot be used in
+conjunction with the @option{--globalize-symbol} or
+@option{--globalize-symbols} options.
@item --localize-hidden
In an ELF object, mark all symbols that have hidden or internal visibility
@item --globalize-symbol=@var{symbolname}
Give symbol @var{symbolname} global scoping so that it is visible
outside of the file in which it is defined. This option may be given
-more than once.
+more than once. Note: this option cannot be used in conjunction with
+the @option{-G} or @option{--keep-global-symbol} options.
@item -w
@itemx --wildcard
Apply @option{--globalize-symbol} option to each symbol listed in the file
@var{filename}. @var{filename} is simply a flat file, with one symbol
name per line. Line comments may be introduced by the hash character.
-This option may be given more than once.
+This option may be given more than once. Note: this option cannot be
+used in conjunction with the @option{-G} or @option{--keep-global-symbol}
+options.
@item --weaken-symbols=@var{filename}
Apply @option{--weaken-symbol} option to each symbol listed in the file
@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
@itemx --version
Show the version number of @command{objcopy}.
+@item --verilog-data-width=@var{bytes}
+For Verilog output, this options controls the number of bytes
+converted for each output data element. The input target controls the
+endianness of the conversion.
+
@item -v
@itemx --verbose
Verbose output: list all object files modified. In the case of
@cindex object file information
@kindex objdump
-@c man title objdump display information from object files.
+@c man title objdump display information from object files
@smallexample
@c man begin SYNOPSIS objdump
objdump [@option{-a}|@option{--archive-headers}]
[@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}]
[@option{-C}|@option{--demangle}[=@var{style}] ]
- [@option{-d}|@option{--disassemble}]
+ [@option{-d}|@option{--disassemble}[=@var{symbol}]]
[@option{-D}|@option{--disassemble-all}]
[@option{-z}|@option{--disassemble-zeroes}]
[@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}]
[@option{-s}|@option{--full-contents}]
[@option{-W[lLiaprmfFsoRtUuTgAckK]}|
@option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]]
+ [@option{--ctf=}@var{section}]
[@option{-G}|@option{--stabs}]
[@option{-t}|@option{--syms}]
[@option{-T}|@option{--dynamic-syms}]
[@option{--adjust-vma=}@var{offset}]
[@option{--dwarf-depth=@var{n}}]
[@option{--dwarf-start=@var{n}}]
+ [@option{--ctf-parent=}@var{section}]
+ [@option{--ctf-symbols=}@var{section}]
+ [@option{--ctf-strings=}@var{section}]
+ [@option{--no-recurse-limit}|@option{--recurse-limit}]
[@option{--special-syms}]
[@option{--prefix=}@var{prefix}]
[@option{--prefix-strip=}@var{level}]
choose an appropriate demangling style for your compiler. @xref{c++filt},
for more information on demangling.
+@item --recurse-limit
+@itemx --no-recurse-limit
+@itemx --recursion-limit
+@itemx --no-recursion-limit
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings. Since the name mangling formats allow for
+an inifinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault. The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names. Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+
@item -g
@itemx --debugging
Display debugging information. This attempts to parse STABS
@item -d
@itemx --disassemble
+@itemx --disassemble=@var{symbol}
@cindex disassembling object code
@cindex machine instructions
-Display the assembler mnemonics for the machine instructions from
-@var{objfile}. This option only disassembles those sections which are
-expected to contain instructions.
+Display the assembler mnemonics for the machine instructions from the
+input file. This option only disassembles those sections which are
+expected to contain instructions. If the optional @var{symbol}
+argument is given, then display the assembler mnemonics starting at
+@var{symbol}. If @var{symbol} is a function name then disassembly
+will stop at the end of the function, otherwise it will stop when the
+next symbol is encountered. If there are no matches for @var{symbol}
+then nothing will be displayed.
+
+Note if the @option{--dwarf=follow-links} option has also been enabled
+then any symbol tables in linked debug info files will be read in and
+used when disassembling.
@item -D
@itemx --disassemble-all
of forcing the disassembler to decode pieces of data found in code
sections as if they were instructions.
+Note if the @option{--dwarf=follow-links} option has also been enabled
+then any symbol tables in linked debug info files will be read in and
+used when disassembling.
+
@item --prefix-addresses
When disassembling, print the complete address on each line. This is
the older disassembly format.
@item --dwarf-check
Enable additional checks for consistency of Dwarf information.
+@include ctf.options.texi
+
@item -G
@itemx --stabs
@cindex stab
@cindex archive contents
@cindex symbol index
-@c man title ranlib generate index to archive.
+@c man title ranlib generate an index to an archive
@smallexample
@c man begin SYNOPSIS ranlib
@kindex size
@cindex section sizes
-@c man title size list section sizes and total size.
+@c man title size list section sizes and total size of binary files
@smallexample
@c man begin SYNOPSIS size
-size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}]
+size [@option{-A}|@option{-B}|@option{-G}|@option{--format=}@var{compatibility}]
[@option{--help}]
[@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}]
[@option{--common}]
@c man begin DESCRIPTION size
-The @sc{gnu} @command{size} utility lists the section sizes---and the total
-size---for each of the object or archive files @var{objfile} in its
-argument list. By default, one line of output is generated for each
-object file or each module in an archive.
+The @sc{gnu} @command{size} utility lists the section sizes and the total
+size for each of the binary files @var{objfile} on its argument list.
+By default, one line of output is generated for each file or each
+module if the file is an archive.
-@var{objfile}@dots{} are the object files to be examined.
-If none are specified, the file @code{a.out} will be used.
+@var{objfile}@dots{} are the files to be examined. If none are
+specified, the file @code{a.out} will be used instead.
@c man end
@table @env
@item -A
@itemx -B
+@itemx -G
@itemx --format=@var{compatibility}
@cindex @command{size} display format
Using one of these options, you can choose whether the output from @sc{gnu}
@command{size} resembles output from System V @command{size} (using @option{-A},
or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or
@option{--format=berkeley}). The default is the one-line format similar to
-Berkeley's.
+Berkeley's. Alternatively, you can choose the GNU format output
+(using @option{-G}, or @option{--format=gnu}), this is similar to
+Berkeley's output format, but sizes are counted differently.
@c Bonus for doc-source readers: you can also say --format=strange (or
@c anything else that starts with 's') for sysv, and --format=boring (or
@c anything else that starts with 'b') for Berkeley.
@command{size}:
@smallexample
$ size --format=Berkeley ranlib size
-text data bss dec hex filename
-294880 81920 11592 388392 5ed28 ranlib
-294880 81920 11888 388688 5ee50 size
+ text data bss dec hex filename
+ 294880 81920 11592 388392 5ed28 ranlib
+ 294880 81920 11888 388688 5ee50 size
+@end smallexample
+
+The Berkeley style output counts read only data in the @code{text}
+column, not in the @code{data} column, the @code{dec} and @code{hex}
+columns both display the sum of the @code{text}, @code{data}, and
+@code{bss} columns in decimal and hexadecimal respectively.
+
+The GNU format counts read only data in the @code{data} column, not
+the @code{text} column, and only displays the sum of the @code{text},
+@code{data}, and @code{bss} columns once, in the @code{total} column.
+The @option{--radix} option can be used to change the number base for
+all columns. Here is the same data displayed with GNU conventions:
+
+@smallexample
+$ size --format=GNU ranlib size
+ text data bss total filename
+ 279880 96920 11592 388392 ranlib
+ 279880 96920 11888 388688 size
@end smallexample
@noindent
@item --common
Print total size of common symbols in each file. When using Berkeley
-format these are included in the bss size.
+or GNU format these are included in the bss size.
@item -t
@itemx --totals
-Show totals of all objects listed (Berkeley format listing mode only).
+Show totals of all objects listed (Berkeley or GNU format mode only).
@item --target=@var{bfdname}
@cindex object code format
@cindex printing strings
@cindex strings, printing
-@c man title strings print the strings of printable characters in files.
+@c man title strings print the sequences of printable characters in files
@smallexample
@c man begin SYNOPSIS strings
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.
+the presence of any @option{-d} option.
@command{strings} is mainly useful for determining the contents of
non-text files.
@cindex discarding symbols
@cindex symbols, discarding
-@c man title strip Discard symbols from object files.
+@c man title strip discard symbols and other data from object files
@smallexample
@c man begin SYNOPSIS strip
@itemx --no-merge-notes
For ELF files, attempt (or do not attempt) to reduce the size of any
SHT_NOTE type sections by removing duplicate notes. The default is to
-attempt this reduction.
+attempt this reduction unless stripping debug or DWO information.
@item -N @var{symbolname}
@itemx --strip-symbol=@var{symbolname}
@kindex c++filt
@cindex demangling C++ symbols
-@c man title cxxfilt Demangle C++ and Java symbols.
+@c man title cxxfilt demangle C++ and Java symbols
@smallexample
@c man begin SYNOPSIS cxxfilt
[@option{-p}|@option{--no-params}]
[@option{-t}|@option{--types}]
[@option{-i}|@option{--no-verbose}]
+ [@option{-r}|@option{--no-recurse-limit}]
+ [@option{-R}|@option{--recurse-limit}]
[@option{-s} @var{format}|@option{--format=}@var{format}]
[@option{--help}] [@option{--version}] [@var{symbol}@dots{}]
@c man end
Do not include implementation details (if any) in the demangled
output.
+@item -r
+@itemx -R
+@itemx --recurse-limit
+@itemx --no-recurse-limit
+@itemx --recursion-limit
+@itemx --no-recursion-limit
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings. Since the name mangling formats allow for
+an inifinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault. The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names. Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+
+The @option{-r} option is a synonym for the
+@option{--no-recurse-limit} option. The @option{-R} option is a
+synonym for the @option{--recurse-limit} option.
+
@item -s @var{format}
@itemx --format=@var{format}
@command{c++filt} can decode various methods of mangling, used by
@kindex addr2line
@cindex address to file name and line number
-@c man title addr2line convert addresses into file names and line numbers.
+@c man title addr2line convert addresses into file names and line numbers
@smallexample
@c man begin SYNOPSIS addr2line
addr2line [@option{-a}|@option{--addresses}]
[@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}]
[@option{-C}|@option{--demangle}[=@var{style}]]
+ [@option{-r}|@option{--no-recurse-limit}]
+ [@option{-R}|@option{--recurse-limit}]
[@option{-e} @var{filename}|@option{--exe=}@var{filename}]
[@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}]
[@option{-i}|@option{--inlines}]
Make the output more human friendly: each location are printed on one line.
If option @option{-i} is specified, lines for all enclosing scopes are
prefixed with @samp{(inlined by)}.
+
+@item -r
+@itemx -R
+@itemx --recurse-limit
+@itemx --no-recurse-limit
+@itemx --recursion-limit
+@itemx --no-recursion-limit
+Enables or disables a limit on the amount of recursion performed
+whilst demangling strings. Since the name mangling formats allow for
+an inifinite level of recursion it is possible to create strings whose
+decoding will exhaust the amount of stack space available on the host
+machine, triggering a memory fault. The limit tries to prevent this
+from happening by restricting recursion to 2048 levels of nesting.
+
+The default is for this limit to be enabled, but disabling it may be
+necessary in order to demangle truly complicated names. Note however
+that if the recursion limit is disabled then stack exhaustion is
+possible and any bug reports about such an event will be rejected.
+
+The @option{-r} option is a synonym for the
+@option{--no-recurse-limit} option. The @option{-R} option is a
+synonym for the @option{--recurse-limit} option.
+
+Note this option is only effective if the @option{-C} or
+@option{--demangle} option has been enabled.
+
@end table
@c man end
utilities, since it is only useful for Windows targets.
@end quotation
-@c man title windmc generates Windows message resources.
+@c man title windmc generates Windows message resources
@smallexample
@c man begin SYNOPSIS windmc
utilities, since it is only useful for Windows targets.
@end quotation
-@c man title windres manipulate Windows resources.
+@c man title windres manipulate Windows resources
@smallexample
@c man begin SYNOPSIS windres
support DLLs.
@end quotation
-@c man title dlltool Create files needed to build and use DLLs.
+@c man title dlltool create files needed to build and use DLLs
@smallexample
@c man begin SYNOPSIS dlltool
@cindex ELF file information
@kindex readelf
-@c man title readelf Displays information about ELF files.
+@c man title readelf display information about ELF files
@smallexample
@c man begin SYNOPSIS readelf
@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,=addr,=cu_index,=links,=follow-links]]
[@option{--dwarf-depth=@var{n}}]
[@option{--dwarf-start=@var{n}}]
+ [@option{--ctf=}@var{section}]
+ [@option{--ctf-parent=}@var{section}]
+ [@option{--ctf-symbols=}@var{section}]
+ [@option{--ctf-strings=}@var{section}]
[@option{-I}|@option{--histogram}]
[@option{-v}|@option{--version}]
[@option{-W}|@option{--wide}]
@cindex unwind information
Displays the contents of the file's unwind section, if it has one. Only
the unwind sections for IA64 ELF files, as well as ARM unwind tables
-(@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported.
+(@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported. If
+support is not yet implemented for your architecture you could try
+dumping the contents of the @var{.eh_frames} section using the
+@option{--debug-dump=frames} or @option{--debug-dump=frames-interp}
+options.
@item -d
@itemx --dynamic
@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,=addr,=cu_index,=links,=follow-links]
@include debug.options.texi
+@include ctf.options.texi
+@item --ctf-symbols=@var{section}
+@item --ctf-strings=@var{section}
+Specify the name of another section from which the CTF file can inherit
+strings and symbols.
+
+If either of @option{--ctf-symbols} or @option{--ctf-strings} is specified, the
+other must be specified as well.
+
@item -I
@itemx --histogram
Display a histogram of bucket list lengths when displaying the contents
@cindex Update ELF header
@kindex elfedit
-@c man title elfedit Update the ELF header of ELF files.
+@c man title elfedit update ELF header and program property of ELF files
@smallexample
@c man begin SYNOPSIS elfedit
@option{--output-mach=}@var{machine}
@option{--output-type=}@var{type}
@option{--output-osabi=}@var{osabi}
+ @option{--enable-x86-feature=}@var{feature}
+ @option{--disable-x86-feature=}@var{feature}
[@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 which have
-the matching ELF machine and file types. The options control how and
-which fields in the ELF header should be updated.
+@command{elfedit} updates the ELF header and program property of ELF
+files which have the matching ELF machine and file types. The options
+control how and which fields in the ELF header and program property
+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.
The long and short forms of options, shown here as alternatives, are
equivalent. At least one of the @option{--output-mach},
-@option{--output-type} and @option{--output-osabi} options must be given.
+@option{--output-type}, @option{--output-osabi},
+@option{--enable-x86-feature} and @option{--disable-x86-feature}
+options must be given.
@table @env
Change the ELF OSABI in the ELF header to @var{osabi}. The
supported ELF OSABI are the same as @option{--input-osabi}.
+@item --enable-x86-feature=@var{feature}
+Set the @var{feature} bit in program property in @var{exec} or @var{dyn}
+ELF files with machine types of @var{i386} or @var{x86-64}. The
+supported features are, @var{ibt} and @var{shstk}.
+
+@item --disable-x86-feature=@var{feature}
+Clear the @var{feature} bit in program property in @var{exec} or
+@var{dyn} ELF files with machine types of @var{i386} or @var{x86-64}.
+The supported features are the same as @option{--enable-x86-feature}.
+
+Note: @option{--enable-x86-feature} and @option{--disable-x86-feature}
+are available only on hosts with @samp{mmap} support.
+
@item -v
@itemx --version
Display the version number of @command{elfedit}.
projects / deliverable / binutils-gdb.git / blobdiff