LLVM-SYMBOLIZER(1)

📦

version 14.0.6 · 8 versions

💖 `llvm-symbolizer` 💖 — the LLVM manual, part 1

okay bestie, sit down, hydrate, because this is the tool that takes a sad little hex number like 0x400490 and tells you exactly which line of source it crawled out of. it's giving detective energy. it's giving "I found your bug and I'm not sorry". 🔍✨

and yes, we're doing this in two parts because there's a LOT here, so buckle up.

🌸 NAME 🌸

llvm-symbolizer — convert addresses into source code locations

✨ SYNOPSIS ✨

llvm-symbolizer [options] [addresses…]

💅 DESCRIPTION 💅

okay so. llvm-symbolizer reads object file names and addresses straight off the command line, then prints the matching source code locations to standard output. that's the whole vibe. that's the job. 👑

if you don't hand it any address on the command line, no worries — it just reads the addresses from standard input instead. and if you don't give it an object file on the command line but you do give it addresses, or if at any point an input value is just... not recognized? it simply echoes the input straight to the output. no drama, no crash, it just shrugs and mirrors it back at you. 🪞

a positional argument or a standard input value can be prefixed with DATA or CODE to say "hey, symbolize this as data" or "symbolize this as executable code" respectively. if you specify neither, CODE is assumed, periodt. and here's the tea: DATA gets symbolized as an address and symbol size rather than a line number. different treatment, same love. 💖

object files can be specified together with the addresses, either on standard input or as positional arguments on the command line, and they go right after any DATA or CODE prefix. yeah, it's flexible like that. 🦋

and one more thing bestie — llvm-symbolizer parses options from the environment variable LLVM_SYMBOLIZER_OPTS after it parses the options from the command line. LLVM_SYMBOLIZER_OPTS is primarily useful for supplementing the command-line options when llvm-symbolizer gets invoked by another program or runtime. it's the "hey, also do this" of env vars. 🙈

🎀 EXAMPLES 🎀

okay so every single example below uses these two source files as input. they mix C-style and C++-style linkage on purpose, to show you how those names get printed differently (peep --demangle for that whole situation).

// test.h
extern "C" inline int foz() {
  return 1234;
}

// test.cpp
#include "test.h"
int bar=42;

int foo() {
  return bar;
}

int baz() {
  volatile int k = 42;
  return foz() + k;
}

int main() {
  return foo() + baz();
}

and these files are built like this:

$ clang -g test.cpp -o test.elf
$ clang -g -O2 test.cpp -o inlined.elf

💜 Example 1 — addresses and object on command-line 💜

you got the object and the addresses, all on one line. chef's kiss. 🤌

$ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
foz
/tmp/test.h:1:0

baz()
/tmp/test.cpp:11:0

💜 Example 2 — addresses on standard input 💜

now the addresses are chilling in a file and we're piping them in.

$ cat addr.txt
0x4004a0
0x400490
0x4004d0
$ llvm-symbolizer --obj=test.elf < addr.txt
main
/tmp/test.cpp:15:0

baz()
/tmp/test.cpp:11:0

foz
/tmp/./test.h:1:0

ngl that last line really does print /tmp/./test.h:1:0 with the little ./ in there. that's not me being chaotic, that's literally the output. we don't make the rules, we just report them. 💀

💜 Example 3 — object specified with address 💜

now the object file is attached to each address. two of them, different ELFs, same command line.

$ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
baz()
/tmp/test.cpp:11:0

foo()
/tmp/test.cpp:8:10

$ cat addr2.txt
test.elf 0x4004a0
inlined.elf 0x400480

$ llvm-symbolizer < addr2.txt
main
/tmp/test.cpp:15:0

foo()
/tmp/test.cpp:8:10

💜 Example 4 — `CODE` and `DATA` prefixes 💜

here's where those prefixes show up in the wild. CODE gets you the usual function + line. DATA gets you the symbol name plus the address and size. two totally different aesthetics. 🌈

$ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
baz()
/tmp/test.cpp:11:0

bar
6295592 4

$ cat addr3.txt
CODE test.elf 0x4004a0
DATA inlined.elf 0x601028

