LLVM-CXXMAP(1)

💖 LLVM-CXXMAP(1) 💖

okay bestie, welcome to llvm-cxxmap — the Mangled name remapping tool ✨ it's the LLVM manual page, and it's lowkey iconic. let's get into it 🫶

---

✨ SYNOPSIS ✨

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

---

🌸 DESCRIPTION 🌸

so basically, the llvm-cxxmap tool does fuzzy matching of C++ mangled names, based on a file that describes which name components should be treated as equivalent. it's giving matchmaker but for symbols 💅

your symbol files should contain a list of C++ mangled names, one per line. blank lines and lines starting with #? yeah, those get ignored, we don't claim them 🚫

the output is a list of pairs of equivalent symbols, one per line, and the form is literally 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 where the two symbols are identical are omitted. no duplicates on our watch, periodt 👑

---

💅 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. Required. go look at REMAPPING FILE below, iykyk 🔥
• -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. default behavior slay 💖
• -Wambiguous — produce a warning if there are multiple equivalent (but distinct) symbols in symbol-file-2. messy behavior, we're calling it out 😭
• -Wincomplete — produce a warning if symbol-file-1 contains a symbol for which there is no equivalent symbol in symbol-file-2. bestie's lonely, we warn about it 🥺

---

🎀 REMAPPING FILE 🎀

the remapping file is a text file containing lines of this exact 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, same as before ✨

unmangled C names can be expressed as an encoding that is a (length-prefixed) <source-name>. like this, for example:

# 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 🙈 (we let it slide, it's fine)

so for example, to specify that absl::string_view and std::string_view should be treated as equivalent, this 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 Windows... not today, bestie 💀

---

💜 AUTHOR 💜

Maintained by the LLVM Team (https://llvm.org/). they're the main characters fr fr 👑

---

🌈 COPYRIGHT 🌈

2003-2024, LLVM Project. all the rights, all the vibes ✨

---

okay that's the whole page bestie, you're officially fluent in llvm-cxxmap now 🦋 this was LLVM-CXXMAP(1), LLVM version 12, dated 2024-07-18 — go remap some names, you absolute icon, mwah 💖🎀