1DWARFDUMP() DWARFDUMP()
2
6 dwarfdump - dumps DWARF debug information of an ELF object
7
9 dwarfdump [options] objectfilename
10
12 The dwarfdump command prints or checks DWARF sections as requested by
13 specific options. With no options (but with the required objectfile‐
14 name ) all sections print (but some sections cannot be printed indepen‐
15 dently safely, so those are only printed at offsets where the
16 .debug_info section refers to those sections).
17 For split-dwarf (DWARF5) object files see Split Object Files, DWARF5
19 section 7.3.
20 Nearly all options are available in the traditional (single-letter)
23 form and in a long-options form with meaningful names. New options are
24 only in the long-options form.
25 With no options dwarfdump prints a basic set of DWARF section informa‐
28 tion. If any option is given on the command line the basic set is
29 ignored and one must tell dwarfdump what to print or check (for example
30 by adding the -a option).
31 As of June 2011 the printing options and the checking options are mutu‐
34 ally exclusive (if checking options are selected the section details
35 are not printed). When errors are encountered dwarfdump does attempt to
36 print sufficient context so that one can understand exactly where the
37 error is in the DWARF. This change makes checking really large object
38 files much easier.
39 The format is intended to be human readable. If a script is to parse
41 the output, the --format-dense (-d) option is useful.
42 Not all sections actually exist in any given object file.
44 The output format may change from release to release, so it is unwise
46 to depend too heavily on the format.
47 Frame information (.debug_frame and .eh_frame) is heavily dependent on
49 the ABI/ISA of the object file. By default we use a generic set of
50 register names handling up to 100 registers named r0-r99.
51 As of 2020 there are three different ways compiler writers separate the
53 DWARF information from an executable/shared-object. One is DWARF5
54 Split Dwarf (the --file-tied option is useful for these). Another ls
55 GNU debuglink (libdwarf automatically finds the DWARF when given the
56 name of the executable, use --no-follow-debuglink to suppress this and
57 make possible printing the backtrace data in section .eh_frame). The
58 third way is on MacOS: the debug DWARF is in a separate object (dwarf‐
59 dump/libdwarf automatically find it if it is present, --no-follow-
60 debuglink suppresses this finding).
61 In many cases one can get additional detail by specifying -v (sometimes
63 -v -v gets even more). When printing DIEs (Debugging Information
64 Entries) the options -G (showing global offsets) and -M (naming the
65 DW_FORM* of attributes) (or their -- counterparts) can be a great aid
66 to understanding DWARF..
67 The --format-registers (-R) option uses a built-in generic register
69 name set handling up to 1200 registers named r0-r1199.
70 The -file-abi=<abi> (-x abi=<abi>) description below shows how to name
72 an abi and use that to guide the --print-frame (-f) or --print-eh-
73 frame (-F) processing.
74 Unless one of --print-frame (-f) or --print-eh-frame (-F) or --print-
76 all (-a) is used any abi reference is ignored because no frame data
77 will be printed.
78 Unless the cpu for the object file being dumped has many registers, do
81 not use --format-registers or -file-abi=<abi> as those can be need‐
82 lessly slow dumping frame sections. Instead, use the correct abi (if it
83 exists in dwarfdump.conf) or a generic such as --file-
84 abi=abi=generic100 or --file-abi=abi=generic500
85 .
86 The most useful abi choices are likely mips or x86 or x86_64 or ppc or
88 arm
89 . Without --format-registers (-R) or -file-abi=<abi> (-x abi=<abi>)
90 dwarfdump ignores the dwarfdump.conf file and uses compiled-in generic
91 set of register names. If no --file-name=<path> (-x name=<path>) is
92 given, dwarfdump looks for "./dwarfdump.conf", "$HOME/.dwarfdump.conf",
93 "<install-prefix>/lib/dwarfdump.conf" and takes the first it finds. If
94 one or more --file-name=<path> (-x name=<path>) is given the last of
95 these is used and all other such files are ignored.
96 Some checking ( -k) options (See "Check DWARF Integrity" in the help
98 output) print so-called harmless errors. These are compiler errors
99 that do not cause any known problem and are only detected inside libd‐
100 warf itself. These are difficult to properly report in dwarfdump and
101 any error strings may not appear close to the time the error was
102 encountered.
103 If zlib compression was used on the DWARF sections in the object file
105 being read the real section names such as .zdebug_info etc will be
106 reported by dwarfdump. When dwarfdump says something is at offset 55
107 of .zdebug_info (or the like) keep in mind that the offset applies to
108 the uncompressed section (in memory), not the .zdebug_ compressed sec‐
109 tion in objectfilename.
110
112 The <objectfilename> and all the options taking name strings look for
113 URIs and translate the URI strings to characters by default. So any
114 single % character is treated as if the following two characters are
115 hex digits representing the underlying true character. Various charac‐
116 ters are meaningful to shells (such as bash or sh) and to getopt (such
117 as the space character) If the URI translation does anything it prints
118 the before and after of the URI translation on standard output, so
119 inspection of the first lines of output will show if URI did anything.
120 The actual options themselves are assumed to be non-URI. So in the
121 option --format-producer=S&T (-cS&T) the & character might cause input
122 issues so --format-producer=S%26T should be used instead. To actually
123 input a single % character (in a name, for example), double it to %% on
124 the command line (or simply use %25).
125 Options --format-suppress-uri (-U) (turning off URI interpretation) and
127 --format-suppress-uri-msg (-q) (making finding URI sequences silent)
128 give finer control of URI interpretation.
129 As an example, to get a string'a b' make the string 'a%20b' (here the
131 quote (') is for exposition not part of the string, though quote is
132 certainly problematic in a name). Instead of escaping " quotes in the
133 string, type %25, as in
134 'a "b' should be typed 'a%20%25b' Any characters can be typed in URI
135 style, not just characters which are problematic to the shell or
136 getopt. We strongly suggest you not type URI-style characters where
137 such are not needed or use the % character itself in command line
138 strings unless you must.
139
141 Dwarfdump translates any characters in strings which are not ordinary
142 printable ASCII (and some which are ASCII) in the reverse of the previ‐
143 ous section. It prints into a uri-style output in the form %xx, where
144 xx are hex digits in the form of ASCII 0-9a-0f. The percent charac‐
145 ter(%) is printed as '%25'
146 This is a clumsy way to deal with UTF-8 strings and sensible way to
148 deal with the low ASCII values that on many systems cause one's termi‐
149 nal to behave oddly. Such translations are not idempotent so dwarfdump
150 avoids doing the translation more than once on any string. See option
151 --format-suppress-sanitize below to eliminate the output transforma‐
152 tion.
153
156 --print-all (-a)
157 Print each section as independently as possible. Sections that
158 can safely be printed independently (like .debug_abbrev) have
159 relevant info printed in the report (sometimes dependent on -v).
160 --print-abbrev (-b)
163 Print the .debug_abbrev section. Because the DWARF specifica‐
164 tions do not rule out garbage data areas in .debug_abbrev (if
165 they are not referenced from .debug_info) any garbage bytes can
166 result in this print failing.
167 --print-loc (-c)
170 Print locations lists.
171 --print-debug-gnu
174 Print the .debug_gnu_pubnames and .debug_gnu_typenames sec‐
175 tions.
176 --print-fission
179 Print the .gdb_index, .debug_cu_index,
180 .debug_tu_index, .gnu.debuglink,
181 and .note.gnu.build-id sections.
182 --print-gnu-debuglink
185 Print .gnu_debuglink and .note.gnu.build-id sections
186 --elf (-E)
189 prints, for Elf objects, object file details. See the "Print
190 ELF Section Headers" section of the help file for additional
191 choices on elf printing. If libdwarf or dwarfdump is built
192 without libelf this and related options are not available.
193 --print-frame (-f)
196 Print the .debug_frame section.
197 --print-eh-frame (-F)
199 Print the GNU .eh_frame section.
200 --print-info (-i)
203 Print the .debug_info section.
204 --print-fission (-I)
207 Print any .gdb_index, .debug_cu_index, and .debug_tu_index sec‐
208 tions that exist in the object.
209 --print-gnu-debuglink
212 If the .gnu_debuglink section is present its content is printed.
213 If the .note.gnu.build-id section is present its content is
214 printed. If a DWARF containing file named by the content of the
215 .gnu_debuglink section exists the name will be printed.
216 --print-lines (-l)
219 Print the .debug_info section and the associated line section
220 data.
221 --print-lines-short (-ls)
223 Print the .debug_info section and the associated line section
224 data, but omit the <pc> address. Useful when a comparison of
225 line sections from objects with slight differences is required.
226 --print-macinfo (-m)
229 Print the .debug_macinfo (DWARF 2,3,4) and .debug_macro (DWARF5)
230 sections.
231 --print-ranges (-N)
234 Print .debug_ranges section. Because the DWARF specifications
235 do not rule out garbage data areas in .debug_ranges (if they are
236 not referenced from .debug_info) any garbage bytes can result in
237 this print failing.
238 --print-pubnames (-p)
241 Print the .debug_pubnames section.
242 --print-str-offsets
245 Print the .debug_str_offsets section.
246 --print-aranges (-r)
249 Print the .debug_aranges section.
250 --print-strings (-s)
252 Print .debug_string section.
253 --print-static (-ta)
256 Print the IRIX only sections .debug_static_funcs and
257 .debug_static_vars.
258 --print-type (-y)
261 Print the .debug_pubtypes section (and .debug_typenames, an SGI
262 IRIX-only section).
263 Having dwarfdump print relocations may help establish whether dwarfdump
266 understands any relocations that might exist. Other tools may be more
267 useful than dwarfdump for printing object-file details. If dwarfdump
268 or libelf is built without libelf the relocation options are not avail‐
269 able. See "Print Elf Relocation Data" in the help output for addi‐
270 tional relocation printing choices.
271 --reloc (-o)
274 Print all relocation records as well as we can manage. If libd‐
275 warf or dwarfdump were built without libelf this option is
276 unavailable.
277 --version (-V)
280 Print a dwarfdump date/version string and stop.
281
284 --check-all (-ka)
285 Turns on all checking options except --check-frame-
286 extended (-kxe) (which might be slow enough one might not want
287 to use it routinely.)
288 --check-abbrev (-kb)
291 Checks for certain abbreviations section errors when reading
292 DIEs.
293 --check-constants (-kc)
296 Checks for errors in constants in debug_info.
297 -check-show (-kd)
299 Turns on full reporting of error totals per producer. (the
300 default shows less detail).
301 --check-silent-ks
303 Turns off some verbose checking detection.
304 --check-attr-dup (-kD)
307 Turns on reporting of duplicated attributes. Duplicated
308 attributes on a single DW_TAG are improper DWARF, but at least
309 one compiler emitted such.
310 --check-pubnames (-ke)
312 Turns on reading pubnames and checking for fde errors.
313 --check-attr-encodings (-kE)
315 Checks the integer encoding representation in debug_info, com‐
316 puting whether these integer values could fit in fewer bytes if
317 represented in LEB128.
318 --check-frame-info (-kf)
321 Turns on checking for FDE errors (.debug_frame and .eh_frame).
322 --check-files-lines (-kF)
324 Turns on checking for line table errors.
325 --check-gaps (-kg)
327 Turns on checking for unused gaps in .debug_info (these gaps are
328 not an error, just a waste of space).
329 --check-unique (-kG)
331 Print only unique errors. Error lines are simpified (hex numbers
332 removed, for example) and when a given message string would oth‐
333 erwise appear again it is suppressed.
334 --check-summary (-ki)
336 Causes a summary of checking results per compiler (producer) to
337 be printed at the end.
338 --check-loc (-kl)
341 Turns on locations list checking.
342 --check-ranges (-km)
344 Turns on checking of ranges.
345 --check-aranges (-kM)
347 Turns on checking of aranges.
348 --check-tag-attr (-kr)
350 Turns on DIE tag-attr combinations checking, looking for sur‐
351 prising attributes for DIE tags. It does not report common
352 extensions as errors. Common extensions to the standard are
353 allowed as if standard. See the -C (--format-extensions) option
354 to show common extensions as errors.
355 --check-forward-refs (-kR)
357 Turns on reading DIEs and checking for forward declarations from
358 DW_AT_specification attributes. (which are not an error but can
359 be a source of inefficiency for debuggers).
360 --check-self-refs (-kS)
362 Turns on checking DIE references for circular references.
363 --check-tag-tag (-kt)
365 Turns on tag-tag combinations checking, looking for surprising
366 parent-child DIE relationships. It does not report common
367 extensions as errors. Common extensions to the standard are
368 allowed as if standard. See the -C (--format-extensions) option
369 to show common extensions as errors.
370 --check-usage (-ku)
372 Print tag-tree and tag-attribute usage (basic format).
373 --check-usage-extended (-kuf)
375 Print tag-tree and tag-attribute usage (full format). For stan‐
376 dard TAGs and ATtributes this presents an overview of how they
377 were used.
378 --check-frame-basic (-kx)
381 Turns on basic frames checking for .debug_frame and .eh_frame).
382 --check-frame-extended (-kxe)
384 Turns off basic check_frames and turns on extended frame check‐
385 ing for .debug_frame and .eh_frame. This option can be slow.
386 --check-type (-ky)
389 Turns on type_offset checking (ensuring local attribute offsets
390 refer to what they should) and that DW_AT_decl_file and some
391 other offsets refer to appropriate locations.
392
395 --format-extensions (-C)
396 This is a secondary option after --check-tag-tag (-kt) or
397 --check-tag-attr (-kr). Normally when checking for tag-tag or
398 tag-attribute combinations both the standard combinations and
399 some common extensions are allowed (not reported). With this
400 option the extensions are taken out of the class of allowed com‐
401 binations.
402 --format-dense (-d)
405 When printing DIEs, put all the attributes for each DIE on the
406 same (long) line as the TAG. This makes searching for DIE infor‐
407 mation (as with grep) much simpler as the entire DIE is on one
408 line.
409 --format-supress-offsets (-D)
412 Turns off the display of section offsets and attribute values in
413 printed output. So the .debug_info output is just TAGs and
414 Attributes. For pubnames (and the like) it removes offsets from
415 the output. For locations lists it removes offsets from the
416 output, but that is useless since the attribute values don't
417 show so neither does the location data.
418 --format-ellipsis (-e)
421 Turns on truncation of attribute and tag names. For example
422 DW_TAG_foo becomes foo. Not compatible with checking, only use‐
423 ful for printing DIEs.
424 --format-global-offsets (-G)
427 When printing, add global offsets to the offsets printed.
428 --format-limit=<num> (-H number)
431 When printing or checking .debug_info, this terminates the
432 search after 'number' compilation units. When printing frame
433 information this terminates the FDE reporting after 'number'
434 FDEs and the CIE reporting (which occurs if one adds -v) after
435 'number' CIEs. Example '--format-limit=1'
436 --format-attr-name (-M)
439 When printing, show the FORM for each attribute. If a -v is
440 added (or more than one) then details of any form indirection
441 are also shown.
442 --format-suppress-lookup (-n)
445 When printing frames, this turns off the search for function
446 names in inner scopes. Unless the language used to build the
447 object file supports function definitions in inner scopes there
448 is no point in looking for function names in inner scopes. And
449 a really large object the search can take more time than one
450 wants to wait. This option suppresses the inner scope search.
451 --file-output=<path> (-Ofile=<path>)
454 The <path> will be used as the file name for output instead of
455 writing to stdout (stdout is the default).
456 --format-suppress-data (-Q)
459 Suppresses section data printing (set automatically with a
460 checking option).
461 --format-suppress-sanitize
464 Suppresses the default string-printing translations so non-ascii
465 and non-printable characters from the object file are printed
466 as-is. See "URI-STYLE OUTPUT" above.
467 --format-suppress-uri (-U)
470 Suppresses the default URI translation of following options on
471 the command line. See "URI-STYLE INPUT STRINGS" above.
472 --format-registers (-R)
475 When printing frames for ABIs with lots of registers, this
476 allows up to 1200 registers to be named (like R999) without
477 choosing an ABI with, for example '-x abi=ppc' or, equivalently,
478 '--file-abi=ppc'
479 --version (-v)
482 Increases the detail shown when printing. In some sections,
483 using more -v options will increase the detail (one to three are
484 useful) or may change the report to show, for example, the
485 actual line-data-commands instead of the resultant line-table.
486
489 The simplist limiting option is to stop the examination/printing after
490 <num> compilation units. See -H and --format-limit above. This
491 option also limits the number of FDEs and CIEs printed from any
492 .debug_frame or .eh_frame section.
493 The --search (-S) options stand alone and basic print information about
496 the compilation unit and DIE where the string(s) appear. At most one
497 of each of the following is effective (so for example one can only have
498 one 'match', but one can have a 'match', an 'any', and a 'regex'). Any
499 --search (-S) causes the .debug_info section to be inspected. No
500 checking options or printing options should be supplied with
501 --search(-S) options. The strings should use URI-style to avoid any
502 conflicts with the command-line parser applicable (bash, sh, ...) or
503 getopt(), as well as using URI to deal with searching for strings in
504 non-ASCII such as French, (etc) or the now-nearly-universal UTF8.
505 These are particularly useful when the amount of DWARF information out‐
507 put by -i is multiple gigabytes of data.
508 If v is added to the -S option, the number of occurrences is printed.
510 (see below for an example).
511 --search-match=<string> (-Smatch=string)
514 --search-match-count=<string> (-Svmatch=string)
516 When printing DIEs for each tag value or attribute name that
517 matches 'string' exactly print the compilation unit information
518 and its section offset. Any CU with no match is not printed.
519 The 'string' is read as a URI string. The count (Sv) form
520 reports the count of occurrences.
521 --search-any=<string> (-Sany=string)
524 --search-any-count=<string> (-Svany=string)
526 When printing DIEs for each tag value or attribute name that
527 contains 'string' somewhere in the tag or attribute (case insen‐
528 sitive) print the compilation unit information and its section
529 offset. Any CU with no match is not printed. The 'string' is
530 read as a URI string. The count (Sv) form reports the count of
531 occurrences.
532 --search-regex=string (-Sregex=string)
535 --search-regex-count=string (-Svregex=string)
537 When printing DIEs for each tag value or attribute name where
538 the 'string' reqular expression matches print the compilation
539 unit information and its section offset. Any CU with no match
540 is not printed. The 'string' is read as a URI string. The
541 count (Sv) form reports the count of occurrences.
542 The string cannot have spaces or other characters which are meaningful
545 to getopt(3) and the shell will strip off quotes and other characters.
546 So the string is assumed to be in URI style and is translated. In
547 other words, to match 'a b' make the -S string 'a%20b' Instead of
548 escaping " quotes in the string, type %25, as in
549 'a "b' should be typed 'a%20%25b' (the ' are for exposition here, not
550 part of the strings). Any characters can be typed in URI style, not
551 just characters which are problematic to the shell or getopt.
552 The --search-any (-Sany) and --regex-any (-Sregex) options are only
554 usable if regular-expression library functions required are found at
555 configure time.
556 The --search-print (-W) option is a modifier to the -S option, and
558 increases the amount of output -S prints. An example v modifier to the
559 -S option is shown below. And we show the -W in context with a -S
560 option.
561 --search-match-count=string
564 Prints information about the DIEs that -S matches and prints the
565 count of occurrences.
566 -S match=string1 -W
569 --search-match=string1 --search-print-tree
572 Prints the parent tree and the children tree for the DIEs that
573 --search-match matches.
574 -S match=string2 -Wp
577 --search-match=string2 --search-print-parent
580 Prints the parent tree for the DIEs that -S matches.
581 -S match=string3 -Wc
584 --search-match=string3 --search-print-children
586 Prints the children tree for the DIEs that -S matches.
587 --format-gcc (-cg)
590 Restricts printing/checking to compilers whose producer string
591 starts with 'GNU' and turns off -cs.
592 --format-snc (-cs)
595 Restricts printing/checking to compilers whose producer string
596 starts with 'SN' and turns off -cg.
597 --format-producer=<name> (-c<name>)
600 Restricts printing/checking to compilers whose producer string
601 contains 'name' (not case sensitive). The 'name' is read as a
602 URI string.
603
607 -x name=<path>
608 --file-name=/p/a/t/h.conf (-xname=/p/a/t/h.conf)
610 The file path given is the name of a file assumed to be a dwarf‐
611 dump.conf-like file. The file path is read as a URI string.
612 -x abi=ppc
615 --file-abi=ppc
617 Selects the abi (from a dwarfdump.conf file) to be used in
618 printing frame information (here using ppc as an example). The
619 abi is read as a URI string.
620 --format-group=<n> (-x groupnumber=<n>)
623 For an object file with both DWARF5 split dwarf (.debug_info.dwo
624 for example) and ordinary DWARF sections (.debug_info for exam‐
625 ple) in the single object file one must use --format-group=2 to
626 print the dwo sections. Adding --file-tied=<path> naming the
627 same object file ties in the non-dwo sections.
628 -x tied=/t/i/depath
631 --file-tied=/t/i/depath
633 Used when opening a main object that is a .dwo or .dwp file.
634 For example if /path/to/myapp.dwp is the split-dwarf object and
635 /path/to/myapp is the executable, do "dwarfdump --file-
636 tied=/path/to/myapp /path/to/myapp.dwp" . The tied file path
637 names the executable which has the .debug_addr section that may
638 be referred to from the main object. See Split Objects (aka
639 Debug Fission) in the DWARF5 standard. This cannot be used with
640 MacOS debug or GNU debuglink, such files do not have a Split
641 Dwarf object file.
642 -x line5=s2l
645 --file-line5=s2l
647 Normally used only to test libdwarf interfaces. There are 4
648 different interface function sets and to ensure they all work
649 this option lets us choose which to use. The options are 's2l'
650 (default, Allows standard and two-level line tables using the
651 latest interface functions), 'std' (Allows standard single level
652 line tables using the latest interface functions), 'orig'
653 (allows DWARF2,3,4 original line tables using an older interface
654 function set), 'orig2l' (allows original line tables and some
655 two-level line tables using an older interface set).
656 --print-producers
659 -P When checking this adds the list of compilation-unit names
660 seen for each producer-compiler to the printed checking results.
661 -q
663 --format-suppress-uri-msg
665 When a URI is found and translated while reading the command
666 line, be quiet about the URI translation. That is, don't print
667 the original and translated option strings.
668 -u cuname
671 --format-file=<file>
673 Turns on selective printing of DIEs (printing like -i). Only
674 the DIEs for a compilation unit that match the name provided are
675 printed. If the compilation unit is ./a/b/c.c the 'cuname' you
676 provide should be c.c as the characters through the final path-
677 separating / are ignored. If 'cuname' begins with a / then the
678 entire name string of a compilation unit must match 'cuname'.
679 The 'file' is read as a URI string.
680 -U
683 --format-suppress-uri
685 Turn off the URI interpretation of the command line strings
686 entirely. Must be be on the command line before any URI strings
687 encountered to be fully effective. Likely something no one
688 needs to do.
689 -h
692 --help Show this man page.
694
696 With Split Dwarf (DWARF5) the main body of the DWARF is in a separate
697 file, often having the name suffix .dwp or .dwo .
698 For example if /path/to/myapp.dwp is the split-dwarf object and
700 /path/to/myapp is the executable, do "dwarfdump --file-
701 tied=/path/to/myapp /path/to/myapp.dwp" . The tied file path names
702 the executable which has the .debug_addr section and other sections
703 that may be referred to from the .dwo/.dwp object.
704 See Split Object Files (sometimes called Debug Fission) in the DWARF5
706 standard, section 7.3.
707
710 dwarfdump
711 ./dwarfdump.conf
713 $(HOME)/.dwarfdump.conf
715 $(HOME)/dwarfdump.conf
717 <install-prefix>/lib/dwarfdump.conf
719
721 In some cases compilers use DW_FORM_data1 (for example) and in such
722 cases the signedness of the value must be taken from context. Rather
723 than attempt to determine the context, dwarfdump prints the value with
724 both signednesses whenever there is ambiguity about the correct inter‐
725 pretation. For example, "DW_AT_const_value 176(as signed =
726 -80)". For normal DWARF consumers that correctly and fully evaluate
727 all attributes there is no ambiguity of signedness: the ambiguity for
728 dwarfdump is due to dwarfdump evaluating DIEs in a simple order and not
729 keeping track of much context.
730
732 Support for DWARF5 is being completed but may not be complete.
733 DWARFDUMP()