@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
@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{--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}]
@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}]
@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 ELF header and program property of ELF files.
+@c man title elfedit update ELF header and program property of ELF files
@smallexample
@c man begin SYNOPSIS elfedit