Name Mangling

A relocatable object file contains a symbol table, and a symbol table entry is a name, a section, an offset and a few flags. There is no type. When a caller references foo and some object defines foo, the linker matches them because the bytes of the two names are equal, and it does nothing else — this is the whole of [[symbols-and-references]].

That is fine for C, where a program may contain at most one external entity called foo. It is immediately fatal for any language with overloading, namespaces, member functions, or generics instantiated per type argument, because all of those permit several distinct entities to share a source-level name. The resolution is to encode the distinguishing information into the name itself, so that the flat string namespace becomes an injective image of the structured one.

The name that comes out is therefore not a decoration. It is a serialisation of a declaration — scope, name, parameter types, qualifiers, template arguments — into a byte string, chosen so it can be decoded back. That is why c++filt can turn _ZN3foo3barEid back into foo::bar(int, double) with no other information: the string contains the declaration.

The single most useful skill here is reading a linker error as evidence about mangling. When the message names a mangled symbol, the caller was compiled as C++ and expects a C++ symbol. When it names a bare symbol, the caller expected a C symbol. Comparing that to what the library actually defines — nm -C will show you — identifies the mismatch immediately.

The classic case is a C++ program calling a C library whose header lacks extern "C" guards. The C++ compiler reads the declaration, mangles it, and emits a reference to _Z6strlenPKc. The C library defines strlen. Both objects are perfectly well formed and the names do not match, so the link fails with an error naming a symbol that appears nowhere in anyone's source.

The inverse also happens: a C++ function is declared extern "C" in one header and not in another, so one translation unit calls the mangled name and the other defines the unmangled one. And a subtler variant that is not about mangling at all — declaring a function and never defining it — produces the identical message, which is why the error alone does not tell you which of the four causes you have.

The declaration extern "C" void f(int); does two things and it is worth being precise about both. It tells the compiler to emit and reference the symbol under its unmangled name, and it gives the function C language linkage, which on most platforms means the platform C calling convention. It does *not* change the language the body is written in: an extern "C" function may be defined in C++, use C++ types internally, and call C++ code.

What it costs is exactly what mangling bought. Two extern "C" functions cannot share a name, so overloads are impossible on the boundary. Templates cannot be extern "C" because each instantiation would need the same name. And because a C symbol carries no type information, nothing checks that the caller and the definition agree about the signature — the type safety that mangling accidentally provided is gone.

That accidental type safety is worth pausing on. Because a mangled name encodes the parameter types, a C++ caller whose header disagrees with the definition's types gets a link error rather than a silent mismatch. C gets no such protection: change a parameter from int to long in the definition and not in the header, and the program links and passes the wrong-width value. Mangling is a naming scheme that turns out to be a weak ABI checker, which is precisely the property [[abi]] says the system otherwise lacks.

Mangling is not a C++ oddity; it is what any language needs the moment two distinct entities can share a name. Rust mangles because it has modules, traits and generics, and its scheme includes a hash of the crate identity and version so that two versions of the same crate in one binary produce distinct symbols — a deliberate design response to the diamond-dependency problem that C++ does not solve. Swift mangles for the same reasons plus protocol conformances.

The interesting contrast is with languages that avoid the problem. Go does not overload and its symbols are essentially package-qualified names, so its mangling is nearly trivial. Java has overloading but resolves it inside the class file format, which stores a full descriptor next to each name rather than encoding it into the name — the JVM's "symbol table" is structured, so it does not need the trick at all.

That last point is the general lesson. Mangling is a workaround for a flat, untyped symbol table. A linker that understood types would need none of it. Nobody has replaced the flat symbol table because every language and every tool on every platform depends on it, which is a fair description of most of what is in [[toolchains]].