Internal versus external linkage with static and extern

Understanding Internal versus external linkage with static and extern

The compiler processes one translation unit at a time and writes an object file containing a symbol table. Only names with external linkage are offered to the linker as candidates for matching across object files; a name with internal linkage is recorded as a local symbol that nothing outside its own translation unit can bind to. Identifiers declared inside a block have no linkage at all, so two functions may each have a variable called i with no relationship between them. Linkage is therefore a question about names and the linker, not about where bytes live or how long they live.

At file scope, an identifier declared without a storage-class specifier gets external linkage, which is why a stray int config; in a header becomes a definition in every file that includes it. Writing static at file scope switches that identifier to internal linkage, so the same spelling in another .c file names a completely different object or function. Writing extern on a declaration says the opposite: this name has external linkage and its single definition lives somewhere the linker will find, so no storage is reserved here. Function declarations already default to external linkage, which is why extern on a prototype changes nothing.

A useful mental model is that each .c file has a public surface and a private interior, and static is the tool that shrinks the surface. Hiding a name does not hide the memory: a static object's address can still be handed to another file through a non-static function, and that file can read and write through the pointer even though it cannot spell the name. The two classic linker messages map straight onto this model: undefined reference means something was declared external but no external definition exists, often because the definition was accidentally marked static, and multiple definition means two translation units each supplied an external definition of the same name.

#include <stdio.h>

/* No storage class at file scope: external linkage, visible to the linker. */
int total = 0;

/* static at file scope: internal linkage, private to this translation unit. */
static int calls = 0;

/* A static function: other .c files cannot call it even if they declare it. */
static void bump(int amount)
{
    calls++;
    total += amount;
}

/* The exported entry point: this is the only name other files should use. */
void add_twice(int amount)
{
    bump(amount);
    bump(amount);
}

int main(void)
{
    extern int total; /* a declaration, not a new object: same total as above */

    add_twice(5);
    add_twice(1);

    printf("total = %d\n", total);
    printf("bump called %d times\n", calls);
    return 0;
}

Worked examples

#include <stdio.h>

extern int limit;   /* declaration: promises a definition exists */
static int scale;   /* definition, internal linkage, zero initialised */

static int scaled(int v)
{
    return v * scale;
}

int limit = 40;     /* the definition that satisfies the declaration above */

int main(void)
{
    scale = 3;
    printf("scaled(10) = %d\n", scaled(10));
    printf("limit = %d\n", limit);
    printf("clamped = %d\n", scaled(10) > limit ? limit : scaled(10));
    return 0;
}

#include <stdio.h>

static int registry_size = 0; /* internal linkage */
extern int registry_size;     /* same object, linkage unchanged */

static const char *names[4];

int register_name(const char *name)
{
    if (registry_size == 4)
        return -1;
    names[registry_size] = name;
    return registry_size++;
}

int main(void)
{
    printf("slot %d\n", register_name("clk"));
    printf("slot %d\n", register_name("rst"));
    printf("names[0] = %s\n", names[0]);
    printf("registry_size = %d\n", registry_size);
    return 0;
}

#include <stdio.h>

static int file_scope_calls = 0; /* internal linkage, one per .c file */

int next_id(void)
{
    static int local_counter = 0; /* no linkage at all: name is local */
    file_scope_calls++;
    return ++local_counter;
}

int main(void)
{
    printf("id %d\n", next_id());
    printf("id %d\n", next_id());
    printf("id %d\n", next_id());
    printf("calls: %d\n", file_scope_calls);
    return 0;
}

Important notes

Common mistakes

Try it yourself