$ llvm-symbolizer < addr3.txt
main
/tmp/test.cpp:15:0

bar
6295592 4

💜 Example 5 — path-style options 💜

same source file as above, except the source file's full path is /tmp/foo/test.cpp, and it gets compiled like this. first case = the default absolute path. second case = --basenames. third case = --relativenames. three flavors of "where does this file live". 🍓

$ pwd
/tmp
$ clang -g foo/test.cpp -o test.elf
$ llvm-symbolizer --obj=test.elf 0x4004a0
main
/tmp/foo/test.cpp:15:0
$ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
main
test.cpp:15:0
$ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
main
foo/test.cpp:15:0

💅 OPTIONS

Okay bestie, here's the whole menu of flags. Every single one. No skips. Let's go 🫶

--adjust-vma <offset> — adds that <offset> to object file addresses whenever we do a lookup. It's giving "pretend the object got relocated by this much" energy, so your lookups land where they would've if the relocation actually happened. ✨
--basenames, -s — just the file's name, no directories attached. Not the absolute path, just the lil bare name. She's lowkey minimal. 🎀
--demangle, -C — prints demangled function names when the names are mangled (like the mangled _Z3bazv becomes baz(), while the non-mangled name foz just gets printed as-is, no glow-up needed). Defaults to true. 💖
--dwp <path> — use the DWP file sitting at <path> for any CUs that have split DWARF debug data. That's it, that's the job. 🦋
--fallback-debug-path <path> — when a separate file has the debug data and it's referenced by a GNU debug link section, this <path> becomes the basis for finding that debug data if it can't be found relative to the object. Backup plan, but make it a path. 🌸
--functions [=<none|short|linkage>], -f — controls how function names get printed: omit the function name, print the short function name, or print the full linkage name (respectively, in that exact order). Defaults to linkage. 👑
--help, -h — shows help and usage for this command. The classic. 🌈
--inlining, --inlines, -i — if a source code location is inside an inlined function, this prints all the inlined frames. And bestie, this is the default. ✨
--no-inlines — don't print inlined frames. bye frames 💀
--no-demangle — don't print demangled function names. (Yes, she's the opposite twin of --demangle.) 🙈
--obj <path>, --exe, -e — path to the object file that's gonna get symbolized. And if you pass -, it reads the object directly from the standard input stream. Iconic. 💅
--output-style <LLVM|GNU|JSON> — picks your preferred output style. Defaults to LLVM. When it's set to GNU, the tool follows the style of GNU's addr2line. The differences from the LLVM style are:
- Does not print the column of a source code location.
- Does not add an empty line after the report for an address.
- Does not replace the name of an inlined function with the name of the topmost caller when inlined frames are not shown.
- Prints an address's debug-data discriminator when it is non-zero. One way to produce discriminators is to compile with clang's -fdebug-info-for-profiling.

And JSON style provides a machine readable output in JSON. If addresses are supplied via stdin, the output JSON will be a series of individual objects. Otherwise, all results will be contained in a single array. 🧚

$ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
baz() at /tmp/test.cpp:11:18
 (inlined by) main at /tmp/test.cpp:15:0

foo() at /tmp/test.cpp:6:3

$ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
main at /tmp/test.cpp:11:18

foo() at /tmp/test.cpp:6:3

$ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
baz() at /tmp/test.cpp:11
foo() at /tmp/test.cpp:6

$ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
$ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
main at /tmp/test.cpp:15 (discriminator 2)

$ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
[
  {
    "Address": "0x4004be",
    "ModuleName": "inlined.elf",
    "Symbol": [
      {
        "Column": 18,
        "Discriminator": 0,
        "FileName": "/tmp/test.cpp",
        "FunctionName": "baz()",
        "Line": 11,
        "StartAddress": "0x4004be",
        "StartFileName": "/tmp/test.cpp",
        "StartLine": 9
      },
      {
        "Column": 0,
        "Discriminator": 0,
        "FileName": "/tmp/test.cpp",
        "FunctionName": "main",
        "Line": 15,
        "StartAddress": "0x4004be",
        "StartFileName": "/tmp/test.cpp",
        "StartLine": 14
      }
    ]
  },
  {
    "Address": "0x400486",
    "ModuleName": "inlined.elf",
    "Symbol": [
      {
        "Column": 3,
        "Discriminator": 0,
        "FileName": "/tmp/test.cpp",
        "FunctionName": "foo()",
        "Line": 6,
        "StartAddress": "0x400486",
        "StartFileName": "/tmp/test.cpp",
        "StartLine": 5
      }
    ]
  }
]

