Initial commit

namecollision/README.md

@@ -0,0 +1,116 @@
+# Name Collision / ODR Violation with Shared Libraries
+
+## The Setup
+
+`hello.cpp` defines a class `nt` with a method `print()`, used internally by
+`print_obj()`. `main.cpp` defines a `namespace nt` with a free function
+`print()`, and calls both `nt::print()` and `print_obj()`.
+
+`hello.cpp` is compiled into a shared library (`libhello.so`), and `main.cpp` is
+linked against it.
+
+## The Problem
+
+C++ name mangling encodes both **namespaces** and **classes** identically in the
+Itanium ABI (used on Linux):
+
+```
+namespace nt { void print() }  →  _ZN2nt5printEv
+class nt { void print() }      →  _ZN2nt5printEv
+```
+
+Both produce the exact same mangled symbol. The compiler has no way to
+distinguish them at link time.
+
+## What Actually Happens
+
+With `-O0` (no optimization):
+
+- `libhello.so` exports `_ZN2nt5printEv` as a **weak** symbol (the class method)
+- `main` defines `_ZN2nt5printEv` as a **strong/global** symbol (the namespace
+  function)
+- When `print_obj()` in the shared library calls `nt::print()`, the dynamic
+  linker resolves `_ZN2nt5printEv` at runtime and the **strong symbol in `main`
+  wins**
+- Result: `print_obj()` calls `main`'s `nt::print()` instead of the class method
+- Output: `"Hello from namespace"` printed twice
+
+With `-O3` (optimizations on):
+
+- The compiler inlines the class `nt::print()` directly into `print_obj()`
+- `_ZN2nt5printEv` is never emitted as a standalone symbol in `libhello.so`
+- No collision occurs — each call resolves correctly
+- Output: correct
+
+This is why the bug was **optimization-dependent** and hard to spot.
+
+## Symbol Evidence
+
+```
+# -O0: libhello.so exports the class method as weak
+00000000000011d0  w    F .text   _ZN2nt5printEv   ← weak, can be overridden
+
+# -O3: libhello.so does NOT export it at all (inlined away)
+# only _Z9print_objv is present
+```
+
+## One Definition Rule (ODR)
+
+The C++ standard (basic.def.odr) requires that any entity with more than one
+definition across translation units must have **identical** definitions.
+Violating this is **ill-formed, no diagnostic required** — the compiler and
+linker are not required to warn you.
+
+The consequences are undefined behavior: the program may crash, produce wrong
+output, or appear to work correctly depending on compiler flags, optimization
+level, or link order.
+
+## Linux Dynamic Linker Behavior
+
+On Linux, the dynamic linker (`ld.so`) uses a **flat symbol namespace** by
+default. When a shared library references a symbol, the linker searches all
+loaded objects (including the main executable) and resolves to the **first
+strong symbol found**, regardless of which DSO the symbol logically belongs to.
+
+This is different from macOS (which uses two-level namespaces by default) and
+Windows (where DLL symbols are explicitly imported/exported via import tables
+and don't collide this way).
+
+This flat namespace behavior means a weak symbol in a `.so` can be silently
+overridden by any strong symbol of the same name anywhere in the process — even
+from the main executable.
+
+## The Fix
+
+Wrap internal-use classes in an **anonymous namespace** in `hello.cpp`:
+
+```cpp
+namespace {
+    class nt {
+    public:
+        void print() { ... }
+    };
+}
+```
+
+This gives the class **internal linkage**. The mangled symbol becomes:
+
+```
+_ZN12_GLOBAL__N_12nt5printEv
+```
+
+The `_GLOBAL__N_1` prefix is the ABI encoding for the anonymous namespace,
+making it unique per translation unit and invisible to the dynamic linker. No
+collision is possible.
+
+## Key Takeaways
+
+- Class and namespace names mangle identically in the Itanium C++ ABI
+- Weak symbols in shared libraries can be silently hijacked by strong symbols in
+  the executable
+- ODR violations are UB with no required diagnostic — bugs may only appear at
+  certain optimization levels
+- Internal implementation details in shared libraries should use anonymous
+  namespaces to prevent symbol leakage
+- Use `objdump -t` or `nm` to inspect symbol visibility and catch these issues
+  early