skip to content

A C++ utility function defined in a header causes a multiple-definition link error; why, and which fixes are correct?

level: middleimportance: must knowfreq 72%

answer

  1. one definition per object file
  2. guards work per translation unit
  3. the one-definition rule's exception
  4. one entity, one address
  5. static gives every file a copy

basics

~20 s

Each .cpp file that includes the header compiles its own external definition, but a non-inline function may be defined once per program. Mark it inline or move the body into one .cpp file; static also links, but gives each file a private copy.

solid answer

~50 s

`#include` pastes the function's body into every `.cpp` file that includes the header, so each object file carries an external definition of `clamp_speed`. The one-definition rule allows a non-inline, non-template function only **one** definition in the whole program, and the linker reports the duplicates. Include guards do not help: they act within one translation unit. There are two real fixes. Mark it **`inline`**, which lets every translation unit carry an identical definition that is still one function with one address; member functions defined inside a class, and `constexpr` functions, are inline already. Or keep the declaration in the header and move the body into **one `.cpp` file**. `static` or an **unnamed namespace** also make the error disappear, but by giving every file its own private copy: separate addresses, separate function-local statics, duplicated code. A counter inside such a function counts per file.

code

plaintext · 5 lines
plaintext
duplicate symbol 'clamp_speed(double)' in:
    /private/var/folders/.../T/main-0ff8be.o
    /private/var/folders/.../T/drive-b13ab8.o
ld: 1 duplicate symbols
clang++: error: linker command failed with exit code 1 (use -v to see invocation)

go deeper

for a junior

Know that a function body in a header is compiled into every .cpp file that includes it, and that inline or moving the body into one .cpp file fixes the link error.

for a middle

Explain the one-definition rule's inline exception, why include guards cannot help across files, and why static silences the error by creating per-file copies with separate state.

for a senior

Spot the subtle consequences in review: a per-file static counter or cache, code bloat from internal-linkage helpers, and an inline function that calls a static one and so violates the ODR.

for a principal

Set the header rule for the codebase: which helpers may be inline in headers, which must live in a .cpp file for build-time reasons, and how a checker enforces it.

## Why the link fails A header is text that `#include` pastes into each source file. Suppose `clamp_util.h` contains: ```cpp #pragma once double clamp_speed(double v) { // defined in a header, not inline return v > 2.0 ? 2.0 : v; } ``` `drive.cpp` and `main.cpp` both include it. Each is compiled on its own, and each object file now contains a definition of `clamp_speed(double)` with **external linkage**, meaning a symbol the linker matches across files. The one-definition rule says a **non-inline, non-template** function or variable may be defined in only one translation unit of the program. When the linker sees two definitions of the same external symbol, it stops. Apple's linker says `duplicate symbol 'clamp_speed(double)' in:` and lists both object files; GNU's linker calls it a multiple definition. The `#pragma once` line, or an `#ifndef` guard, changes nothing here. Guards stop the text from appearing twice **within** one translation unit. Two different `.cpp` files each get one copy, legitimately, and that is precisely what produces two definitions. ## Fix 1: inline ```cpp inline double clamp_speed(double v) { return v > 2.0 ? 2.0 : v; } ``` `inline` is the one-definition rule's exception for functions. An inline function with external linkage may be defined in every translation unit that uses it, provided each definition is the same sequence of tokens with the same meaning. The standard is explicit that it is still **one function with one address**, and a `static` local variable or a type defined inside it is a single entity across the program. Typical toolchains make that work by emitting each copy as a mergeable definition and keeping one. `inline` is no longer mainly a request to substitute the body at the call site; the standard calls it a preference the implementation may ignore. Its guaranteed effect is the linkage permission. Several functions are inline without the keyword: - member functions **defined inside** a class body (outside a named module) - `constexpr` and `consteval` functions - function templates are not inline, but templates have their own allowance to be defined in several translation units ## Fix 2: move the body into one .cpp Leave `double clamp_speed(double v);` in the header and put the body in `clamp_util.cpp`. This is the right choice for anything long, or anything that pulls heavy includes along: a change to the body then recompiles one file instead of every includer. It also keeps the header free of whatever the body needs to include, and leaves the debugger and profiler exactly one copy to show. ## The tempting non-fix: static or an unnamed namespace `static double clamp_speed(double)` in the header, or wrapping it in `namespace { }`, also makes the error go away, because it gives the function **internal linkage**: every translation unit owns a private, unrelated function that happens to share the name. That is a different program: | Header function | Copies in the program | Function-local `static` | Address | |---|---|---|---| | non-inline, external | one per file, link error | — | — | | `inline` | one entity | shared | the same everywhere | | `static` or unnamed namespace | one per file | one per file | differs per file | | body moved to one `.cpp` | one | shared | the same everywhere | The difference shows as soon as the function keeps state. With `next_id()` containing `static int counter = 0; return ++counter;`, a call from `a.cpp` followed by a call from `main.cpp` printed `1 1` with `static` and `1 2` with `inline` on Apple clang 21. Internal linkage also duplicates the code in every object file, and an inline function elsewhere that calls the static one now refers to a different entity in each file, which is itself an ODR violation. ## Choosing 1. Short, hot, stateless helper: `inline` in the header. 2. Anything substantial or include-heavy: declaration in the header, body in one `.cpp`. 3. A helper only one file needs: keep it out of the header entirely and give it internal linkage in that `.cpp` file. 4. A function that `constexpr` code or a template in the header must call: its body has to be visible there, so it stays in the header as `inline` or `constexpr`, which implies inline.

  • Why does an include guard not prevent this link error?
    A guard only stops a header's text from appearing twice inside one translation unit. Each `.cpp` file is a separate translation unit that starts with no guard macro defined, so each gets one copy of the function's definition, legitimately, and the linker then sees one definition per object file.
  • Is a member function defined inside the class body affected?
    No. A member function defined inside its class definition is implicitly inline (outside a named module), so a class with in-class member bodies can sit in a header included everywhere. Moving that body out of the class into the header, as `double Robot::speed() const { ... }`, removes the implicit inline and brings the duplicate-definition error back unless you write `inline`.
  • Does inline force the compiler to substitute the body at each call?
    No. The standard says `inline` indicates a preference for inline substitution that the implementation is not required to follow; compilers decide by their own heuristics, keyword or not. The part that is guaranteed is the linkage rule: an inline function may be defined in several translation units and remains one function.

  • An include guard or #pragma once fixes multiple-definition link errors.
  • static is the standard fix because it hides the duplicate from the linker.
  • inline means the compiler must paste the body at every call.
  • An inline function gets a separate address in every file.
  • Member functions defined inside a class body must be marked inline.