256 lines · plain
1llvm-dwarfdump - dump and verify DWARF debug information2========================================================3 4.. program:: llvm-dwarfdump5 6SYNOPSIS7--------8 9:program:`llvm-dwarfdump` [*options*] [*filename ...*]10 11DESCRIPTION12-----------13 14:program:`llvm-dwarfdump` parses DWARF sections in object files,15archives, and `.dSYM` bundles and prints their contents in16human-readable form. Only the .debug_info section is printed unless one of17the section-specific options or :option:`--all` is specified.18 19If no input file is specified, `a.out` is used instead. If `-` is used as the20input file, :program:`llvm-dwarfdump` reads the input from its standard input21stream.22 23OPTIONS24-------25 26.. option:: -a, --all27 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. This34 option can be specified multiple times, once for each desired35 architecture. All CPU architectures will be printed by36 default.37 38.. option:: -c, --show-children39 40 Show a debug info entry's children when selectively printing with41 the `=<offset>` argument of :option:`--debug-info`, or options such42 as :option:`--find` or :option:`--name`.43 44.. option:: --color45 46 Use colors in output.47 48.. option:: --error-display=<value> 49 50 Set the level of detail and summary to display when verifying.51 Implies :option:`--verify`. The supported values are:52 53 `quiet` - Only display whether errors occurred.54 `summary` - Display only a summary of the errors found.55 `details` - Display each error in detail but no summary.56 `full` - Display each error as well as a summary. [default]57 58.. option:: -f <name>, --find=<name>59 60 Search for the exact text <name> in the accelerator tables61 and print the matching debug information entries.62 When there is no accelerator tables or the name of the DIE63 you are looking for is not found in the accelerator tables,64 try using the slower but more complete :option:`--name` option.65 66.. option:: -F, --show-form67 68 Show DWARF form types after the DWARF attribute types.69 70.. option:: -h, --help71 72 Show help and usage for this command.73 74.. option:: --help-list75 76 Show help and usage for this command without grouping the options77 into categories.78 79.. option:: -i, --ignore-case80 81 Ignore case distinctions when using :option:`--name`.82 83.. option:: -n <name>, --name=<name>84 85 Find and print all debug info entries whose name86 (`DW_AT_name`/`DW_AT_linkage_name` attribute) is <name>.87 88.. option:: --lookup=<address>89 90 Look up <address> in the debug information and print out the file,91 function, block, and line table details.92 93.. option:: -o <path>94 95 Redirect output to a file specified by <path>, where `-` is the96 standard output stream.97 98.. option:: -p, --show-parents99 100 Show a debug info entry's parents when selectively printing with101 the `=<offset>` argument of :option:`--debug-info`, or options such102 as :option:`--find` or :option:`--name`.103 104.. option:: --parent-recurse-depth=<N>105 106 When displaying debug info entry parents, only show them to a107 maximum depth of <N>.108 109.. option:: --quiet110 111 Use with :option:`--verify` to not emit to `STDOUT`.112 113.. option:: -r <N>, --recurse-depth=<N>114 115 When displaying debug info entries, only show children to a maximum116 depth of <N>.117 118.. option:: --show-section-sizes119 120 Show the sizes of all debug sections, expressed in bytes.121 122.. option:: --show-sources123 124 Print all source files mentioned in the debug information. Absolute125 paths are given whenever possible.126 127.. option:: --statistics128 129 Collect debug info quality metrics and print the results130 as machine-readable single-line JSON output. The output131 format is described in the section below (:ref:`stats-format`).132 133.. option:: --summarize-types134 135 Abbreviate the description of type unit entries.136 137.. option:: -t, --filter-child-tag138 139 Only dump children whose DWARF tag is one of the specified tags.140 Example usage:141 142 .. code-block:: c143 144 llvm-dwarfdump -t DW_TAG_structure_type -t DW_TAG_member -c145 146.. option:: -x, --regex147 148 Treat any <name> strings as regular expressions when searching149 with :option:`--name`. If :option:`--ignore-case` is also specified,150 the regular expression becomes case-insensitive.151 152.. option:: -u, --uuid153 154 Show the UUID for each architecture.155 156.. option:: --diff157 158 Dump the output in a format that is more friendly for comparing159 DWARF output from two different files.160 161.. option:: -v, --verbose162 163 Display verbose information when dumping. This can help to debug164 DWARF issues.165 166.. option:: --verify167 168 Verify the structure of the DWARF information by verifying the169 compile unit chains, DIE relationships graph, address170 ranges, and more.171 172.. option:: --verify-json=<path>173 174 Output JSON-formatted error summary to the file specified by175 <path>. Implies :option:`--verify`. The output format is described176 in the section below (:ref:`verify-json-format`).177 178.. option:: --version179 180 Display the version of the tool.181 182.. 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-objc183 184 Dump the specified DWARF section by name. Only the185 `.debug_info` section is shown by default. Some entries186 support adding an `=<offset>` as a way to provide an187 optional offset of the exact entry to dump within the188 respective section. When an offset is provided, only the189 entry at that offset will be dumped, else the entire190 section will be dumped.191 192 The :option:`--debug-macro` option prints both the .debug_macro and the .debug_macinfo sections.193 194 The :option:`--debug-frame` and :option:`--eh-frame` options are aliases, in cases where both sections are present one command outputs both.195 196.. option:: @<FILE>197 198 Read command-line options from `<FILE>`.199 200.. _stats-format:201 202FORMAT OF STATISTICS OUTPUT203---------------------------204 205The :option:`--statistics` option generates single-line JSON output206representing quality metrics of the processed debug info. These metrics are207useful to compare changes between two compilers, particularly for judging208the effect that a change to the compiler has on the debug info quality.209 210The output is formatted as key-value pairs. The first pair contains a version211number. The following naming scheme is used for the keys:212 213 - `variables` ==> local variables and parameters214 - `local vars` ==> local variables215 - `params` ==> formal parameters216 217For aggregated values, the following keys are used:218 219 - `sum_of_all_variables(...)` ==> the sum applied to all variables220 - `#bytes` ==> the number of bytes221 - `#variables - entry values ...` ==> the number of variables excluding222 the entry values etc.223 224.. _verify-json-format:225 226FORMAT OF VERIFY JSON OUTPUT227----------------------------228 229The format of the JSON output created by the :option:`--verify-json` is::230 231 { 232 "error-categories": { 233 "<first category description>": {"count": 1234},234 "<next category description>": {"count": 4321}235 },236 "error-count": 5555237 }238 239The following is generated if there are no errors reported::240 241 { 242 "error-categories": {},243 "error-count": 0244 }245 246EXIT STATUS247-----------248 249:program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped250successfully. Otherwise, it returns 1.251 252SEE ALSO253--------254 255:manpage:`dsymutil(1)`256