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 As of June 2011 the printing options and the checking options are mutu‐
19 ally exclusive (if checking options are selected the section details
20 are not printed). When errors are encountered dwarfdump does attempt to
21 print sufficient context so that one can understand exactly where the
22 error is in the DWARF. This change makes checking really large object
23 files much easier.
24 The format is intended to be human readable. If a script is to parse
26 the output, the -d option is useful.
27 Not all sections actually exist in any given object file.
29 The format may change from release to release, so it is unwise to
31 depend too heavily on the format.
32 Frame information (.debug_frame and .eh_frame) is heavily dependent on
34 the ABI/ISA of the object file. By default we use a generic set of
35 register names handling up to 100 registers named r0-100. The '-R'
36 option uses a built-in generic register name set handling up to 1200
37 registers named r0-r1199. The '-x abi=<abi>' description below shows
38 how to name an abi and use that to guide the -f or -F processing.
39 Unless the cpu for the object file being dumped has many registers, do
40 not use -R or -x abi=generic as those can be needlessly slow dumping
41 frame sections. Instead, use the correct abi (if it exists in dwarf‐
42 dump.conf) or a generic such as -x abi=generic100 or -x abi=generic500.
43 To get MIPS/IRIX register names names and call the old version 2 libd‐
44 warf frame interface use the option '-x abi=mips'. Without '-R' or '-x
45 abi=<abi>' dwarfdump ignores the dwarfdump.conf file and uses compiled-
46 in generic set of register names. If no '-x name=<path>' is given,
47 dwarfdump looks for "./dwarfdump.conf", "$HOME/.dwarfdump.conf",
48 "<install-prefix>/lib/dwarfdump.conf" and takes the first it finds. If
49 one or more '-x name=<path>' is given the last of these is used and all
50 other such files are ignored.
51 If '-x nosanitizestrings' is given then unprintable characters are not
53 translated to '%xx' (two digit hex preceded by the '%' character)
54 (with this option bogus characters in strings could cause terminal win‐
55 dows to behave oddly).
56 Some -k (checking) options print so-called harmless errors. These are
58 compiler errors that do not cause any known problem and are only
59 detected inside libdwarf itself. These are difficult to properly
60 report in dwarfdump and any error strings may not appear close to the
61 time the error was encountered.
62 If zlib compression was used on the DWARF sections in the object file
64 being read the real section names such as .zdebug_info etc will be
65 reported by dwarfdump. When dwarfdump says something is at offset 55
66 of .zdebug_info (or the like) keep in mind that the offset applies to
67 the uncompressed section (in memory), not the .zdebug_ compressed sec‐
68 tion in objectfilename.
69
71 The <objectfilename> and the options taking name strings look for URIs
72 and translate the URI strings to characters by default (see -x, -c<com‐
73 piler name>, -S, -u). So any single % character is treated as if the
74 following two characters are hex digits representing the underlying
75 true character. Various characters are meaningful to shells (such as
76 bash or sh) and to getopt (such as the space character) If the URI
77 translation does anything it prints the before and after of the URI
78 translation on standard output, so inspection of the first lines of
79 output will show if URI did anything. The actual options themselves
80 are assumed to be non-URI. So in the option '-cS&T' the -c portion
81 must be non-URI, but the & character might cause input issues so
82 '-cS%26T' could be used instead. To actually input a single % charac‐
83 ter (in a name, for example), double it to %% on the command line.
84 Options -U (turning off URI interpretation) and -q (making finding URI
86 sequences silent) give finer control of URI interpretation. PP As an
87 example, to get a string'a b' make the string 'a%20b' (here the quote
88 (') is for exposition not part of the string, though quote is certainly
89 problematic in a name). Instead of escaping " quotes in the string,
90 type %25, as in
91 'a "b' should be typed 'a%20%25b' Any characters can be typed in URI
92 style, not just characters which are problematic to the shell or
93 getopt. We strongly suggest you not type URI-style characters where
94 such are not needed or use the % character itself in command line
95 strings unless you must.
96
98 -a Print each section as independently as possible. Sections that
99 can safely be printed independently (like .debug_abbrev) have
100 relevant info printed in the report (sometimes dependent on -v).
101 -b Print the .debug_abbrev section. Because the DWARF specifica‐
104 tions do not rule out garbage data areas in .debug_abbrev (if
105 they are not referenced from .debug_info) any garbage bytes can
106 result in this print failing.
107 -c Print locations lists.
110 -E Print ELF header information and index, address and size for all
113 sections.
114 -Eh Effectively does nothing (use another tool to print the Elf file
116 header).
117 -El Print index, address and size for the .debug_line section.
119 -Ei Print index, address and size for the .debug_info section.
121 -Ea Print index, address and size for the .debug_abbrev section.
123 -Ep Print index, address and size for the .debug_pubnames section.
125 -Er Print index, address and size for the .debug_aranges section.
127 -Ef Print index, address and size for the .debug_frame section.
129 -Eo Print index, address and size for the .debug_loc section.
131 -ER Print index, address and size for the .debug_ranges section.
133 -Es Print index, address and size for the .debug_string section.
135 -Et Print index, address and size for the .debug_pubtypes section.
137 -Ex Print index, address and size for the .text section.
139 -Ed Print index, address and size for the .text and .debug_* sec‐
141 tions.
142 -f Print the .debug_frame section.
145 -F Print the .eh_frame section.
147 -h Print the dwarfdump options list.
150 -i Print the .debug_info section.
153 -I Print the .gdb_index, .debug_cu_index, .debug_tu_index sections
156 if any exist.
157 -l Print the .debug_info section and the associated line section
160 data.
161 -ls Print the .debug_info section and the associated line section
163 data, but omits the <pc> address. Useful when a comparison is
164 required.
165 -m Print the .debug_macinfo section.
168 -N Print .debug_ranges section. Because the DWARF specifications do
171 not rule out garbage data areas in .debug_ranges (if they are
172 not referenced from .debug_info) any garbage bytes can result in
173 this print failing.
174 -p Print the .debug_pubnames section.
177 --print-str-offsets
180 Print the .debug_str_offsets section.
181 -r Print the .debug_aranges section.
184 -s Print .debug_string section.
186 -ta Print the IRIX only sections .debug_static_funcs and
189 .debug_static_vars.
190 -tf Print the IRIX only section .debug_static_funcs.
193 -tv Print the IRIX only section .debug_static_vars.
195 -w Print the IRIX-only .debug_weaknames section.
198 -y Print the .debug_pubtypes section (and .debug_typenames, an SGI
201 IRIX-only section).
202 Having dwarfdump print relocations may help establish whether dwarfdump
205 understands any relocations that might exist.
206 -o Print all relocation records as well as we can manage.
209 -oi Print .rel*debug_info relocations.
211 -ol Print .rel*debug_line relocation.
213 -op Print .rel*debug_pubnames relocation.
215 -oa Has no effect.
217 -or Print .rel*debug_aranges relocations.
219 -of Print .rel*debug_frame relocations.
221 -oo Print .rel*debug_loc relocations.
223 -oR Print .rel*debug_ranges relocations.
225 -g Normally used only for testing libdwarf, this tells dwarfdump to
228 use an older dwarf_loclist() interface function (a function that
229 cannot handle all DWARF4 or DWARF5 location lists). Before No‐
230 vember 2015 it implied -i, now you should use -i -g to also get
231 .debug_info printed.
232 -V Print a dwarfdump date/version string and stop.
234
237 -cg Restricts checking to compilers whose producer string starts
238 with 'GNU' and turns off -cs.
239 -cs Restricts checking to compilers whose producer string starts
242 with 'SN' and turns off -cg.
243 -cname Restricts checking to compilers whose producer string contains
245 'name' (not case sensitive). The 'name' is read as a URI
246 string.
247 -ka Turns on all checking options except -kxe (-kxe might be slow
250 enough one mignt not want to use it routinely.)
251 -kb Checks for certain abbreviations section errors when reading
254 DIEs.
255 -kc Checks for errors in constants in debug_info.
257 -kd Turns on full reporting of error totals per producer. (the
259 default shows less detail).
260 -kD Turns on reporting of duplicated attributes. Duplicated
262 attributes on a single DW_TAG are improper DWARF, but at least
263 one compiler emitted such.
264 -ke Turns on reading pubnames and checking for fde errors.
266 -kE Checks the integer encoding representation in debug_info, com‐
268 puting whether these integer values could fit in fewer bytes if
269 represented in LEB128.
270 -kf Turns on checking for FDE errors.
273 -kF Turns on checking for line table errors.
275 -kg Turns on checking for unused gaps in .debug_info (these gaps are
277 not an error, just a waste of space).
278 -kG Print only unique errors. Error lines are simpified (hex numbers
280 removed, for example) and when a given message string would oth‐
281 erwise appear again it is suppressed.
282 -ki Causes a summary of checking results per compiler (producer) to
284 be printed at the end.
285 -kl Turns on locations list checking.
287 -km Turns on checking of ranges.
289 -kM Turns on checking of aranges.
291 -kr Turns on DIE tag-attr combinations checking.
293 -kR Turns on reading DIEs and checking for forward declarations rom
295 DW_AT_specification attributes. (which are not an error but can
296 be a source of inefficiency for debuggers).
297 -ks Turns on extra reporting for some DIE errors checking detects.
299 -kS Turns on checking DIE references for circular references.
301 -kt Turns on tag-tag combinations checking.
303 -ku Print tag-tree and tag-attribute usage (basic format).
305 -kuf Print tag-tree and tag-attribute usage (full format). For stan‐
307 dard TAGs and ATtributes this presents an overview of how they
308 were used.
309 -kx Turns on check_frames.
311 -kxe Turns off basic check_frames and turns on extended frame check‐
313 ing.
314 -ky Turns on type_offset, decl_file checking,
316
319 -C Normally when checking for tag-tag or tag-attribute combinations
320 both the standard combinations and some common extensions are
321 allowed. With -C the extensions are taken out of the allowed
322 class of combinations.
323 -d When printing DIEs, put all the attributes for each DIE on the
326 same (long) line as the TAG. This makes searching for DIE infor‐
327 mation (as with grep) much simpler as the entire DIE is on one
328 line.
329 -D Turns off the display of section offsets and attribute values in
332 printed output. So the .debug_info output is just TAGs and
333 Attributes. For pubnames (and the like) it removes offsets from
334 the output. For locations lists it removes offsets from the
335 output, but that is useless since the attribute values don't
336 show so neither does the location data.
337 -e Turns on truncation of attribute and tag names. For example
340 DW_TAG_foo becomes foo. Not compatible with checking, only use‐
341 ful for printing DIEs.
342 -G When printing, add global offsets to the offsets printed.
345 -H number
348 When printing or checking .debug_info, this terminates the
349 search after 'number' compilation units. When printing frame
350 information this terminates the FDE reporting after 'number'
351 FDEs and the CIE reporting (which occurs if one adds -v) after
352 'number' CIEs. Example '-H 1'
353 -M When printing, this means one want to have the FORM show for
356 each attribute. If a -v is also added (or more than one) then
357 details of any form indirection are also shown.
358 -n When printing frames, this turns off the search for function
361 names. In a really large object the search can take more time
362 than one wants to wait, so this avoids the search.
363 -O file=<path>
365 The <path> will be used as the file name for output instead of
366 writing to stdout (stdout is the default).
367 -Q Suppresses section data printing (set automatically with a
369 checking option).
370 -R When printing frames for ABIs with lots of registers, this
373 allows up to 1200 registers to be named (like R999) without
374 choosing an ABI with, for example '-x abi=ppc'
375 -v Increases the detail shown when printing. In some sections,
378 using more -v options will increase the detail (one to three are
379 useful) or may change the report to show, for example, the
380 actual line-data-commands instead of the resultant line-table.
381
384 These -S options stand alone and basic print information about the com‐
385 pilation unit and DIE where the string(s) appear. At most one of each
386 of the following is effective (so for example one can only have one
387 'match', but one can have a 'match', an 'any', and a 'regex'). Any -S
388 causes the .debug_info section to be inspected. No checking options or
389 printing options should be supplied with -S.
390 If v is added to the -S option, the number of occurrences is printed.
392 (see below for an example).
393 -S match=string
396 When printing DIEs for each tag value or attribute name that
397 matches 'string' exactly print the compilation unit information
398 and its section offset. Any CU with no match is not printed.
399 The 'string' is read as a URI string.
400 -S any=string
402 When printing DIEs for each tag value or attribute name that
403 contains 'string' somewhere in the tag or attribute (case insen‐
404 sitive) print the compilation unit information and its section
405 offset. Any CU with no match is not printed. The 'string' is
406 read as a URI string.
407 -S regex=string
409 When printing DIEs for each tag value or attribute name where
410 the 'string' reqular expression matches print the compilation
411 unit information and its section offset. Any CU with no match
412 is not printed. The 'string' is read as a URI string.
413 The string cannot have spaces or other characters which are meaningful
416 to getopt(3) and the shell will strip off quotes and other characters.
417 So the string is assumed to be in URI style and is translated. In
418 other words, to match 'a b' make the -S string 'a%20b' Instead of
419 escaping " quotes in the string, type %25, as in
420 'a "b' should be typed 'a%20%25b' (the ' are for exposition here, not
421 part of the strings). Any characters can be typed in URI style, not
422 just characters which are problematic to the shell or getopt.
423 The -S any= and -S regex= options are only usable if the library func‐
425 tions required are found at configure time.
426 The -W option is a modifier to the -S option, and increases the amount
428 of output -W prints. An example v modifier to the -S option is shown
429 below. And we show the -W in context with a -S option.
430 -S vmatch=string1
433 Prints information about the DIEs that -S matches and prints the
434 count of occurrences
435 -S match=string1 -W
438 Prints the parent tree and the children tree for the DIEs that
439 -S matches.
440 -S match=string2 -Wp
443 Prints the parent tree for the DIEs that -S matches.
444 -S match=string3 -Wc
447 Prints the parent tree for the DIEs that -S matches.
448
451 -# number
452 This option controls internal debugging output, higher numbers
453 mean more debug actions. See the source code.
454 -x name=/p/a/t/h.conf
458 The file path given is the name of a file assumed to be a dwarf‐
459 dump.conf-like file. The file path is read as a URI string.
460 -x abi=ppc
463 Selects the abi (from a dwarfdump.conf file) to be used in
464 printing frame information (here using ppc as an example). The
465 abi is read as a URI string.
466 -x groupnumber=<n>
469 For an object file with both DWARF5 split dwarf (.debug_info.dwo
470 for example) and ordinary DWARF sections (.debug_info for exam‐
471 ple) in the single object file one must use -x groupnumber=2 to
472 print the dwo sections. Adding -x tied=<path> naming the same
473 object file ties in the non-dwo sections.
474 -x tied=/t/i/depath
477 Used when opening a main object that is a .dwo or .dwp file.
478 The tied file path names the executable which has the
479 .debug_addr section that may be referred to from the main
480 object. See Split Objects (aka Debug Fission).
481 -x line5=s2l
483 Normally used only to test libdwarf interfaces. There are 4
484 different interface function sets and to ensure they all work
485 this option lets us choose which to use. The options are 's2l'
486 (default, Allows standard and two-level line tables using the
487 latest interface functions), 'std' (Allows standard single level
488 line tables using the latest interface functions), 'orig'
489 (allows DWARF2,3,4 original line tables using an older interface
490 function set), 'orig2l' (allows original line tables and some
491 two-level line tables using an older interface set).
492 -P When checking this adds the list of compilation-unit names seen
495 for each producer-compiler to the printed checking results.
496 -q When a URI is found and translated while reading the command
498 line, be quiet about the URI translation. That is, don't print
499 the original and translated option strings.
500 -E Turns on printing object-internal header data for some systems
503 (for Unix/Linux does nothing).
504 -u cuname
507 Turns on selective printing of DIEs (printing like -i). Only
508 the DIEs for a compilation unit that match the name provided are
509 printed. If the compilation unit is ./a/b/c.c the 'cuname' you
510 provide should be c.c as the characters through the final path-
511 separating / are ignored. If 'cuname' begins with a / then the
512 entire name string of a compilation unit must match 'cuname'.
513 The 'cuname' is read as a URI string.
514 -U Turn off the URI interpretation of the command line strings
517 entirely. Must be be on the command line before any URI strings
518 encountered to be fully effective.
519 -z No longer supported.
522
526 dwarfdump
527 ./dwarfdump.conf
529 $(HOME)/.dwarfdump.conf
531 $(HOME)/dwarfdump.conf
533 <install-prefix>/lib/dwarfdump.conf
535
537 In some cases compilers use DW_FORM_data1 (for example) and in such
538 cases the signedness of the value must be taken from context. Rather
539 than attempt to determine the context, dwarfdump prints the value with
540 both signednesses whenever there is ambiguity about the correct inter‐
541 pretation. For example, "DW_AT_const_value 176(as signed =
542 -80)". For normal DWARF consumers that correctly and fully evaluate
543 all attributes there is no ambiguity of signedness: the ambiguity for
544 dwarfdump is due to dwarfdump evaluating DIEs in a simple order and not
545 keeping track of much context.
546
548 Support for DWARF3 is being completed but may not be complete.
549 DWARFDUMP()