llvm/docs/CommandGuide/llvm-dwarfdump.rst

   1 llvm-dwarfdump - dump and verify DWARF debug information
   2 ========================================================
   3
   4 .. program:: llvm-dwarfdump
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-dwarfdump` [*options*] [*filename ...*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-dwarfdump` parses DWARF sections in object files,
  15 archives, and `.dSYM` bundles and prints their contents in
  16 human-readable form. Only the .debug_info section is printed unless one of
  17 the section-specific options or :option:`--all` is specified.
  18
  19 If no input file is specified, `a.out` is used instead. If `-` is used as the
  20 input file, :program:`llvm-dwarfdump` reads the input from its standard input
  21 stream.
  22
  23 OPTIONS
  24 -------
  25
  26 .. option:: -a, --all
  27
  28             Dump all supported DWARF sections.
  29
  30 .. option:: --arch=<arch>
  31
  32             Dump DWARF debug information for the specified CPU architecture.
  33             Architectures may be specified by name or by number.  This
  34             option can be specified multiple times, once for each desired
  35             architecture.  All CPU architectures will be printed by
  36             default.
  37
  38 .. option:: -c, --show-children
  39
  40             Show a debug info entry's children when selectively printing with
  41             the `=<offset>` argument of :option:`--debug-info`, or options such
  42             as :option:`--find` or :option:`--name`.
  43
  44 .. option:: --color
  45
  46             Use colors in output.
  47
  48 .. option:: -f <name>, --find=<name>
  49
  50             Search for the exact text <name> in the accelerator tables
  51             and print the matching debug information entries.
  52             When there is no accelerator tables or the name of the DIE
  53             you are looking for is not found in the accelerator tables,
  54             try using the slower but more complete :option:`--name` option.
  55
  56 .. option:: -F, --show-form
  57
  58             Show DWARF form types after the DWARF attribute types.
  59
  60 .. option:: -h, --help
  61
  62             Show help and usage for this command.
  63
  64 .. option:: --help-list
  65
  66             Show help and usage for this command without grouping the options
  67             into categories.
  68
  69 .. option:: -i, --ignore-case
  70
  71             Ignore case distinctions when using :option:`--name`.
  72
  73 .. option:: -n <name>, --name=<name>
  74
  75             Find and print all debug info entries whose name
  76             (`DW_AT_name` attribute) is <name>.
  77
  78 .. option:: --lookup=<address>
  79
  80             Look up <address> in the debug information and print out the file,
  81             function, block, and line table details.
  82
  83 .. option:: -o <path>
  84
  85             Redirect output to a file specified by <path>, where `-` is the
  86             standard output stream.
  87
  88 .. option:: -p, --show-parents
  89
  90             Show a debug info entry's parents when selectively printing with
  91             the `=<offset>` argument of :option:`--debug-info`, or options such
  92             as :option:`--find` or :option:`--name`.
  93
  94 .. option:: --parent-recurse-depth=<N>
  95
  96             When displaying debug info entry parents, only show them to a
  97             maximum depth of <N>.
  98
  99 .. option:: --quiet
 100
 101             Use with :option:`--verify` to not emit to `STDOUT`.
 102
 103 .. option:: -r <N>, --recurse-depth=<N>
 104
 105             When displaying debug info entries, only show children to a maximum
 106             depth of <N>.
 107
 108 .. option:: --show-section-sizes
 109
 110             Show the sizes of all debug sections, expressed in bytes.
 111
 112 .. option:: --statistics
 113
 114             Collect debug info quality metrics and print the results
 115             as machine-readable single-line JSON output. The output
 116             format is described in the section below (:ref:`stats-format`).
 117
 118 .. option:: --summarize-types
 119
 120             Abbreviate the description of type unit entries.
 121
 122 .. option:: -x, --regex
 123
 124             Treat any <name> strings as regular expressions when searching
 125             with :option:`--name`. If :option:`--ignore-case` is also specified,
 126             the regular expression becomes case-insensitive.
 127
 128 .. option:: -u, --uuid
 129
 130             Show the UUID for each architecture.
 131
 132 .. option:: --diff
 133
 134             Dump the output in a format that is more friendly for comparing
 135             DWARF output from two different files.
 136
 137 .. option:: -v, --verbose
 138
 139             Display verbose information when dumping. This can help to debug
 140             DWARF issues.
 141
 142 .. option:: --verify
 143
 144             Verify the structure of the DWARF information by verifying the
 145             compile unit chains, DIE relationships graph, address
 146             ranges, and more.
 147
 148 .. option:: --version
 149
 150             Display the version of the tool.
 151
 152 .. option:: --debug-abbrev, --debug-addr, --debug-aranges, --debug-cu-index, --debug-frame[=<offset>], --debug-gnu-pubnames, --debug-gnu-pubtypes, --debug-info [=<offset>], --debug-line [=<offset>], --debug-line-str, --debug-loc [=<offset>], --debug-loclists [=<offset>], --debug-macro, --debug-names, --debug-pubnames, --debug-pubtypes, --debug-ranges, --debug-rnglists, --debug-str, --debug-str-offsets, --debug-tu-index, --debug-types [=<offset>], --eh-frame [=<offset>], --gdb-index, --apple-names, --apple-types, --apple-namespaces, --apple-objc
 153
 154             Dump the specified DWARF section by name. Only the
 155             `.debug_info` section is shown by default. Some entries
 156             support adding an `=<offset>` as a way to provide an
 157             optional offset of the exact entry to dump within the
 158             respective section. When an offset is provided, only the
 159             entry at that offset will be dumped, else the entire
 160             section will be dumped.
 161
 162 .. option:: @<FILE>
 163
 164             Read command-line options from `<FILE>`.
 165
 166 .. _stats-format:
 167
 168 FORMAT OF STATISTICS OUTPUT
 169 ---------------------------
 170
 171 The ::option:`--statistics` option generates single-line JSON output
 172 representing quality metrics of the processed debug info. These metrics are
 173 useful to compare changes between two compilers, particularly for judging
 174 the effect that a change to the compiler has on the debug info quality.
 175
 176 The output is formatted as key-value pairs. The first pair contains a version
 177 number. The following naming scheme is used for the keys:
 178
 179       - `variables` ==> local variables and parameters
 180       - `local vars` ==> local variables
 181       - `params` ==> formal parameters
 182
 183 For aggregated values, the following keys are used:
 184
 185       - `sum_of_all_variables(...)` ==> the sum applied to all variables
 186       - `#bytes` ==> the number of bytes
 187       - `#variables - entry values ...` ==> the number of variables excluding
 188         the entry values etc.
 189
 190 EXIT STATUS
 191 -----------
 192
 193 :program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
 194 successfully. Otherwise, it returns 1.
 195
 196 SEE ALSO
 197 --------
 198
 199 :manpage:`dsymutil(1)`