LLVM-DWARFDUMP(1)

📦
version 23.1.4 · 11 versions
, in arch rolling

💅 llvm-dwarfdump — the LLVM manual page, but make it make sense ✨

okay so bestie, welcome to llvm-dwarfdump, one of the LLVM tools. It's the one that dumps and verifies DWARF debug information, and honestly? It's giving main character energy for anyone who's ever stared at a debug binary going "what is in here 😭". Let me walk you through it, no cap.

🌸 SYNOPSIS 🌸

llvm-dwarfdump [options] [filename ...]

literally just options and then zero or more filenames, that's the whole vibe 🫶

💖 DESCRIPTION 💖

okay so llvm-dwarfdump parses DWARF sections inside object files, archives, and .dSYM bundles, and prints their contents in human-readable form. Iconic behaviour. It takes that raw binary soup and makes it readable, we love to see it.

here's the important bit tho: only the .debug_info section is printed unless you specify one of the section-specific options or --all. So don't come for it when you only get .debug_info bestie, that's the default, that's the assignment 💅

and if you pass no input file at all? it uses a.out instead. classic. If you use - as the input file, llvm-dwarfdump reads the input from its standard input stream. cute 🎀

✨ OPTIONS ✨

  • -a, --all — dump all supported DWARF sections. the "just give me everything" option, and honestly, sometimes you need that.
  • --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. so yeah, repeat it as much as you want, it's not jealous 🌈
  • -c, --show-children — show a debug info entry's children when selectively printing with the =<offset> argument of --debug-info, or options such as --find or --name. it's giving "show me the kids too" 🧚
  • --color — use colors in output. yes queen, make those terminal bytes pretty 🌸
  • --error-display=<value> — set the level of detail and summary to display when verifying. This implies --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]

so full is the default, it's the overachiever of the group and honestly slay 💜

  • -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 --name option. so like, --find is the fast one and --name is the thorough one. iykyk 😌
  • -F, --show-form — show DWARF form types after the DWARF attribute types. little extra detail, big energy 🔥
  • -h, --help — show help and usage for this command. the classic "help me" button, we've all been there 🙈
  • --help-list — show help and usage for this command without grouping the options into categories. same help, just one big flat list instead of cute organized categories 🦋
  • -i, --ignore-case — ignore case distinctions when using --name. so Foo and foo are the same girl, periodt 🎀
  • -n <name>, --name=<name> — find and print all debug info entries whose name (DW_AT_name/DW_AT_linkage_name attribute) is <name>. the thorough search bestie 💖
  • --lookup=<address> — look up <address> in the debug information and print out the file, function, block, and line table details. address goes in, lore comes out ✨
  • -o <path> — redirect output to a file specified by <path>, where - is the standard output stream. so you can yeet your output into a file, or back to stdout with - 🫶
  • -p, --show-parents — show a debug info entry's parents when selectively printing with the =<offset> argument of --debug-info, or options such as --find or --name. the opposite of --show-children, it's the "who raised you" option 😭
  • --parent-recurse-depth=<N> — when displaying debug info entry parents, only show them to a maximum depth of <N>. keeps the family tree from getting out of hand 🌳
  • --quiet — use with --verify to not emit to STDOUT. silence. peace. no notes 💀
  • -r <N>, --recurse-depth=<N> — when displaying debug info entries, only show children to a maximum depth of <N>. same vibe, but for the kids 🎀
  • --show-section-sizes — show the sizes of all debug sections, expressed in bytes. numbers, we love numbers ⭐
  • --show-sources — print all source files mentioned in the debug information. Absolute paths are given whenever possible. a little who's-who of your sources 💜
  • --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 (FORMAT OF STATISTICS OUTPUT). yes it's json, yes it's one line, get into it 🌈
  • --summarize-types — abbreviate the description of type unit entries. short and sweet, we stan a concise queen 💅
  • -t, --filter-child-tag — only dump children whose DWARF tag is one of the specified tags. Example usage:
llvm-dwarfdump -t DW_TAG_structure_type -t DW_TAG_member -c

