LLVM-CXXMAP(1)

💖 llvm-cxxmap 💖

okay bestie, gather round, because today we're talking about llvm-cxxmap, aka the Mangled name remapping tool from the LLVM fam. it lives in the LLVM manual set and honestly? it's giving matchmaker energy. ✨

---

🌸 SYNOPSIS 🌸

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

that's it. two symbol files, some options, and a whole lot of name-matching drama. 🎀

---

🦋 DESCRIPTION 🦋

so what does llvm-cxxmap actually do, you ask? it performs fuzzy matching of C++ mangled names, and it figures out what matches based on a file describing name components that should be considered equivalent. like, "these two things? yeah, same thing, bestie." 💅

the symbol files should contain a list of C++ mangled names, one per line. and listen — blank lines and lines starting with # are ignored, so you can leave cute lil notes for yourself, no judgement. 🙈

the output is a list of pairs of equivalent symbols, one per line, and it looks 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 thing — mappings for which the two symbols are identical are omitted. if it's the same symbol, it's not a mapping, it's just... itself. periodt. 💀

---

✨ OPTIONS ✨

• -remapping-file=file, -r=file — point this at a file containing a list of equivalence rules that should be used to determine whether two symbols are equivalent. this one is Required — like, no remapping file, no remapping, bestie. see REMAPPING FILE below for the tea. 🔥
• -output=file, -o=file — specify a file to write the list of matched names to. if unspecified, the list gets written to stdout, which is honestly fine too. 👑
• -Wambiguous — produce a warning if there are multiple equivalent (but distinct) symbols in symbol-file-2. like, girl, pick one?? 😭
• -Wincomplete — produce a warning if symbol-file-1 contains a symbol for which there is no equivalent symbol in symbol-file-2. nobody left behind... except this symbol. it's left behind. 💔

---

🎀 REMAPPING FILE 🎀

okay this is the main character of the whole operation. 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, <type>s, or <encoding>s, respectively. blank lines and lines starting with # are ignored here too — consistency, we love to see it. ✨

unmangled C names can be expressed as an encoding that is a (length-prefixed) <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. they're lying about their identity a little bit. we support them anyway. 🫶

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 if you're on a Windows target, this is not your moment, bestie. 💀

---

🌈 AUTHOR 🌈

maintained by the LLVM Team (https://llvm.org/). iconic behavior, truly. 👑

---

💜 COPYRIGHT 💜

2003-2025, LLVM Project. that's a long-running era and we respect it. 🫶

---

and that's the whole vibe check! this page came from the LLVM manual collection, version/date situation being 2025-05-22 — go forth and remap those mangled names, bestie, you're gonna slay. 💅✨🌸