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 All options are available in the traditional (single-letter) form and
20 in a long-options form with meaningful names.
21 With no options dwarfdump prints a basic set of DWARF section informa‐
24 tion. If any option is given on the command line the basic set is
25 ignored and one must tell dwarfdump what to print or check (for example
26 by adding the -a option).
27 As of June 2011 the printing options and the checking options are mutu‐
30 ally exclusive (if checking options are selected the section details
31 are not printed). When errors are encountered dwarfdump does attempt to
32 print sufficient context so that one can understand exactly where the
33 error is in the DWARF. This change makes checking really large object
34 files much easier.
35 The format is intended to be human readable. If a script is to parse
37 the output, the --format-dense (-d) option is useful.
38 Not all sections actually exist in any given object file.
40 The format may change from release to release, so it is unwise to
42 depend too heavily on the format.
43 Frame information (.debug_frame and .eh_frame) is heavily dependent on
45 the ABI/ISA of the object file. By default we use a generic set of
46 register names handling up to 100 registers named r0-r99.
47 The --format-registers (-R) option uses a built-in generic register
49 name set handling up to 1200 registers named r0-r1199.
50 The -file-abi=<abi> (-x abi=<abi>) description below shows how to name
52 an abi and use that to guide the --print-frame (-f) or --print-eh-
53 frame (-F) processing.
54 Unless one of --print-frame (-f) or --print-eh-frame (-F) or --print-
56 all (-a) is used any abi reference is ignored because no frame data
57 will be printed.
58 Unless the cpu for the object file being dumped has many registers, do
61 not use --format-registers or -file-abi=<abi> as those can be need‐
62 lessly slow dumping frame sections. Instead, use the correct abi (if it
63 exists in dwarfdump.conf) or a generic such as --file-
64 abi=abi=generic100 or --file-abi=abi=generic500
65 .
66 The most useful abi choices are likely mips or x86 or x86_64 or ppc or
68 arm
69 . Without --format-registers (-R) or -file-abi=<abi> (-x abi=<abi>)
70 dwarfdump ignores the dwarfdump.conf file and uses compiled-in generic
71 set of register names. If no --file-name=<path> (-x name=<path>) is
72 given, dwarfdump looks for "./dwarfdump.conf", "$HOME/.dwarfdump.conf",
73 "<install-prefix>/lib/dwarfdump.conf" and takes the first it finds. If
74 one or more --file-name=<path> (-x name=<path>) is given the last of
75 these is used and all other such files are ignored.
76 Some checking ( -k) options (See "Check DWARF Integrity" in the help
78 output) print so-called harmless errors. These are compiler errors
79 that do not cause any known problem and are only detected inside libd‐
80 warf itself. These are difficult to properly report in dwarfdump and
81 any error strings may not appear close to the time the error was
82 encountered.
83 If zlib compression was used on the DWARF sections in the object file
85 being read the real section names such as .zdebug_info etc will be
86 reported by dwarfdump. When dwarfdump says something is at offset 55
87 of .zdebug_info (or the like) keep in mind that the offset applies to
88 the uncompressed section (in memory), not the .zdebug_ compressed sec‐
89 tion in objectfilename.
90
92 The <objectfilename> and all the options taking name strings look for
93 URIs and translate the URI strings to characters by default. So any
94 single % character is treated as if the following two characters are
95 hex digits representing the underlying true character. Various charac‐
96 ters are meaningful to shells (such as bash or sh) and to getopt (such
97 as the space character) If the URI translation does anything it prints
98 the before and after of the URI translation on standard output, so
99 inspection of the first lines of output will show if URI did anything.
100 The actual options themselves are assumed to be non-URI. So in the
101 option --format-producer=S&T (-cS&T) the & character might cause input
102 issues so --format-producer=S%26T should be used instead. To actually
103 input a single % character (in a name, for example), double it to %% on
104 the command line (or simply use %25).
105 Options --format-suppress-uri (-U) (turning off URI interpretation) and
107 --format-suppress-uri-msg (-q) (making finding URI sequences silent)
108 give finer control of URI interpretation. PP As an example, to get a
109 string'a b' make the string 'a%20b' (here the quote (') is for exposi‐
110 tion not part of the string, though quote is certainly problematic in a
111 name). Instead of escaping " quotes in the string, type %25, as in
112 'a "b' should be typed 'a%20%25b' Any characters can be typed in URI
113 style, not just characters which are problematic to the shell or
114 getopt. We strongly suggest you not type URI-style characters where
115 such are not needed or use the % character itself in command line
116 strings unless you must.
117
119 --print-all (-a)
120 Print each section as independently as possible. Sections that
121 can safely be printed independently (like .debug_abbrev) have
122 relevant info printed in the report (sometimes dependent on -v).
123 --print-abbrev (-b)
126 Print the .debug_abbrev section. Because the DWARF specifica‐
127 tions do not rule out garbage data areas in .debug_abbrev (if
128 they are not referenced from .debug_info) any garbage bytes can
129 result in this print failing.
130 --print-loc (-c)
133 Print locations lists.
134 --elf (-E)
137 prints, for Elf objects, object file details. See the "Print
138 ELF sections header" section of the help file for additional
139 choices on elf printing. If libdwarf or dwarfdump is built
140 without libelf this option is unavailable.
141 --print-frame (-f)
144 Print the .debug_frame section.
145 --print-eh-frame (-F)
147 Print the GNU .eh_frame section.
148 --print-info (-i)
151 Print the .debug_info section.
152 --print-fission (-I)
155 Print any .gdb_index, .debug_cu_index, and .debug_tu_index sec‐
156 tions that exist in the object.
157 --print-gnu-debuglinkIfthe.gnu_debuglinksection
160 is present its content is printed. If the .note.gnu.build-id
161 section is present its content is printed. If a DWARF contain‐
162 ing file named by the content of the .gnu_debuglink section
163 exists the name will be printed.
164 --print-lines (-l)
167 Print the .debug_info section and the associated line section
168 data.
169 --print-lines-short (-ls)
171 Print the .debug_info section and the associated line section
172 data, but omit the <pc> address. Useful when a comparison of
173 line sections from objects with slight differences is required.
174 --print-macinfo (-m)
177 Print the .debug_macinfo (DWARF 2,3,4) and .debug_macro (DWARF5)
178 sections.
179 --print-ranges (-N)
182 Print .debug_ranges section. Because the DWARF specifications
183 do not rule out garbage data areas in .debug_ranges (if they are
184 not referenced from .debug_info) any garbage bytes can result in
185 this print failing.
186 --print-pubnames (-p)
189 Print the .debug_pubnames section.
190 --print-str-offsets
193 Print the .debug_str_offsets section.
194 --print-aranges (-r)
197 Print the .debug_aranges section.
198 --print-strings (-s)
200 Print .debug_string section.
201 --print-static (-ta)
204 Print the IRIX only sections .debug_static_funcs and
205 .debug_static_vars.
206 --print-type (-y)
209 Print the .debug_pubtypes section (and .debug_typenames, an SGI
210 IRIX-only section).
211 Having dwarfdump print relocations may help establish whether dwarfdump
214 understands any relocations that might exist. Other tools may be more
215 useful than dwarfdump for printing object-file details. See "Print
216 Relocations Info" in the help output for additional relocation printing
217 choices.
218 --reloc (-o)
221 Print all relocation records as well as we can manage. If libd‐
222 warf or dwarfdump were built without libelf this option is
223 unavailable.
224 --version (-V)
227 Print a dwarfdump date/version string and stop.
228
231 --check-all (-ka)
232 Turns on all checking options except --check-frame-
233 extended (-kxe) (which might be slow enough one might not want
234 to use it routinely.)
235 --check-abbrev (-kb)
238 Checks for certain abbreviations section errors when reading
239 DIEs.
240 --check-constants (-kc)
243 Checks for errors in constants in debug_info.
244 -check-show (-kd)
246 Turns on full reporting of error totals per producer. (the
247 default shows less detail).
248 --check-silent-ks
250 Turns off some verbose checking detection.
251 --check-attr-dup (-kD)
254 Turns on reporting of duplicated attributes. Duplicated
255 attributes on a single DW_TAG are improper DWARF, but at least
256 one compiler emitted such.
257 --check-pubnames (-ke)
259 Turns on reading pubnames and checking for fde errors.
260 --check-attr-encodings (-kE)
262 Checks the integer encoding representation in debug_info, com‐
263 puting whether these integer values could fit in fewer bytes if
264 represented in LEB128.
265 --check-frame-info (-kf)
268 Turns on checking for FDE errors (.debug_frame and .eh_frame).
269 --check-files-lines (-kF)
271 Turns on checking for line table errors.
272 --check-gaps (-kg)
274 Turns on checking for unused gaps in .debug_info (these gaps are
275 not an error, just a waste of space).
276 --check-unique (-kG)
278 Print only unique errors. Error lines are simpified (hex numbers
279 removed, for example) and when a given message string would oth‐
280 erwise appear again it is suppressed.
281 --check-summary (-ki)
283 Causes a summary of checking results per compiler (producer) to
284 be printed at the end.
285 --check-loc (-kl)
288 Turns on locations list checking.
289 --check-ranges (-km)
291 Turns on checking of ranges.
292 --check-aranges (-kM)
294 Turns on checking of aranges.
295 --check-tag-attr (-kr)
297 Turns on DIE tag-attr combinations checking, looking for sur‐
298 prising attributes for DIE tags.
299 --check-forward-refs (-kR)
301 Turns on reading DIEs and checking for forward declarations from
302 DW_AT_specification attributes. (which are not an error but can
303 be a source of inefficiency for debuggers).
304 --check-self-refs (-kS)
306 Turns on checking DIE references for circular references.
307 --check-tag-tag (-kt)
309 Turns on tag-tag combinations checking, looking for surprising
310 parent-child DIE relationships.
311 --check-usage (-ku)
313 Print tag-tree and tag-attribute usage (basic format).
314 --check-usage-extended (-kuf)
316 Print tag-tree and tag-attribute usage (full format). For stan‐
317 dard TAGs and ATtributes this presents an overview of how they
318 were used.
319 --check-frame-basic (-kx)
322 Turns on basic frames checking for .debug_frame and .eh_frame).
323 --check-frame-extended (-kxe)
325 Turns off basic check_frames and turns on extended frame check‐
326 ing for .debug_frame and .eh_frame. This option can be slow.
327 --check-type (-ky)
330 Turns on type_offset checking (ensuring local attribute offsets
331 refer to what they should) and that DW_AT_decl_file and some
332 other offsets refer to appropriate locations.
333
336 --format-extensions (-C)
337 Normally when checking for tag-tag or tag-attribute combinations
338 both the standard combinations and some common extensions are
339 allowed. With -C the extensions are taken out of the allowed
340 class of combinations.
341 --format-dense (-d)
344 When printing DIEs, put all the attributes for each DIE on the
345 same (long) line as the TAG. This makes searching for DIE infor‐
346 mation (as with grep) much simpler as the entire DIE is on one
347 line.
348 --format-supress-offsets (-D)
351 Turns off the display of section offsets and attribute values in
352 printed output. So the .debug_info output is just TAGs and
353 Attributes. For pubnames (and the like) it removes offsets from
354 the output. For locations lists it removes offsets from the
355 output, but that is useless since the attribute values don't
356 show so neither does the location data.
357 --format-ellipsis (-e)
360 Turns on truncation of attribute and tag names. For example
361 DW_TAG_foo becomes foo. Not compatible with checking, only use‐
362 ful for printing DIEs.
363 --format-global-offsets (-G)
366 When printing, add global offsets to the offsets printed.
367 --format-limit=<num> (-H number)
370 When printing or checking .debug_info, this terminates the
371 search after 'number' compilation units. When printing frame
372 information this terminates the FDE reporting after 'number'
373 FDEs and the CIE reporting (which occurs if one adds -v) after
374 'number' CIEs. Example '--format-limit=1'
375 --format-attr-name (-M)
378 When printing, show the FORM for each attribute. If a -v is
379 added (or more than one) then details of any form indirection
380 are also shown.
381 --format-suppress-lookup (-n)
384 When printing frames, this turns off the search for function
385 names. In a really large object the search can take more time
386 than one wants to wait, so this avoids the search.
387 --file-output=<path> (-Ofile=<path>)
390 The <path> will be used as the file name for output instead of
391 writing to stdout (stdout is the default).
392 -format-suppress-data (-Q)
395 Suppresses section data printing (set automatically with a
396 checking option).
397 --format-registers (-R)
400 When printing frames for ABIs with lots of registers, this
401 allows up to 1200 registers to be named (like R999) without
402 choosing an ABI with, for example '-x abi=ppc'
403 --version (-v)
406 Increases the detail shown when printing. In some sections,
407 using more -v options will increase the detail (one to three are
408 useful) or may change the report to show, for example, the
409 actual line-data-commands instead of the resultant line-table.
410
413 These --search (-S) options stand alone and basic print information
414 about the compilation unit and DIE where the string(s) appear. At most
415 one of each of the following is effective (so for example one can only
416 have one 'match', but one can have a 'match', an 'any', and a 'regex').
417 Any --search (-S) causes the .debug_info section to be inspected. No
418 checking options or printing options should be supplied with
419 --search(-S) options. The strings should use URI-style to avoid any
420 conflicts with the command-line parser applicable (bash, sh, ...) or
421 getopt().
422 These are particularly useful when the amount of DWARF information is
424 really large.
425 If v is added to the -S option, the number of occurrences is printed.
427 (see below for an example).
428 --search-match=<string> (-Smatch=string)
431 --search-match-count=<string> (-Svmatch=string)
433 When printing DIEs for each tag value or attribute name that
434 matches 'string' exactly print the compilation unit information
435 and its section offset. Any CU with no match is not printed.
436 The 'string' is read as a URI string. The count (Sv) form
437 reports the count of occurrences.
438 --search-any=<string> (-Sany=string)
441 --search-any-count=<string> (-Svany=string)
443 When printing DIEs for each tag value or attribute name that
444 contains 'string' somewhere in the tag or attribute (case insen‐
445 sitive) print the compilation unit information and its section
446 offset. Any CU with no match is not printed. The 'string' is
447 read as a URI string. The count (Sv) form reports the count of
448 occurrences.
449 --search-regex=string (-Sregex=string)
452 --search-regex-count=string (-Svregex=string)
454 When printing DIEs for each tag value or attribute name where
455 the 'string' reqular expression matches print the compilation
456 unit information and its section offset. Any CU with no match
457 is not printed. The 'string' is read as a URI string. The
458 count (Sv) form reports the count of occurrences.
459 The string cannot have spaces or other characters which are meaningful
462 to getopt(3) and the shell will strip off quotes and other characters.
463 So the string is assumed to be in URI style and is translated. In
464 other words, to match 'a b' make the -S string 'a%20b' Instead of
465 escaping " quotes in the string, type %25, as in
466 'a "b' should be typed 'a%20%25b' (the ' are for exposition here, not
467 part of the strings). Any characters can be typed in URI style, not
468 just characters which are problematic to the shell or getopt.
469 The --search-any (-Sany) and --regex-any (-Sregex) options are only
471 usable if regular-expression library functions required are found at
472 configure time.
473 The --search-print (-W) option is a modifier to the -S option, and
475 increases the amount of output -S prints. An example v modifier to the
476 -S option is shown below. And we show the -W in context with a -S
477 option.
478 --search-match-count=string1 (-S vmatch=string1)
481 Prints information about the DIEs that -S matches and prints the
482 count of occurrences.
483 -S match=string1 -W
486 --search-match=string1 --search-print-tree
489 Prints the parent tree and the children tree for the DIEs that
490 -S matches.
491 -S match=string2 -Wp
494 --search-match=string2 --search-print-parent
497 Prints the parent tree for the DIEs that -S matches.
498 -S match=string3 -Wc
501 --search-match=string3 --search-print-children
503 Prints the children tree for the DIEs that -S matches.
504 --format-gcc (-cg)
507 Restricts printing/checking to compilers whose producer string
508 starts with 'GNU' and turns off -cs.
509 --format-snc (-cs)
512 Restricts printing/checking to compilers whose producer string
513 starts with 'SN' and turns off -cg.
514 --format-producer=<name> (-c<name>)
517 Restricts printing/checking to compilers whose producer string
518 contains 'name' (not case sensitive). The 'name' is read as a
519 URI string.
520
524 -x name=<path>
525 --file-name=/p/a/t/h.conf (-xname=/p/a/t/h.conf)
527 The file path given is the name of a file assumed to be a dwarf‐
528 dump.conf-like file. The file path is read as a URI string.
529 -x abi=ppc
532 --file-abi=ppc
534 Selects the abi (from a dwarfdump.conf file) to be used in
535 printing frame information (here using ppc as an example). The
536 abi is read as a URI string.
537 --format-group=<n> (-x groupnumber=<n>)
540 For an object file with both DWARF5 split dwarf (.debug_info.dwo
541 for example) and ordinary DWARF sections (.debug_info for exam‐
542 ple) in the single object file one must use --format-group=2 to
543 print the dwo sections. Adding --file-tied=<path> naming the
544 same object file ties in the non-dwo sections.
545 -x tied=/t/i/depath
548 --file-tied=/t/i/depath
550 Used when opening a main object that is a .dwo or .dwp file.
551 The tied file path names the executable which has the
552 .debug_addr section that may be referred to from the main
553 object. See Split Objects (aka Debug Fission).
554 -x line5=s2l
556 --file-line5=s2l
558 Normally used only to test libdwarf interfaces. There are 4
559 different interface function sets and to ensure they all work
560 this option lets us choose which to use. The options are 's2l'
561 (default, Allows standard and two-level line tables using the
562 latest interface functions), 'std' (Allows standard single level
563 line tables using the latest interface functions), 'orig'
564 (allows DWARF2,3,4 original line tables using an older interface
565 function set), 'orig2l' (allows original line tables and some
566 two-level line tables using an older interface set).
567 --print-producers
570 -P When checking this adds the list of compilation-unit names
571 seen for each producer-compiler to the printed checking results.
572 -q
574 --format-suppress-uri-msg
576 When a URI is found and translated while reading the command
577 line, be quiet about the URI translation. That is, don't print
578 the original and translated option strings.
579 -u cuname
582 --format-file=<file>
584 Turns on selective printing of DIEs (printing like -i). Only
585 the DIEs for a compilation unit that match the name provided are
586 printed. If the compilation unit is ./a/b/c.c the 'cuname' you
587 provide should be c.c as the characters through the final path-
588 separating / are ignored. If 'cuname' begins with a / then the
589 entire name string of a compilation unit must match 'cuname'.
590 The 'file' is read as a URI string.
591 -U
594 --format-suppress-uri
596 Turn off the URI interpretation of the command line strings
597 entirely. Must be be on the command line before any URI strings
598 encountered to be fully effective. Likely something no one
599 needs to do.
600 -h
603 --help Show this man page.
605
608 dwarfdump
609 ./dwarfdump.conf
611 $(HOME)/.dwarfdump.conf
613 $(HOME)/dwarfdump.conf
615 <install-prefix>/lib/dwarfdump.conf
617
619 In some cases compilers use DW_FORM_data1 (for example) and in such
620 cases the signedness of the value must be taken from context. Rather
621 than attempt to determine the context, dwarfdump prints the value with
622 both signednesses whenever there is ambiguity about the correct inter‐
623 pretation. For example, "DW_AT_const_value 176(as signed =
624 -80)". For normal DWARF consumers that correctly and fully evaluate
625 all attributes there is no ambiguity of signedness: the ambiguity for
626 dwarfdump is due to dwarfdump evaluating DIEs in a simple order and not
627 keeping track of much context.
628
630 Support for DWARF5 is being completed but may not be complete.
631 DWARFDUMP()