so you can stack -t like little stickers and filter exactly what you want 🍓

  • -x, --regex — treat any <name> strings as regular expressions when searching with --name. If --ignore-case is also specified, the regular expression becomes case-insensitive. regex girlies, this one's for you 🔥
  • -u, --uuid — show the UUID for each architecture. ID check bestie 🪪
  • --diff — dump the output in a format that is more friendly for comparing DWARF output from two different files. extremely useful when you're like "why did this change??" 😭
  • -v, --verbose — display verbose information when dumping. This can help to debug DWARF issues. when it gets weird, add -v, that's the move 🫶
  • --verify — verify the structure of the DWARF information by verifying the compile unit chains, DIE relationships graph, address ranges, and more. it's the vibe check for your debug info, and it does NOT let things slide 👑
  • --verify-json=<path> — output JSON-formatted error summary to the file specified by <path>. Implies --verify. The output format is described in the section below (FORMAT OF VERIFY JSON OUTPUT). machine-readable receipts, iconic 💖
  • --version — display the version of the tool. which one are we running, bestie 🌸
  • --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 --debug-macro option prints both the .debug_macro and the .debug_macinfo sections. two for one, we love a bundle 💅

The --debug-frame and --eh-frame options are aliases, in cases where both sections are present one command outputs both. so don't @ them for being the same, they know 🦋

  • --show-variable-coverage — show per-variable coverage metrics. The output format is described in the section below (FORMAT OF VARIABLE COVERAGE OUTPUT). 📊
  • --coverage-baseline — file to use as the baseline for variable coverage statistics (implies --show-variable-coverage). the "compare it to this" file 💖
  • --variable-coverage-bitcode-file — file containing LLVM IR (bitcode or textual) used for calculating variable definedness in coverage statistics (implies --show-variable-coverage). yes, bitcode or textual, both are welcome here 🎀
  • --combine-inline-variable-instances — use with --show-variable-coverage to average variable coverage across inlined subroutine instances instead of printing them separately. group chat energy: average them out instead of one-by-one 🌸
  • @<FILE> — read command-line options from <FILE>. options in a file, extremely convenient, no notes 🫶

🌈 FORMAT OF STATISTICS OUTPUT 🌈

The --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. so it's the perfect thing to bring to your "did my compiler change make things better or worse" moment 💅

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.

🦋 FORMAT OF VERIFY JSON OUTPUT 🦋

The format of the JSON output created by the --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
}

empty categories and a big fat zero, the dream scenario honestly 😌✨

🍓 FORMAT OF VARIABLE COVERAGE OUTPUT 🍓

The --show-variable-coverage option differs from --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. so it's the more chill, more meaningful metric, and i'm obsessed 🤌

The output is a tab-separated table containing the following columns:

  • Function ==> name of the function the variable was found in
  • InstanceCount (when --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 --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 --coverage-baseline is not specified) ==> number of source lines covered by the variable's debug information in the baseline
  • CoveredRatio (empty if --coverage-baseline is not specified) ==> ratio of the coverage compared to the baseline (calculated as LinesCovered/Baseline)
  • LinesPresent (empty if --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 --coverage-baseline is not specified) ==> ratio of the line table coverage compared to the baseline (calculated as LinesPresent/Baseline)

💜 EXIT STATUS 💜

llvm-dwarfdump returns 0 if the input files were parsed and dumped successfully. Otherwise, it returns 1. that's it, that's the whole story. success is 0, anything else is 1, no in-between drama 💀

🔥 SEE ALSO 🔥

dsymutil(1) <dsymutil.html> — go check that one out too bestie, it's in the same friend group 💖

👑 Author 👑

Maintained by the LLVM Team (https://llvm.org/). they keep the whole thing running and we appreciate them fr fr 🫶

2003-2026, LLVM Project

ok that's the whole page bestie, go dump some DWARF and slay 💅✨

and one last cute sign-off: this iconic piece of documentation was brought to you by LLVM-DWARFDUMP(1) from the LLVM manual collection, dated 2026-10-20, page 23 of the manual. mwah, go verify some debug info 🎀💜

📦 where this page comes from