LLVM-SYMBOLIZER(1)

💖 llvm-symbolizer 💖

okay bestie, welcome to LLVM-SYMBOLIZER(1) — the section 1 manual page for llvm-symbolizer, brought to you by the LLVM girlies. she's a little compiler-adjacent legend whose whole job is taking your sad little raw addresses and turning them into actual source code locations. it's giving glow-up, fr fr. 🦋

---

✨ NAME ✨

llvm-symbolizer — convert addresses into source code locations 💅

---

✨ SYNOPSIS ✨

llvm-symbolizer [options] [addresses...]

---

✨ DESCRIPTION ✨

okay so here's the tea. llvm-symbolizer reads input names and addresses from the command line and prints the corresponding source code locations to standard output. no cap, that's the whole vibe. 🌸

she can also symbolize logs containing Symbolizer Markup <> — that's what the --filter-markup flag is for. 💫

and your addresses? they can be either plain numbers or symbol names. flexible queen. 👑

how she gets her input 🎀

• If no address is specified on the command line, she reads the addresses from standard input instead.
• If no input name is given on the command line, but addresses are, then the first address value gets treated as an input name. plot twist. 😭
• If an input value isn't recognized at all, she just reports that source information is not found. not a crash, just a gentle "bestie I don't know her". 💀

input names, explained 🫶

Input names can come along with the addresses either on standard input or as positional arguments on the command line. two roads, same destination.

By default, input names are interpreted as object file paths. simple. clean. iconic.

But! you can prefix a name to change what she thinks it is:

