dwarfdump - dumps DWARF debug information of an ELF object
dwarfdump [options] objectfilename
DWARFDUMP() DWARFDUMP()
NAME
dwarfdump - dumps DWARF debug information of an ELF object
SYNOPSIS
dwarfdump [options] objectfilename
DESCRIPTION
The dwarfdump command prints or checks DWARF sections as requested by
specific options. With no options (but with the required objectfile-
name ) all sections print (but some sections cannot be printed indepen-
dently safely, so those are only printed at offsets where the
.debug_info section refers to those sections).
All options are available in the traditional (single-letter) form and
in a long-options form with meaningful names.
With no options dwarfdump prints a basic set of DWARF section informa-
tion. If any option is given on the command line the basic set is
ignored and one must tell dwarfdump what to print or check (for example
by adding the -a option).
As of June 2011 the printing options and the checking options are mutu-
ally exclusive (if checking options are selected the section details
are not printed). When errors are encountered dwarfdump does attempt to
print sufficient context so that one can understand exactly where the
error is in the DWARF. This change makes checking really large object
files much easier.
The format is intended to be human readable. If a script is to parse
the output, the --format-dense (-d) option is useful.
Not all sections actually exist in any given object file.
The format may change from release to release, so it is unwise to
depend too heavily on the format.
Frame information (.debug_frame and .eh_frame) is heavily dependent on
the ABI/ISA of the object file. By default we use a generic set of
register names handling up to 100 registers named r0-r99.
The --format-registers (-R) option uses a built-in generic register
name set handling up to 1200 registers named r0-r1199.
The -file-abi=<abi> (-x abi=<abi>) description below shows how to name
an abi and use that to guide the --print-frame (-f) or --print-eh-
frame (-F) processing.
Unless one of --print-frame (-f) or --print-eh-frame (-F) or --print-
all (-a) is used any abi reference is ignored because no frame data
will be printed.
Unless the cpu for the object file being dumped has many registers, do
not use --format-registers or -file-abi=<abi> as those can be need-
lessly slow dumping frame sections. Instead, use the correct abi (if it
exists in dwarfdump.conf) or a generic such as --file-
abi=abi=generic100 or --file-abi=abi=generic500
.
The most useful abi choices are likely mips or x86 or x86_64 or ppc or
arm
. Without --format-registers (-R) or -file-abi=<abi> (-x abi=<abi>)
dwarfdump ignores the dwarfdump.conf file and uses compiled-in generic
set of register names. If no --file-name=<path> (-x name=<path>) is
given, dwarfdump looks for "./dwarfdump.conf", "$HOME/.dwarfdump.conf",
"<install-prefix>/lib/dwarfdump.conf" and takes the first it finds. If
one or more --file-name=<path> (-x name=<path>) is given the last of
these is used and all other such files are ignored.
Some checking ( -k) options (See "Check DWARF Integrity" in the help
output) print so-called harmless errors. These are compiler errors
that do not cause any known problem and are only detected inside libd-
warf itself. These are difficult to properly report in dwarfdump and
any error strings may not appear close to the time the error was
encountered.
If zlib compression was used on the DWARF sections in the object file
being read the real section names such as .zdebug_info etc will be
reported by dwarfdump. When dwarfdump says something is at offset 55
of .zdebug_info (or the like) keep in mind that the offset applies to
the uncompressed section (in memory), not the .zdebug_ compressed sec-
tion in objectfilename.
URI STYLE INPUT STRINGS
The <objectfilename> and all the options taking name strings look for
URIs and translate the URI strings to characters by default. So any
single % character is treated as if the following two characters are
hex digits representing the underlying true character. Various charac-
ters are meaningful to shells (such as bash or sh) and to getopt (such
as the space character) If the URI translation does anything it prints
the before and after of the URI translation on standard output, so
inspection of the first lines of output will show if URI did anything.
The actual options themselves are assumed to be non-URI. So in the
option --format-producer=S&T (-cS&T) the & character might cause input
issues so --format-producer=S%26T should be used instead. To actually
input a single % character (in a name, for example), double it to %% on
the command line (or simply use %25).
Options --format-suppress-uri (-U) (turning off URI interpretation) and
--format-suppress-uri-msg (-q) (making finding URI sequences silent)
give finer control of URI interpretation. PP As an example, to get a
string'a b' make the string 'a%20b' (here the quote (') is for exposi-
tion not part of the string, though quote is certainly problematic in a
name). Instead of escaping " quotes in the string, type %25, as in
'a "b' should be typed 'a%20%25b' Any characters can be typed in URI
style, not just characters which are problematic to the shell or
getopt. We strongly suggest you not type URI-style characters where
such are not needed or use the % character itself in command line
strings unless you must.
PRINTING OPTIONS
--print-all (-a)
Print each section as independently as possible. Sections that
can safely be printed independently (like .debug_abbrev) have
relevant info printed in the report (sometimes dependent on -v).
--print-abbrev (-b)
Print the .debug_abbrev section. Because the DWARF specifica-
tions do not rule out garbage data areas in .debug_abbrev (if
they are not referenced from .debug_info) any garbage bytes can
result in this print failing.
--print-loc (-c)
Print locations lists.
--elf (-E)
prints, for Elf objects, object file details. See the "Print
ELF sections header" section of the help file for additional
choices on elf printing. If libdwarf or dwarfdump is built
without libelf this option is unavailable.
--print-frame (-f)
Print the .debug_frame section.
--print-eh-frame (-F)
Print the GNU .eh_frame section.
--print-info (-i)
Print the .debug_info section.
--print-fission (-I)
Print any .gdb_index, .debug_cu_index, and .debug_tu_index sec-
tions that exist in the object.
--print-gnu-debuglinkIfthe.gnu_debuglinksection
is present its content is printed. If the .note.gnu.build-id
section is present its content is printed. If a DWARF contain-
ing file named by the content of the .gnu_debuglink section
exists the name will be printed.
--print-lines (-l)
Print the .debug_info section and the associated line section
data.
--print-lines-short (-ls)
Print the .debug_info section and the associated line section
data, but omit the <pc> address. Useful when a comparison of
line sections from objects with slight differences is required.
--print-macinfo (-m)
Print the .debug_macinfo (DWARF 2,3,4) and .debug_macro (DWARF5)
sections.
--print-ranges (-N)
Print .debug_ranges section. Because the DWARF specifications
do not rule out garbage data areas in .debug_ranges (if they are
not referenced from .debug_info) any garbage bytes can result in
this print failing.
--print-pubnames (-p)
Print the .debug_pubnames section.
--print-str-offsets
Print the .debug_str_offsets section.
--print-aranges (-r)
Print the .debug_aranges section.
--print-strings (-s)
Print .debug_string section.
--print-static (-ta)
Print the IRIX only sections .debug_static_funcs and
.debug_static_vars.
--print-type (-y)
Print the .debug_pubtypes section (and .debug_typenames, an SGI
IRIX-only section).
Having dwarfdump print relocations may help establish whether dwarfdump
understands any relocations that might exist. Other tools may be more
useful than dwarfdump for printing object-file details. See "Print
Relocations Info" in the help output for additional relocation printing
choices.
--reloc (-o)
Print all relocation records as well as we can manage. If libd-
warf or dwarfdump were built without libelf this option is
unavailable.
--version (-V)
Print a dwarfdump date/version string and stop.
CHECKING OPTIONS
--check-all (-ka)
Turns on all checking options except --check-frame-
extended (-kxe) (which might be slow enough one might not want
to use it routinely.)
--check-abbrev (-kb)
Checks for certain abbreviations section errors when reading
DIEs.
--check-constants (-kc)
Checks for errors in constants in debug_info.
-check-show (-kd)
Turns on full reporting of error totals per producer. (the
default shows less detail).
--check-silent-ks
Turns off some verbose checking detection.
--check-attr-dup (-kD)
Turns on reporting of duplicated attributes. Duplicated
attributes on a single DW_TAG are improper DWARF, but at least
one compiler emitted such.
--check-pubnames (-ke)
Turns on reading pubnames and checking for fde errors.
--check-attr-encodings (-kE)
Checks the integer encoding representation in debug_info, com-
puting whether these integer values could fit in fewer bytes if
represented in LEB128.
--check-frame-info (-kf)
Turns on checking for FDE errors (.debug_frame and .eh_frame).
--check-files-lines (-kF)
Turns on checking for line table errors.
--check-gaps (-kg)
Turns on checking for unused gaps in .debug_info (these gaps are
not an error, just a waste of space).
--check-unique (-kG)
Print only unique errors. Error lines are simpified (hex numbers
removed, for example) and when a given message string would oth-
erwise appear again it is suppressed.
--check-summary (-ki)
Causes a summary of checking results per compiler (producer) to
be printed at the end.
--check-loc (-kl)
Turns on locations list checking.
--check-ranges (-km)
Turns on checking of ranges.
--check-aranges (-kM)
Turns on checking of aranges.
--check-tag-attr (-kr)
Turns on DIE tag-attr combinations checking, looking for sur-
prising attributes for DIE tags.
--check-forward-refs (-kR)
Turns on reading DIEs and checking for forward declarations from
DW_AT_specification attributes. (which are not an error but can
be a source of inefficiency for debuggers).
--check-self-refs (-kS)
Turns on checking DIE references for circular references.
--check-tag-tag (-kt)
Turns on tag-tag combinations checking, looking for surprising
parent-child DIE relationships.
--check-usage (-ku)
Print tag-tree and tag-attribute usage (basic format).
--check-usage-extended (-kuf)
Print tag-tree and tag-attribute usage (full format). For stan-
dard TAGs and ATtributes this presents an overview of how they
were used.
--check-frame-basic (-kx)
Turns on basic frames checking for .debug_frame and .eh_frame).
--check-frame-extended (-kxe)
Turns off basic check_frames and turns on extended frame check-
ing for .debug_frame and .eh_frame. This option can be slow.
--check-type (-ky)
Turns on type_offset checking (ensuring local attribute offsets
refer to what they should) and that DW_AT_decl_file and some
other offsets refer to appropriate locations.
OPTION MODIFIERS
--format-extensions (-C)
Normally when checking for tag-tag or tag-attribute combinations
both the standard combinations and some common extensions are
allowed. With -C the extensions are taken out of the allowed
class of combinations.
--format-dense (-d)
When printing DIEs, put all the attributes for each DIE on the
same (long) line as the TAG. This makes searching for DIE infor-
mation (as with grep) much simpler as the entire DIE is on one
line.
--format-supress-offsets (-D)
Turns off the display of section offsets and attribute values in
printed output. So the .debug_info output is just TAGs and
Attributes. For pubnames (and the like) it removes offsets from
the output. For locations lists it removes offsets from the
output, but that is useless since the attribute values don't
show so neither does the location data.
--format-ellipsis (-e)
Turns on truncation of attribute and tag names. For example
DW_TAG_foo becomes foo. Not compatible with checking, only use-
ful for printing DIEs.
--format-global-offsets (-G)
When printing, add global offsets to the offsets printed.
--format-limit=<num> (-H number)
When printing or checking .debug_info, this terminates the
search after 'number' compilation units. When printing frame
information this terminates the FDE reporting after 'number'
FDEs and the CIE reporting (which occurs if one adds -v) after
'number' CIEs. Example '--format-limit=1'
--format-attr-name (-M)
When printing, show the FORM for each attribute. If a -v is
added (or more than one) then details of any form indirection
are also shown.
--format-suppress-lookup (-n)
When printing frames, this turns off the search for function
names. In a really large object the search can take more time
than one wants to wait, so this avoids the search.
--file-output=<path> (-Ofile=<path>)
The <path> will be used as the file name for output instead of
writing to stdout (stdout is the default).
-format-suppress-data (-Q)
Suppresses section data printing (set automatically with a
checking option).
--format-registers (-R)
When printing frames for ABIs with lots of registers, this
allows up to 1200 registers to be named (like R999) without
choosing an ABI with, for example '-x abi=ppc'
--version (-v)
Increases the detail shown when printing. In some sections,
using more -v options will increase the detail (one to three are
useful) or may change the report to show, for example, the
actual line-data-commands instead of the resultant line-table.
SELECTIVE ENTRY PRINTING
These --search (-S) options stand alone and basic print information
about the compilation unit and DIE where the string(s) appear. At most
one of each of the following is effective (so for example one can only
have one 'match', but one can have a 'match', an 'any', and a 'regex').
Any --search (-S) causes the .debug_info section to be inspected. No
checking options or printing options should be supplied with
--search(-S) options. The strings should use URI-style to avoid any
conflicts with the command-line parser applicable (bash, sh, ...) or
getopt().
These are particularly useful when the amount of DWARF information is
really large.
If v is added to the -S option, the number of occurrences is printed.
(see below for an example).
--search-match=<string> (-Smatch=string)
--search-match-count=<string> (-Svmatch=string)
When printing DIEs for each tag value or attribute name that
matches 'string' exactly print the compilation unit information
and its section offset. Any CU with no match is not printed.
The 'string' is read as a URI string. The count (Sv) form
reports the count of occurrences.
--search-any=<string> (-Sany=string)
--search-any-count=<string> (-Svany=string)
When printing DIEs for each tag value or attribute name that
contains 'string' somewhere in the tag or attribute (case insen-
sitive) print the compilation unit information and its section
offset. Any CU with no match is not printed. The 'string' is
read as a URI string. The count (Sv) form reports the count of
occurrences.
--search-regex=string (-Sregex=string)
--search-regex-count=string (-Svregex=string)
When printing DIEs for each tag value or attribute name where
the 'string' reqular expression matches print the compilation
unit information and its section offset. Any CU with no match
is not printed. The 'string' is read as a URI string. The
count (Sv) form reports the count of occurrences.
The string cannot have spaces or other characters which are meaningful
to getopt(3) and the shell will strip off quotes and other characters.
So the string is assumed to be in URI style and is translated. In
other words, to match 'a b' make the -S string 'a%20b' Instead of
escaping " quotes in the string, type %25, as in
'a "b' should be typed 'a%20%25b' (the ' are for exposition here, not
part of the strings). Any characters can be typed in URI style, not
just characters which are problematic to the shell or getopt.
The --search-any (-Sany) and --regex-any (-Sregex) options are only
usable if regular-expression library functions required are found at
configure time.
The --search-print (-W) option is a modifier to the -S option, and
increases the amount of output -S prints. An example v modifier to the
-S option is shown below. And we show the -W in context with a -S
option.
--search-match-count=string1 (-S vmatch=string1)
Prints information about the DIEs that -S matches and prints the
count of occurrences.
-S match=string1 -W
--search-match=string1 --search-print-tree
Prints the parent tree and the children tree for the DIEs that
-S matches.
-S match=string2 -Wp
--search-match=string2 --search-print-parent
Prints the parent tree for the DIEs that -S matches.
-S match=string3 -Wc
--search-match=string3 --search-print-children
Prints the children tree for the DIEs that -S matches.
--format-gcc (-cg)
Restricts printing/checking to compilers whose producer string
starts with 'GNU' and turns off -cs.
--format-snc (-cs)
Restricts printing/checking to compilers whose producer string
starts with 'SN' and turns off -cg.
--format-producer=<name> (-c<name>)
Restricts printing/checking to compilers whose producer string
contains 'name' (not case sensitive). The 'name' is read as a
URI string.
OTHER OPTIONS
-x name=<path>
--file-name=/p/a/t/h.conf (-xname=/p/a/t/h.conf)
The file path given is the name of a file assumed to be a dwarf-
dump.conf-like file. The file path is read as a URI string.
-x abi=ppc
--file-abi=ppc
Selects the abi (from a dwarfdump.conf file) to be used in
printing frame information (here using ppc as an example). The
abi is read as a URI string.
--format-group=<n> (-x groupnumber=<n>)
For an object file with both DWARF5 split dwarf (.debug_info.dwo
for example) and ordinary DWARF sections (.debug_info for exam-
ple) in the single object file one must use --format-group=2 to
print the dwo sections. Adding --file-tied=<path> naming the
same object file ties in the non-dwo sections.
-x tied=/t/i/depath
--file-tied=/t/i/depath
Used when opening a main object that is a .dwo or .dwp file.
The tied file path names the executable which has the
.debug_addr section that may be referred to from the main
object. See Split Objects (aka Debug Fission).
-x line5=s2l
--file-line5=s2l
Normally used only to test libdwarf interfaces. There are 4
different interface function sets and to ensure they all work
this option lets us choose which to use. The options are 's2l'
(default, Allows standard and two-level line tables using the
latest interface functions), 'std' (Allows standard single level
line tables using the latest interface functions), 'orig'
(allows DWARF2,3,4 original line tables using an older interface
function set), 'orig2l' (allows original line tables and some
two-level line tables using an older interface set).
--print-producers
-P When checking this adds the list of compilation-unit names
seen for each producer-compiler to the printed checking results.
-q
--format-suppress-uri-msg
When a URI is found and translated while reading the command
line, be quiet about the URI translation. That is, don't print
the original and translated option strings.
-u cuname
--format-file=<file>
Turns on selective printing of DIEs (printing like -i). Only
the DIEs for a compilation unit that match the name provided are
printed. If the compilation unit is ./a/b/c.c the 'cuname' you
provide should be c.c as the characters through the final path-
separating / are ignored. If 'cuname' begins with a / then the
entire name string of a compilation unit must match 'cuname'.
The 'file' is read as a URI string.
-U
--format-suppress-uri
Turn off the URI interpretation of the command line strings
entirely. Must be be on the command line before any URI strings
encountered to be fully effective. Likely something no one
needs to do.
-h
--help Show this man page.
FILES
dwarfdump
./dwarfdump.conf
$(HOME)/.dwarfdump.conf
$(HOME)/dwarfdump.conf
<install-prefix>/lib/dwarfdump.conf
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/libdwarf |
+---------------+------------------+
|Stability | Volatile |
+---------------+------------------+
NOTES
In some cases compilers use DW_FORM_data1 (for example) and in such
cases the signedness of the value must be taken from context. Rather
than attempt to determine the context, dwarfdump prints the value with
both signednesses whenever there is ambiguity about the correct inter-
pretation. For example, "DW_AT_const_value 176(as signed =
-80)". For normal DWARF consumers that correctly and fully evaluate
all attributes there is no ambiguity of signedness: the ambiguity for
dwarfdump is due to dwarfdump evaluating DIEs in a simple order and not
keeping track of much context.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://www.prevanders.net/libd-
warf-20191104.tar.gz.
Further information about this software can be found on the open source
community website at https://www.prevanders.net/dwarf.html.
BUGS
Support for DWARF5 is being completed but may not be complete.
DWARFDUMP()