| llvm-dwarfdump - dump and verify DWARF debug information | |
| ======================================================== | |
| .. program:: llvm-dwarfdump | |
| SYNOPSIS | |
| -------- | |
| :program:`llvm-dwarfdump` [*options*] [*filename ...*] | |
| DESCRIPTION | |
| ----------- | |
| :program:`llvm-dwarfdump` parses DWARF sections in object files, | |
| archives, and `.dSYM` bundles and prints their contents in | |
| human-readable form. Only the .debug_info section is printed unless one of | |
| the section-specific options or :option:`--all` is specified. | |
| If no input file is specified, `a.out` is used instead. If `-` is used as the | |
| input file, :program:`llvm-dwarfdump` reads the input from its standard input | |
| stream. | |
| OPTIONS | |
| ------- | |
| .. option:: -a, --all | |
| Dump all supported DWARF sections. | |
| .. option:: --arch=<arch> | |
| Dump DWARF debug information for the specified CPU architecture. | |
| Architectures may be specified by name or by number. This | |
| option can be specified multiple times, once for each desired | |
| architecture. All CPU architectures will be printed by | |
| default. | |
| .. option:: -c, --show-children | |
| Show a debug info entry's children when selectively printing with | |
| the `=<offset>` argument of :option:`--debug-info`, or options such | |
| as :option:`--find` or :option:`--name`. | |
| .. option:: --color | |
| Use colors in output. | |
| .. option:: --error-display=<value> | |
| Set the level of detail and summary to display when verifying. | |
| Implies :option:`--verify`. The supported values are: | |
| `quiet` - Only display whether errors occurred. | |
| `summary` - Display only a summary of the errors found. | |
| `details` - Display each error in detail but no summary. | |
| `full` - Display each error as well as a summary. [default] | |
| .. option:: -f <name>, --find=<name> | |
| Search for the exact text <name> in the accelerator tables | |
| and print the matching debug information entries. | |
| When there is no accelerator tables or the name of the DIE | |
| you are looking for is not found in the accelerator tables, | |
| try using the slower but more complete :option:`--name` option. | |
| .. option:: -F, --show-form | |
| Show DWARF form types after the DWARF attribute types. | |
| .. option:: -h, --help | |
| Show help and usage for this command. | |
| .. option:: --help-list | |
| Show help and usage for this command without grouping the options | |
| into categories. | |
| .. option:: -i, --ignore-case | |
| Ignore case distinctions when using :option:`--name`. | |
| .. option:: -n <name>, --name=<name> | |
| Find and print all debug info entries whose name | |
| (`DW_AT_name`/`DW_AT_linkage_name` attribute) is <name>. | |
| .. option:: --lookup=<address> | |
| Look up <address> in the debug information and print out the file, | |
| function, block, and line table details. | |
| .. option:: -o <path> | |
| Redirect output to a file specified by <path>, where `-` is the | |
| standard output stream. | |
| .. option:: -p, --show-parents | |
| Show a debug info entry's parents when selectively printing with | |
| the `=<offset>` argument of :option:`--debug-info`, or options such | |
| as :option:`--find` or :option:`--name`. | |
| .. option:: --parent-recurse-depth=<N> | |
| When displaying debug info entry parents, only show them to a | |
| maximum depth of <N>. | |
| .. option:: --quiet | |
| Use with :option:`--verify` to not emit to `STDOUT`. | |
| .. option:: -r <N>, --recurse-depth=<N> | |
| When displaying debug info entries, only show children to a maximum | |
| depth of <N>. | |
| .. option:: --show-section-sizes | |
| Show the sizes of all debug sections, expressed in bytes. | |
| .. option:: --show-sources | |
| Print all source files mentioned in the debug information. Absolute | |
| paths are given whenever possible. | |
| .. option:: --statistics | |
| Collect debug info quality metrics and print the results | |
| as machine-readable single-line JSON output. The output | |
| format is described in the section below (:ref:`stats-format`). | |
| .. option:: --summarize-types | |
| Abbreviate the description of type unit entries. | |
| .. option:: -t, --filter-child-tag | |
| Only dump children whose DWARF tag is one of the specified tags. | |
| Example usage: | |
| .. code-block:: c | |
| llvm-dwarfdump -t DW_TAG_structure_type -t DW_TAG_member -c | |
| .. option:: -x, --regex | |
| Treat any <name> strings as regular expressions when searching | |
| with :option:`--name`. If :option:`--ignore-case` is also specified, | |
| the regular expression becomes case-insensitive. | |
| .. option:: -u, --uuid | |
| Show the UUID for each architecture. | |
| .. option:: --diff | |
| Dump the output in a format that is more friendly for comparing | |
| DWARF output from two different files. | |
| .. option:: -v, --verbose | |
| Display verbose information when dumping. This can help to debug | |
| DWARF issues. | |
| .. option:: --verify | |
| Verify the structure of the DWARF information by verifying the | |
| compile unit chains, DIE relationships graph, address | |
| ranges, and more. | |
| .. option:: --verify-json=<path> | |
| Output JSON-formatted error summary to the file specified by | |
| <path>. Implies :option:`--verify`. The output format is described | |
| in the section below (:ref:`verify-json-format`). | |
| .. option:: --version | |
| Display the version of the tool. | |
| .. 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 | |
| Dump the specified DWARF section by name. Only the | |
| `.debug_info` section is shown by default. Some entries | |
| support adding an `=<offset>` as a way to provide an | |
| optional offset of the exact entry to dump within the | |
| respective section. When an offset is provided, only the | |
| entry at that offset will be dumped, else the entire | |
| section will be dumped. | |
| The :option:`--debug-macro` option prints both the .debug_macro and the .debug_macinfo sections. | |
| The :option:`--debug-frame` and :option:`--eh-frame` options are aliases, in cases where both sections are present one command outputs both. | |
| .. option:: --show-variable-coverage | |
| Show per-variable coverage metrics. The output format is described | |
| in the section below (:ref:`variable-coverage-format`). | |
| .. option:: --coverage-baseline | |
| File to use as the baseline for variable coverage statistics | |
| (implies :option:`--show-variable-coverage`) | |
| .. option:: --combine-inline-variable-instances | |
| Use with :option:`--show-variable-coverage` to average variable | |
| coverage across inlined subroutine instances instead of printing | |
| them separately. | |
| .. option:: @<FILE> | |
| Read command-line options from `<FILE>`. | |
| .. _stats-format: | |
| FORMAT OF STATISTICS OUTPUT | |
| --------------------------- | |
| The :option:`--statistics` option generates single-line JSON output | |
| representing quality metrics of the processed debug info. These metrics are | |
| useful to compare changes between two compilers, particularly for judging | |
| the effect that a change to the compiler has on the debug info quality. | |
| The output is formatted as key-value pairs. The first pair contains a version | |
| number. The following naming scheme is used for the keys: | |
| - `variables` ==> local variables and parameters | |
| - `local vars` ==> local variables | |
| - `params` ==> formal parameters | |
| For aggregated values, the following keys are used: | |
| - `sum_of_all_variables(...)` ==> the sum applied to all variables | |
| - `#bytes` ==> the number of bytes | |
| - `#variables - entry values ...` ==> the number of variables excluding | |
| the entry values etc. | |
| .. _verify-json-format: | |
| FORMAT OF VERIFY JSON OUTPUT | |
| ---------------------------- | |
| The format of the JSON output created by the :option:`--verify-json` is:: | |
| { | |
| "error-categories": { | |
| "<first category description>": {"count": 1234}, | |
| "<next category description>": {"count": 4321} | |
| }, | |
| "error-count": 5555 | |
| } | |
| The following is generated if there are no errors reported:: | |
| { | |
| "error-categories": {}, | |
| "error-count": 0 | |
| } | |
| .. _variable-coverage-format: | |
| FORMAT OF VARIABLE COVERAGE OUTPUT | |
| ---------------------------------- | |
| The :option:`--show-variable-coverage` option differs from | |
| :option:`--statistics` by printing per-variable debug info coverage metrics | |
| based on the number of source lines covered instead of the number of | |
| instruction bytes. Compared to counting instruction bytes, this is more stable | |
| across compilations and better reflects the debugging experience. The output is | |
| a tab-separated table containing the following columns: | |
| - `Function` ==> Name of the function the variable was found in | |
| - `InstanceCount` (when :option:`--combine-inline-variable-instances` is | |
| specified) ==> Number of instances of the function; this is 1 for | |
| functions that have not been inlined, and n+1 for functions that have | |
| been inlined n times | |
| - `InlChain` (when :option:`--combine-inline-variable-instances` is not | |
| specified) ==> Chain of call sites (file and line number) that the | |
| function has been inlined into; this will be empty if the function has | |
| not been inlined | |
| - `Variable` ==> Name of the variable | |
| - `Decl` ==> Source location (file and line number) of the variable's | |
| declaration | |
| - `LinesCovered` ==> Number of source lines covered by the variable's | |
| debug information in the input file | |
| - `Baseline` (empty if :option:`--coverage-baseline` is not specified) | |
| ==> Number of source lines covered by the variable's debug information | |
| in the baseline | |
| - `CoveredRatio` (empty if :option:`--coverage-baseline` is not | |
| specified) ==> Ratio of the coverage compared to the baseline | |
| (calculated as `LinesCovered/Baseline`) | |
| - `LinesPresent` (empty if :option:`--coverage-baseline` is not | |
| specified) ==> Number of source lines covered in the variable's | |
| baseline debug information that are also present in the input file's | |
| line table | |
| - `LinesPresentRatio` (empty if :option:`--coverage-baseline` is not | |
| specified) ==> Ratio of the line table coverage compared to the | |
| baseline (calculated as `LinesPresent/Baseline`) | |
| EXIT STATUS | |
| ----------- | |
| :program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped | |
| successfully. Otherwise, it returns 1. | |
| SEE ALSO | |
| -------- | |
| :manpage:`dsymutil(1)` |