56 Handling name collisions — from prefixes to namespace

56.1 When and where collisions go off

Spellings collide in three places, and each is harder to diagnose than the last.

The third is why this chapter exists. Three places where silent collisions arise.

• The link order of static libraries. If libfoo.a and libbar.a both carry the name, the linker takes whichever it met first on the command line and stops. Reorder the libraries and the program behaves differently.
• Weak symbols. A name the implementation marked “anyone may override this” is replaced without a word. Swapping in your own malloc is this pattern.
• Interception at run time. Unix’s LD_PRELOAD lets whatever loaded first win. A legitimate technique for diagnostic tools, and an accident when the same name is used by chance.

56.2 The first weapon — do not export (static)

The surest defence is not putting the name outside at all. Add static to a file-scope declaration and it has internal linkage (chapter 54): outside that translation unit it does not exist.

The discipline reduces to one line — make static the default and release only what goes in the header. There is a bonus: knowing “this name cannot be called from another file”, the compiler can optimise more aggressively (inlining, removing unused functions).

/* util.c */
int helper(int x) { … }         /* not in any header, yet external */

56.3 The second weapon — the prefix convention

For names that must be exported, the fence is built by hand. It is the universal practice of C libraries, and the larger the project the fewer the exceptions.

Four design rules can be read out of it.

1. Short, but unique. zlib’s z is convenient for being short and collides just as easily. Three or four characters is a safe choice today.
2. Put it on types and macros too. A prefix that covers only functions is half a fence — chapter 55 showed that type names and enumeration constants live in the same yard.
3. Split the layers by case. Combine the prefix with the habit of lowercase for functions and capitals for macros and constants, and a name alone reveals what it is.
4. Write it down. One line in the conventions document saying “our prefix is this” is cheaper than pointing it out a hundred times in review.

56.4 The third weapon — symbol visibility

A prefix is a convention people keep, so it leaks. There is one more layer that lets the build enforce it — the symbol visibility of a shared library.

The practice is to wrap it in one macro.

#if defined(_WIN32)
#  define MYLIB_API __declspec(dllexport)
#elif defined(__GNUC__)
#  define MYLIB_API __attribute__((visibility("default")))
#else
#  define MYLIB_API
#endif

MYLIB_API int mylib_open(const char *path);

Three effects: collisions grow rarer, loading gets faster (fewer symbols to resolve), and the boundary between the internal functions you may change and the public ones you may not is written into the code.

nm -g --defined-only mylib.o      # an object file
nm -D --defined-only libmy.so     # a shared library (dynamic symbols)
objdump -T libmy.so               # the same job with another tool

56.5 The fourth weapon — cut down the names themselves

Better than building a good fence is having few names to put outside. There is a pattern in which a module, instead of exporting twenty functions, exports a single struct holding function pointers.

/* 「모듈 하나 = 외부 심볼 하나」 — 접두어 규약과 함수 포인터 표.
   C 에는 사용자가 만드는 이름 공간이 없으니, 내보내는 이름을 줄이는 것이
   가장 확실한 방어다. */
#include <stdio.h>
#include <string.h>

/* ── 안쪽 구현은 전부 내부 연결(static) — 바깥 마당에 나가지 않는다 ── */
static int  buf_len;
static char buf[64];

static void impl_reset(void)                 { buf_len = 0; buf[0] = '\0'; }
static bool impl_push(const char *s)
{
    size_t n = strlen(s);
    if ((size_t)buf_len + n + 1 > sizeof buf) return false;   /* 잘림은 실패다(43장) */
    memcpy(buf + buf_len, s, n + 1);
    buf_len += (int)n;
    return true;
}
static const char *impl_text(void)           { return buf; }

/* ── 밖에 내보내는 것은 이것 하나 ──
   표(vtable) 하나에 접두어를 붙여 두면, 이 번역 단위가 링커에 내미는
   이름은 `textbuf` 단 하나다. 나머지 철자는 다른 파일과 부딪힐 수 없다. */
struct textbuf_api {
    void        (*reset)(void);
    bool        (*push)(const char *);
    const char *(*text)(void);
};