--pretty-print, -p — prints human readable output. If --inlining is specified, the enclosing scope gets prefixed by (inlined by). And for JSON output, this option makes the JSON indented and split over new lines — otherwise the JSON output gets printed in a compact form. 💖

$ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
baz() at /tmp/test.cpp:11:18
 (inlined by) main at /tmp/test.cpp:15:0

--print-address, --addresses, -a — prints the address before the source code location. Defaults to false.

$ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
0x4004be
baz()
/tmp/test.cpp:11:18
main
/tmp/test.cpp:15:0

$ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
0x4004be: baz() at /tmp/test.cpp:11:18
 (inlined by) main at /tmp/test.cpp:15:0

--print-source-context-lines <N> — prints <N> lines of source context for each symbolized address. Context queen. 👑

$ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
baz()
/tmp/test.cpp:11:0
10  :   volatile int k = 42;
11 >:   return foz() + k;
12  : }

--relativenames — prints the file's path relative to the compilation directory instead of the absolute path. And heads up: if the command-line to the compiler already included the full path, then this will be the same as the default. 🎀
--verbose — prints verbose address, line and column information. All the deets, no gatekeeping. 🌸

$ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
baz()
  Filename: /tmp/test.cpp
  Function start filename: /tmp/test.cpp
  Function start line: 9
  Function start address: 0x4004b6
  Line: 11
  Column: 18
main
  Filename: /tmp/test.cpp
  Function start filename: /tmp/test.cpp
  Function start line: 14
  Function start address: 0x4004b0
  Line: 15
  Column: 18

--version, -v — prints version information for the tool. ✨
@<FILE> — reads command-line options from the response file <FILE>. 🦋

🪟 WINDOWS/PDB SPECIFIC OPTIONS 🪟

--dia — use the Windows DIA SDK for symbolization. And if the DIA SDK isn't found, llvm-symbolizer will fall back to the native implementation. No drama, she adapts. 💅

🍎 MACH-O SPECIFIC OPTIONS 🍎

--default-arch <arch> — if a binary contains object files for multiple architectures (say it's a Mach-O universal binary), this symbolizes the object file for the given architecture. You can also specify the architecture by writing binary_name:arch_name in the input (peep the example below). And if the architecture isn't specified in either way? The address will not be symbolized. Defaults to empty string. 💀

$ cat addr.txt
/tmp/mach_universal_binary:i386 0x1f84
/tmp/mach_universal_binary:x86_64 0x100000f24

$ llvm-symbolizer < addr.txt
_main
/tmp/source_i386.cc:8

_main
/tmp/source_x86_64.cc:8

--dsym-hint <path/to/file.dSYM> — if the debug info for a binary isn't chilling in the default location, go look for it at the .dSYM path you hand over with this option. And yes, this flag can be used multiple times. Stack 'em. 🔥

🚪 EXIT STATUS 🚪

llvm-symbolizer returns 0. Any other exit codes imply an internal program error. So if you get anything else, something inside is Not Okay. 😭

👀 SEE ALSO 👀

llvm-addr2line(1)

🌟 AUTHOR 🌟

Maintained by the LLVM Team (https://llvm.org/).

📜 COPYRIGHT 📜

2003-2025, LLVM Project

And that's the whole page bestie, we ate and left zero crumbs. 🍓 This one's from the LLVM Project, version 14, dated 2025-05-22 — LLVM-SYMBOLIZER(1), main character of the man pages, no cap. 💜

📦 where this page comes from

ubuntu questing: llvm-14 1:14.0.6-20ubuntu3
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms