LLVM-CXXMAP(1)

🎀 NAME

okay so bestie, welcome to llvm-cxxmap(1) — the LLVM manual page for the mangled name remapping tool. yes that's the whole vibe. it remaps mangled names. iconic behavior honestly.

---

🦋 SYNOPSIS

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

like literally just hand it two files and some options and it does its lil thing 💅

---

✨ DESCRIPTION

so the way that llvm-cxxmap works is it does fuzzy matching of C++ mangled names, and it figures out which ones are "the same" based on a file that tells it which name components should be considered equivalent. not me being a matchmaker for symbols fr fr.

your symbol files should just be a list of C++ mangled names, one per line. and listen — blank lines and lines starting with # get ignored, so you can leave lil comments around, go off.

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 cute part: mappings where the two symbols are literally identical get omitted, because why would we tell you a thing you already know 💖

---

💅 OPTIONS

• -remapping-file=file, -r=file — point this at a file containing the list of equivalence rules that decide whether two symbols are equivalent. this one is Required, no cap. see the REMAPPING FILE section below for the tea.
• -output=file, -o=file — where to write the list of matched names. if you don't specify it, it goes to stdout, which is honestly fine too.
• -Wambiguous — throws a warning if there are multiple equivalent (but distinct) symbols in symbol-file-2. it's giving "bestie there's more than one of these" energy.
• -Wincomplete — throws a warning if symbol-file-1 has a symbol that has no equivalent in symbol-file-2. awww, lonely symbol 🥺

---

🧚 REMAPPING FILE

okay this is the main character file. it's a text file with lines shaped like:

fragmentkind fragment1 fragment2

where fragmentkind is one of name, type, or encoding — telling you whether the mangled name fragments that follow are <name>s, <type>s, or <encoding>s respectively. and yes, blank lines and lines starting with # are ignored here too. consistent queen ✨

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

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

also, 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 don't gatekeep here 🫶

for example, to say that absl::string_view and std::string_view should be treated as equivalent, you could use a remapping file like:

# 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, that's the vibe check on scope 😭

---

👑 AUTHOR

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

---

🌸 COPYRIGHT

2003-2024, LLVM Project — periodt.

---

and that's the whole page bestie, we ate 💖 this was llvm-cxxmap(1) from the LLVM manual, version 11, dated 2024-07-18 — go remap some names and stay iconic 🌈👑🦋