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:: --show-sources
 113
 114             Print all source files mentioned in the debug information. Absolute
 115             paths are given whenever possible.
 116
 117 .. option:: --statistics
 118
 119             Collect debug info quality metrics and print the results
 120             as machine-readable single-line JSON output. The output
 121             format is described in the section below (:ref:`stats-format`).
 122
 123 .. option:: --summarize-types
 124
 125             Abbreviate the description of type unit entries.
 126
 127 .. option:: -x, --regex
 128
 129             Treat any <name> strings as regular expressions when searching
 130             with :option:`--name`. If :option:`--ignore-case` is also specified,
 131             the regular expression becomes case-insensitive.
 132
 133 .. option:: -u, --uuid
 134
 135             Show the UUID for each architecture.
 136
 137 .. option:: --diff
 138
 139             Dump the output in a format that is more friendly for comparing
 140             DWARF output from two different files.
 141
 142 .. option:: -v, --verbose
 143
 144             Display verbose information when dumping. This can help to debug
 145             DWARF issues.
 146
 147 .. option:: --verify
 148
 149             Verify the structure of the DWARF information by verifying the
 150             compile unit chains, DIE relationships graph, address
 151             ranges, and more.
 152
 153 .. option:: --version
 154
 155             Display the version of the tool.
 156
 157 .. 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
 158
 159             Dump the specified DWARF section by name. Only the
 160             `.debug_info` section is shown by default. Some entries
 161             support adding an `=<offset>` as a way to provide an
 162             optional offset of the exact entry to dump within the
 163             respective section. When an offset is provided, only the
 164             entry at that offset will be dumped, else the entire
 165             section will be dumped.
 166
 167             The :option:`--debug-macro` option prints both the .debug_macro and the .debug_macinfo sections.
 168
 169             The :option:`--debug-frame` and :option:`--eh-frame` options are aliases, in cases where both sections are present one command outputs both.
 170
 171 .. option:: @<FILE>
 172
 173             Read command-line options from `<FILE>`.
 174
 175 .. _stats-format:
 176
 177 FORMAT OF STATISTICS OUTPUT
 178 ---------------------------
 179
 180 The :option:`--statistics` option generates single-line JSON output
 181 representing quality metrics of the processed debug info. These metrics are
 182 useful to compare changes between two compilers, particularly for judging
 183 the effect that a change to the compiler has on the debug info quality.
 184
 185 The output is formatted as key-value pairs. The first pair contains a version
 186 number. The following naming scheme is used for the keys:
 187
 188       - `variables` ==> local variables and parameters
 189       - `local vars` ==> local variables
 190       - `params` ==> formal parameters
 191
 192 For aggregated values, the following keys are used:
 193
 194       - `sum_of_all_variables(...)` ==> the sum applied to all variables
 195       - `#bytes` ==> the number of bytes
 196       - `#variables - entry values ...` ==> the number of variables excluding
 197         the entry values etc.
 198
 199 EXIT STATUS
 200 -----------
 201
 202 :program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
 203 successfully. Otherwise, it returns 1.
 204
 205 SEE ALSO
 206 --------
 207
 208 :manpage:`dsymutil(1)`