const struct textbuf_api textbuf = {
    .reset = impl_reset,
    .push  = impl_push,
    .text  = impl_text,
};

/* ── 쓰는 쪽 ── */
int main(void)
{
    textbuf.reset();
    puts("[this module exposes exactly one external name: `textbuf`]");
    printf("  push(\"hello \") -> %s\n", textbuf.push("hello ") ? "ok" : "failed");
    printf("  push(\"world\")  -> %s\n", textbuf.push("world")  ? "ok" : "failed");
    printf("  text()         -> \"%s\"\n", textbuf.text());

    char big[80];
    memset(big, 'A', sizeof big - 1);
    big[sizeof big - 1] = '\0';
    printf("  pushing a long string -> %s (truncation does not count as success)\n",
           textbuf.push(big) ? "ok" : "failed");

    puts("\n[the prefix convention - what large projects do]");
    puts("  sqlite3_ / curl_ / SSL_ / g_ / SDL_ ... the same prefix goes on types and macros");
    puts("  too. A prefix is a name space that C lacks, supplied by hand.");
    return 0;
}

[this module exposes exactly one external name: `textbuf`]
  push("hello ") -> ok
  push("world")  -> ok
  text()         -> "hello world"
  pushing a long string -> failed (truncation does not count as success)

[the prefix convention - what large projects do]
  sqlite3_ / curl_ / SSL_ / g_ / SDL_ ... the same prefix goes on types and macros
  too. A prefix is a name space that C lacks, supplied by hand.

The only name this translation unit hands the linker is textbuf (the nm measurement above). The calling side writes textbuf.push(...) with a dot — and the bonus of the pattern is that it reads like a language that has name spaces.

The price is worth stating plainly.

So the pattern belongs at boundaries — plugins, swappable back ends, test doubles. Not in an inner loop where speed matters.

56.6 How C++ solved this spot

C++ put “the user digs a yard” into the language. Here is as much as a C programmer needs, and accurately.

56.6.1 The syntax

namespace app {
    int  parse(const char *);
    namespace detail { int helper(int); }   // nested
}
namespace app::io { void flush(); }         // the C++17 shorthand

int x = app::parse("42");
int y = app::detail::helper(1);

The yard’s name goes in front of the name. It does the same job as C’s prefix convention; what differs is that the language enforces it and the tools understand it.

56.6.2 The anonymous namespace — the equivalent of C’s static

namespace { int hidden(int x) { return x; } }   // this translation unit only

Measuring shows the character of it.

The two have the same effect, but C++ prefers the anonymous namespace — unlike static it can be applied to types as well, and those can be passed as template arguments.

56.6.3 using namespace — the convenience and its price

using namespace std; tears down the yard’s fence on the spot. Handy in a short example; the conventions of practice mostly run like this.

56.6.4 ADL — looking in the yard of the argument

C++ has argument-dependent lookup: the yard where the argument’s type lives is searched as well, automatically.

namespace app { struct Buf {}; void print(const Buf &); }
app::Buf b;
print(b);        // app:: was not written, yet app::print is called — ADL

Convenient, and a surprising place too. Which function gets called depends on the type of the argument, so in code with many overloads a person struggles to follow it. C has no such lookup — one name is one function. Worth remembering as a spot where C’s simplicity pays.

56.6.5 Name mangling and extern "C"

C++ supports overloading, so the same spelling with different argument types is a different function. For that, the name the linker sees must carry type information — that is mangling.

Take _ZN3app1fEi apart and the yard name app (three characters), the function name f (one) and the argument type i are all in there. The name space is carved into the symbol.

So mixing C and C++ means saying “name this function by C’s rules”, and that is extern "C". The canonical pattern for a C header:

#ifdef __cplusplus
extern "C" {
#endif

int mylib_open(const char *path);

#ifdef __cplusplus
}
#endif

int register_thing(int class, int new);   /* C: fine. C++: an error */

56.7 Good habits — a summary

We know how to govern names. But chapter 55 went past the remark that “macros ignore all four name spaces” — meaning a layer that knows nothing of C replaces names. The next chapter opens that layer head on, and follows the formal steps by which source code becomes a program.