@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2019 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2020 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
* 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
+* debuginfod:: Using binutils with debuginfod
* Reporting Bugs:: Reporting Bugs
* GNU Free Documentation License:: GNU Free Documentation License
* Binutils Index:: Binutils Index
Files cannot be extracted from a thin archive, and there are
restrictions on extracting from archives created with @option{P}: The
paths must not be absolute, may not contain @code{..}, and any
-subdirectories in the paths must exist.
+subdirectories in the paths must exist. If it is desired to avoid
+these restrictions then used the @option{--output} option to specify
+an output directory.
@end table
A number of modifiers (@var{mod}) may immediately follow the @var{p}
extraction operation that option must still be included on the command
line.
-Note - using this option does not allow archive members to be
-extracted to locations outside of the current directory, or one of its
-sub-directories. This is a security feature to prevent archives
-created with the @option{P} option from maliciously overwriting user
-files.
@end table
@c man end
[@option{--interleave-width=}@var{width}]
[@option{-j} @var{sectionpattern}|@option{--only-section=}@var{sectionpattern}]
[@option{-R} @var{sectionpattern}|@option{--remove-section=}@var{sectionpattern}]
+ [@option{--keep-section=}@var{sectionpattern}]
[@option{--remove-relocations=}@var{sectionpattern}]
[@option{-p}|@option{--preserve-dates}]
[@option{-D}|@option{--enable-deterministic-archives}]
will remove all sections matching the pattern '.text.*', but will not
remove the section '.text.foo'.
+@item --keep-section=@var{sectionpattern}
+When removing sections from the output file, keep sections that match
+@var{sectionpattern}.
+
@item --remove-relocations=@var{sectionpattern}
Remove non-dynamic relocations from the output file for any section
matching @var{sectionpattern}. This option may be given more than
filled in with the value specified by @option{--gap-fill} (default zero).
@item --set-start @var{val}
-Set the start address of the new file to @var{val}. Not all object file
-formats support setting the start address.
+Set the start address (also known as the entry address) of the new
+file to @var{val}. Not all object file formats support setting the
+start address.
@item --change-start @var{incr}
@itemx --adjust-start @var{incr}
@cindex changing start address
-Change the start address by adding @var{incr}. Not all object file
-formats support setting the start address.
+Change the start address (also known as the entry address) by adding
+@var{incr}. Not all object file formats support setting the start
+address.
@item --change-addresses @var{incr}
@itemx --adjust-vma @var{incr}
@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.
+@samp{exclude}, @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. In particular the
+@samp{share} flag is only meaningful for COFF format files and not for
+ELF format files.
@item --set-section-alignment @var{sectionpattern}=@var{align}
Set the alignment for any sections matching @var{sectionpattern}.
changing the section's flags to @var{flags} in the process. This has
the advantage over using a linker script to perform the rename in that
the output stays as an object file and does not become a linked
-executable.
+executable. This option accepts the same set of flags as the
+@option{--sect-section-flags} option.
This option is particularly helpful when the input format is binary,
since this will always create a section called .data. If for example,
[@option{-r}|@option{--reloc}]
[@option{-R}|@option{--dynamic-reloc}]
[@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{-W[lLiaprmfFsoORtUuTgAckK]}|
+ @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=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{-w}|@option{--wide}]
[@option{--start-address=}@var{address}]
[@option{--stop-address=}@var{address}]
+ [@option{--no-addresses}]
[@option{--prefix-addresses}]
[@option{--[no-]show-raw-insn}]
[@option{--adjust-vma=}@var{offset}]
[@option{--prefix=}@var{prefix}]
[@option{--prefix-strip=}@var{level}]
[@option{--insn-width=}@var{width}]
+ [@option{--visualize-jumps[=color|=extended-color|=off]}
[@option{-V}|@option{--version}]
[@option{-H}|@option{--help}]
@var{objfile}@dots{}
@itemx --debugging
Display debugging information. This attempts to parse STABS
debugging format information stored in the file and print it out using
-a C like syntax. If no STABS debuging was found this option
+a C like syntax. If no STABS debugging was found this option
falls back on the @option{-W} option to print any DWARF information in
the file.
then any symbol tables in linked debug info files will be read in and
used when disassembling.
+@item --no-addresses
+When disassembling, don't print addresses on each line or for symbols
+and relocation offsets. In combination with @option{--no-show-raw-insn}
+this may be useful for comparing compiler output.
+
@item --prefix-addresses
When disassembling, print the complete address on each line. This is
the older disassembly format.
@option{e300}, @option{e500}, @option{e500mc}, @option{e500mc64},
@option{e500x2}, @option{e5500}, @option{e6500}, @option{efs},
@option{power4}, @option{power5}, @option{power6}, @option{power7},
-@option{power8}, @option{power9}, @option{ppc}, @option{ppc32},
-@option{ppc64}, @option{ppc64bridge}, @option{ppcps}, @option{pwr},
-@option{pwr2}, @option{pwr4}, @option{pwr5}, @option{pwr5x},
-@option{pwr6}, @option{pwr7}, @option{pwr8}, @option{pwr9},
+@option{power8}, @option{power9}, @option{power10}, @option{ppc},
+@option{ppc32}, @option{ppc64}, @option{ppc64bridge}, @option{ppcps},
+@option{pwr}, @option{pwr2}, @option{pwr4}, @option{pwr5}, @option{pwr5x},
+@option{pwr6}, @option{pwr7}, @option{pwr8}, @option{pwr9}, @option{pwr10},
@option{pwrx}, @option{titan}, and @option{vle}.
@option{32} and @option{64} modify the default or a prior CPU
selection, disabling and enabling 64-bit insns respectively. In
Display @var{width} bytes on a single line when disassembling
instructions.
-@item -W[lLiaprmfFsoRtUuTgAckK]
-@itemx --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]
+@item --visualize-jumps[=color|=extended-color|=off]
+Visualize jumps that stay inside a function by drawing ASCII art between
+the start and target addresses. The optional @option{=color} argument
+adds color to the output using simple terminal colors. Alternatively
+the @option{=extended-color} argument will add color using 8bit
+colors, but these might not work on all terminals.
+
+If it is necessary to disable the @option{visualize-jumps} option
+after it has previously been enabled then use
+@option{visualize-jumps=off}.
+
+@item -W[lLiaprmfFsoORtUuTgAckK]
+@itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
@include debug.options.texi
@item --dwarf-check
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
+data sections. If the file type is unrecognizable, or if strings is
reading from stdin then it will always display all of the printable
sequences that it can find.
[@option{-w}|@option{--wildcard}]
[@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
[@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
+ [@option{--keep-section=}@var{sectionpattern}]
[@option{--remove-relocations=}@var{sectionpattern}]
[@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
[@option{-D}|@option{--enable-deterministic-archives}]
will remove all sections matching the pattern '.text.*', but will not
remove the section '.text.foo'.
+@item --keep-section=@var{sectionpattern}
+When removing sections from the output file, keep sections that match
+@var{sectionpattern}.
+
@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
[@option{-V}|@option{--version-info}]
[@option{-A}|@option{--arch-specific}]
[@option{-D}|@option{--use-dynamic}]
+ [@option{-L}|@option{--lint}|@option{--enable-checks}]
[@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[lLiaprmfFsoRtUuTgAckK]}|
- @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{-w[lLiaprmfFsoORtUuTgAckK]}|
+ @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=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}]
When displaying relocations, this option makes @command{readelf}
display the dynamic relocations rather than the static relocations.
+@item -L
+@itemx --lint
+@itemx --enable-checks
+Displays warning messages about possible problems with the file(s)
+being examined. If used on its own then all of the contents of the
+file(s) will be examined. If used with one of the dumping options
+then the warning messages will only be produced for the things being
+displayed.
+
@item -x <number or name>
@itemx --hex-dump=<number or name>
Displays the contents of the indicated section as a hexadecimal bytes.
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[lLiaprmfFsoRtUuTgAckK]
-@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]
+@item -w[lLiaprmfFsOoRtUuTgAckK]
+@itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=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
deduced from the input file
@end enumerate
+@node debuginfod
+@chapter debuginfod
+@cindex separate debug files
+
+debuginfod is a web service that indexes ELF/DWARF debugging resources
+by build-id and serves them over HTTP.
+
+Binutils can be built with the debuginfod client library
+@code{libdebuginfod} using the @option{--with-debuginfod} configure option.
+This option is enabled by default if @code{libdebuginfod} is installed
+and found at configure time. This allows @command{objdump} and
+@command{readelf} to automatically query debuginfod servers for
+separate debug files when the files are otherwise not found.
+
+debuginfod is packaged with elfutils, starting with version 0.178.
+You can get the latest version from `https://sourceware.org/elfutils/'.
+
@node Reporting Bugs
@chapter Reporting Bugs
@cindex bugs
projects / deliverable / binutils-gdb.git / blobdiff