• BUILDID: prefix → nope, that's not a path, that's a hex build ID. she'll go look up the corresponding debug binary for you. 🕵️♀️
• FILE: prefix → yes bestie this is an object file path. (this is also the default, so it's really just here for consistency and for when you want to be explicit. clarity is hot.) ✨

DATA vs CODE 📊💻

A positional argument or a standard input value can be preceded by DATA or CODE to say whether the address should be symbolized as data or as executable code respectively.

• If you specify neither, CODE is assumed. she just assumes code by default, she's optimistic like that.
• DATA gets symbolized as address and symbol size rather than a line number. different treatment, same love.

the environment variable moment 🌈

llvm-symbolizer parses options from the environment variable LLVM_SYMBOLIZER_OPTS after parsing options from the command line.

LLVM_SYMBOLIZER_OPTS is primarily useful for supplementing the command-line options when llvm-symbolizer is invoked by another program or runtime. it's the "hey can you pass this along for me" of env vars. iykyk. 💜

---

✨ EXAMPLES ✨

Every single example below uses the same two source files as input. they mix C-style and C++-style linkage on purpose, to show off how those names get printed differently (peep --demangle for that). 📝

// 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 get 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

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

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

she ate that. two addresses, two beautiful little answers. 💅

---

🌟 Example 2 — addresses on standard input

$ 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

note the /tmp/./test.h in the last one — yeah she said it like that, that's just what the output is. 🙈

---

🌟 Example 3 — object specified with address

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

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

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

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

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

the way you can just smush the object and the address together in one argument?? obsessed. 😍

---

🌟 Example 4 — BUILDID and FILE prefixes

$ llvm-symbolizer "FILE:test.elf 0x400490" "DATA BUILDID:123456789abcdef 0x601028"
baz()
/tmp/test.cpp:11:0

bar
6295592 4

$ cat addr3.txt
FILE:test.elf 0x400490
DATA BUILDID:123456789abcdef 0x601028

$ llvm-symbolizer < addr3.txt
baz()
/tmp/test.cpp:11:0

bar
6295592 4

see how DATA gives you 6295592 4 (address + size) instead of a line number? that's the whole DATA moment. 🔥

---

🌟 Example 5 — CODE and DATA prefixes

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

bar
6295592 4

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

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

bar
6295592 4

CODE and DATA doing their thing, coexisting in perfect harmony. bestie duo energy. 🫶

---

🌟 Example 6 — path-style options

This example uses the same source file as above, but the source file's full path is /tmp/foo/test.cpp and is compiled as follows. The first case shows the default absolute path, the second --basenames, and the third shows --relativenames.

$ 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

three different path vibes, one source file. pick your fighter. ⚔️✨

---

🌟 Example 7 — Addresses as symbol names

$ llvm-symbolizer --obj=test.elf main
main
/tmp/test.cpp:14:0
$ llvm-symbolizer --obj=test.elf "CODE foz"
foz
/tmp/test.h:1:0

yeah you can just. hand her a symbol name. no hex required. iconic behaviour. 👑

---

🌟 Example 8 — --skip-line-zero output for an address with no line correspondence (an address associated with line zero)

// test.c
int foo = 0;
int x = 1234;
int main() {
  if (x)
    return foo;
  else
    return x;
}

These files are built as follows:

$ clang -g -O2 -S test.c -o test.s
$ llvm-mc -filetype=obj -triple=x86_64-unknown-linux  test.s -o test.o

$ llvm-symbolizer --obj=test.o --skip-line-zero 0xa
main
/tmp/test.c:5:7 (approximate)

see that (approximate) at the end? she's being honest with you, that's all. 🌸

---

and that's part 1, bestie — there's more coming so don't go anywhere 💖

✨ OPTIONS ✨

okay bestie, this is the part where it gets juicy. every single flag, no skips, we're doing all of them 💅

• --adjust-vma <offset> — adds the offset you give it to object file addresses when it's doing lookups. basically you can do lookups as if the object got relocated by that offset. pretend-relocation, iconic behavior 🎀
• --skip-line-zero — if an address has no line number attached to it, it grabs the last line number from the current sequence in the line-table instead. those lines get labeled "approximate" in the output, because ngl they might be misleading 🙈
• --basenames, -s — prints just the file's name, no directories, instead of the whole absolute path. stripped down, clean, minimal 💅
• --build-id — looks up the object using the build ID you give it, written as a hexadecimal string. mutually exclusive with --obj, so pick a lane bestie, you can't have both.
• --color [=<always|auto|never>] — tells it whether to use color in --filter-markup mode. defaults to auto, which sniffs out whether standard output supports color. and if you just say --color on its own, that's the same as --color=always. slay 🌈
• --debug-file-directory <path> — hands over a path to a directory containing a .build-id subdirectory, so it can hunt for debug info for stripped binaries. if you pass this argument multiple times, they get searched in the order you gave them 🔍
• --debuginfod, --no-debuginfod — whether or not to try debuginfod lookups for debug binaries. unless you say otherwise, debuginfod is only enabled if libcurl was compiled in (LLVM_ENABLE_CURL) and at least one server URL was provided by the environment variable DEBUGINFOD_URLS.
• --demangle, -C — prints demangled function names if the names are mangled (so like the mangled name _Z3bazv becomes baz(), while the non-mangled name foz just gets printed as-is). defaults to true 💖
• --dwp <path> — uses the DWP file at <path> for any CUs that have split DWARF debug data.
• --fallback-debug-path <path> — when a separate file holds debug data and it's referenced by a GNU debug link section, this path is used as a basis for locating the debug data if it can't be found relative to the object. backup plan energy 🫶
• --filter-markup — reads from standard input, converts the contained Symbolizer Markup <> into human-readable form, and prints the results to standard output. heads up: these markup elements are not yet supported:
  • {{{hexdict}}}
  • {{{dumpfile}}}

the {{{bt}}} backtrace element reports frames with this syntax:

#<number>[.<inline>] <address> <function> <file>:<line>:<col> (<module>+<relative address>)

<inline> gives you frame numbers for calls inlined into the caller corresponding to <number>. the inlined call numbers start at 1 and increase from callee to caller.

<address> is an address inside the call instruction to the function. and important: the address may not be the start of the instruction. <relative address> is the corresponding virtual offset in the <module> loaded at that address.

• --functions [=<none|short|linkage>], -f — picks how function names get printed: omit the function name, print the short function name, or print the full linkage name, respectively. 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, it prints all the inlined frames. this is the default, so you're already living the dream.
• --no-inlines — don't print inlined frames. simple as.
• --no-demangle — don't print demangled function names. raw names only, no glow-up.
• --obj <path>, --exe, -e — path to the object file that's getting symbolized. if you pass -, it reads the object directly from the standard input stream. mutually exclusive with --build-id — again, one or the other, periodt.
• --output-style <LLVM|GNU|JSON> — sets the preferred output style. defaults to LLVM. when you set it to GNU, the tool follows the style of GNU's addr2line. here's what's different from the LLVM style:
  • it does not print the column of a source code location.
  • it does not add an empty line after the report for an address.
  • it does not replace the name of an inlined function with the name of the topmost caller when inlined frames aren't shown.
  • it prints an address's debug-data discriminator when it's non-zero. one way to produce discriminators is to compile with clang's -fdebug-info-for-profiling.

JSON style gives you machine-readable output in JSON. if addresses are supplied via stdin, the output JSON will be a series of individual objects. otherwise, all the 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 with (inlined by). and for JSON output, this option makes the JSON indented and split over new lines — otherwise the JSON gets printed in a compact form. aesthetic ✨

$ 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. little peek into the code, obsessed 📖

$ 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. if the command-line to the compiler already included the full path, this ends up being the same as the default.
• --verbose — prints verbose address, line and column information. the whole receipts 🧾

$ 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 — uses the Windows DIA SDK for symbolization. and if the DIA SDK isn't found, llvm-symbolizer will fall back to the native implementation. no cap, it's got a plan B 🦋

🍎 MACH-O SPECIFIC OPTIONS 🍎

okay bestie this section is Apple-core and it's giving very specific, very slay 🍓

• --default-arch <arch> — so like, if a binary has object files for multiple architectures (think a Mach-O universal binary, or an archive with architecture variants), this tells the symbolizer which architecture's object file to actually symbolize. You can also just say the architecture inline by writing binary_name:arch_name in the input (peep the example down below, it's adorable). And for archives, the format archive.a(member.o):arch is supported too 💅 BUT — if you don't specify the architecture at all, the address will not be symbolized. Not a vibe, but that's the rule. Defaults to empty string.

