Inline functions and what inline really promises

Understanding Inline functions and what inline really promises

The inline keyword in C does two things that look unrelated, and only one of them is about speed. It asks the compiler to consider substituting the function body at the call site, which the compiler is free to refuse for any reason it likes: optimization is off, the address is taken, the body is recursive or simply too big. The part that actually bites is the second: in C99 and later, if every file-scope declaration of a function in a translation unit says inline and none says extern, then that translation unit's definition is an inline definition and does not provide the external definition of the function.

So any call the compiler declined to substitute becomes a call to a symbol that must be defined somewhere else in the program. If nothing defines it you get an undefined reference, typically at -O0 where nothing is inlined, in a project that linked fine at -O2. The fix is to give exactly one translation unit a file-scope declaration that is not inline-without-extern; the usual spelling is extern inline int clampi(int, int, int); in one .c file, which promotes that file's definition to the program's single external definition.

The alternative is static inline, which is why headers are full of it: internal linkage means each including file gets its own private definition, so there is never a missing symbol and never a question about which body ran, at the cost of a possible copy and a distinct address per translation unit. One more rule follows naturally from this picture: an inline definition with external linkage may not define a modifiable static object and may not reference an identifier with internal linkage, because the program can hold several inline copies plus one external copy that could not share such state. For the same reason, if a header body and an out-of-line body ever disagree, which one a given call uses is unspecified.

#include <stdio.h>

/* Inline definition: a candidate for substitution in this file.
   By itself it does NOT provide the external definition of clampi. */
inline int clampi(int v, int lo, int hi)
{
    return v < lo ? lo : (v > hi ? hi : v);
}

/* One non-inline declaration in this translation unit promotes the
   definition above to the program's external definition, so the linker
   has a symbol even when nothing is substituted (as at -O0). */
extern int clampi(int v, int lo, int hi);

int main(void)
{
    int (*fp)(int, int, int) = clampi;  /* taking an address needs a real copy */

    printf("clamped: %d %d %d\n", clampi(-5, 0, 10), clampi(7, 0, 10), clampi(42, 0, 10));
    printf("through pointer: %d\n", fp(99, 0, 10));
    return 0;
}

Worked examples

#include <stdio.h>

/* Internal linkage: this file always has a body available, so no
   external definition of next_pow2 is ever required. */
static inline unsigned next_pow2(unsigned n)
{
    unsigned p = 1;
    while (p < n)
        p <<= 1;
    return p;
}

static inline unsigned tally(unsigned n)
{
    static unsigned calls = 0;   /* legal because the function is static */
    calls++;
    return calls * n;
}

int main(void)
{
    printf("%u %u %u\n", next_pow2(1), next_pow2(17), next_pow2(1000));
    printf("%u ", tally(10));
    printf("%u ", tally(10));
    printf("%u\n", tally(10));
    return 0;
}

#include <stdio.h>

inline double area(double r) { return 3.14159265358979 * r * r; }
extern double area(double r);   /* emit the external definition here */

typedef double (*fn)(double);

int main(void)
{
    fn a = area;
    fn b = &area;

    printf("same address: %s\n", a == b ? "yes" : "no");
    printf("direct   %.4f\n", area(2.0));
    printf("indirect %.4f\n", a(2.0));
    return 0;
}

Important notes

Common mistakes

Try it yourself