LLVM-CXXMAP(1)

💅 llvm-cxxmap — the mangled-name remapping tool (LLVM manual, bestie edition)

okay so first things first: this is a page from the LLVM manual set, and the star of the show is llvm-cxxmap. Buckle up, it's actually kind of iconic.

---

✨ NAME ✨

llvm-cxxmap — mangled name remapping tool 🎀

---

🌸 SYNOPSIS 🌸

llvm-cxxmap [options] symbol-file-1 symbol-file-2

---

🦋 DESCRIPTION 🦋

so what does llvm-cxxmap actually do? it performs fuzzy matching of C++ mangled names, based on a file that describes which name components should be considered equivalent. that's the whole vibe. 💫

the symbol files should each contain a list of C++ mangled names — one per line, no cap. blank lines and lines starting with # are ignored (we love a comment-friendly format, periodt).

the output is a list of pairs of equivalent symbols, one per line, looking like this:

<symbol-1> <symbol-2>

where <symbol-1> is a symbol from symbol-file-1 and <symbol-2> is a symbol from symbol-file-2. and here's the little detail nobody tells you: mappings for which the two symbols are identical are omitted. 🙈 like, if it's the same symbol, why even show it, yk?

---

💖 OPTIONS 💖

• -remapping-file=file, -r=file — specify a file containing a list of equivalence rules that should be used to determine whether two symbols are equivalent. this one is Required, bestie — not optional, fr fr. see REMAPPING FILE below 👇
• -output=file, -o=file — specify a file to write the list of matched names to. if you don't specify one, the list gets written to stdout. classic.
• -Wambiguous — produce a warning if there are multiple equivalent (but distinct) symbols in symbol-file-2. (distinct is doing a lot of heavy lifting there 💀)
• -Wincomplete — produce a warning if symbol-file-1 contains a symbol for which there is no equivalent symbol in symbol-file-2. like, no match found, so sad 😭

---

🧚 REMAPPING FILE 🧚

the remapping file is a text file containing lines of the form

fragmentkind fragment1 fragment2

where fragmentkind is one of name, type, or encoding — indicating whether the following mangled name fragments are <name>s (http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name), <type>s (http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type), or <encoding>s (http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding), respectively. slay. 💅

blank lines and lines starting with # are ignored — yes, again, we stan consistency.

unmangled C names can be expressed as an encoding that is a (length-prefixed) <source-name> (http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.source-name):

# C function "void foo_bar()" is remapped to C++ function "void foo::bar()".
encoding 7foo_bar _Z3foo3barv

for convenience, built-in <substitution>s such as St and Ss are accepted as <name>s — even though they technically are not <name>s. lowkey a little rule-breaking but we allow it 🫶

for example, to specify that absl::string_view and std::string_view should be treated as equivalent, the following remapping file could be used:

# absl::string_view is considered equivalent to std::string_view
type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE

# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
name St St3__1
name St St7__cxx11

💀 Note 💀

symbol remapping is currently only supported for C++ mangled names following the Itanium C++ ABI mangling scheme. this covers all C++ targets supported by Clang other than Windows targets. so like... not Windows. noted. 🫡

---

👑 Author 👑

maintained by the LLVM Team (https://llvm.org/). the main characters themselves, honestly.

---

🌈 Copyright 🌈

2003-2026, LLVM Project

---

and that's the whole page, bestie! 🎀✨ this was page 21, dated 2026-05-15, source LLVM — go forth and remap those mangled names, you absolute icon 💜🦋