$ cat addr.txt
/tmp/mach_universal_binary:i386 0x1f84
/tmp/mach_universal_binary:x86_64 0x100000f24
/tmp/archive.a(member.o):ppc 0x1000
/tmp/archive.a(member.o):ppc64 0x2000

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

_main
/tmp/source_x86_64.cc:8

_foo
/tmp/source_ppc.cc:12

_foo
/tmp/source_ppc64.cc:12

• --dsym-hint <path/to/file.dSYM> — if the debug info for a binary isn't chilling in its default location, hand it the .dSYM path through this option and it'll go looking there 🦋 and yes bestie, this flag is stackable — use it as many times as you need, no cap.

---

🚪 EXIT STATUS 🚪

llvm-symbolizer returns 0. That's it, that's the whole status. Any other exit code means an internal program error happened — so if you see one, something's lowkey wrong inside the program itself 😭

---

👀 SEE ALSO 👀

• llvm-addr2line(1) <llvm-addr2line.html> — its whole sibling, go say hi 🫶

---

✍️ Author ✍️

Maintained by the LLVM Team (https://llvm.org/). Kings and queens, honestly 👑

---

©️ Copyright ©️

2003-2026, LLVM Project 🌈

---

and that's the whole page, bestie!! 💖 you just read LLVM-SYMBOLIZER(1) — part of LLVM, dated 2026-07-16, page 22 in the old-school manpage footer numbering. go symbolize something iconic, mwah 🎀✨