YOUR C LEARNING COMPANION

Find your next idea.

Learning path
Building programsChapter 42 of 73

Translation units and linkage

Connect separate source contexts through compatible declarations, internal and external linkage, and consistent definitions.

5 min readIntermediateC17 baseline
Offline reading
In this chapter8 sections

Each source file is translated in its own context. Linkage lets selected declarations refer to the same entity across those contexts. We will distinguish sharing a declaration, defining an object, and limiting a name to one translation unit.

1. One translation unit has its own declarations

A translation unit is the result of preprocessing a source file together with included material, after excluded groups are removed. A header can contribute declarations to many translation units. A macro defined while preprocessing one .c file does not automatically exist while preprocessing another. Build flags may intentionally supply the same macro to both, but that is a separate configuration action.

Shared declaration, separate translation
visits.c + visits.h
Defines the counter and operation
main.c + visits.h
Declares and uses that interface
The header is processed in each context; linkage connects names denoting the same external entity.

2. Declare the interface; define its objects and functions

C17 · project file · visits.h
#ifndef CODEDILE_VISITS_H
#define CODEDILE_VISITS_H

extern unsigned codedile_visits;
void codedile_visit(void);

#endif

extern unsigned codedile_visits; declares an object without providing a definition here. The function declaration supplies a prototype. Every declaration referring to the same object or function must have a compatible type. Use the shared header in implementations and callers; repeating a guessed declaration by hand invites mismatches that a traditional linker may not detect.

C17 · project file · visits.c
#include "visits.h"
#include <limits.h>

unsigned codedile_visits = 0;

static unsigned next_count(unsigned current)
{
    return current == UINT_MAX ? current : current + 1U;
}

void codedile_visit(void)
{
    codedile_visits = next_count(codedile_visits);
}

The initialized file-scope object is a definition. The function body is a definition too. extern does not always mean “declaration only”: a file-scope declaration such as extern int value = 3; is a definition. The small helper prevents wraparound by saturating at UINT_MAX. The shared global is exposed here to illustrate linkage; many application interfaces instead keep mutable state private.

C17 · project file · main.c
#include "visits.h"
#include <assert.h>

int main(void)
{
    assert(codedile_visits == 0);
    codedile_visit();
    assert(codedile_visits == 1);
    return 0;
}

3. Internal, external, and no linkage answer name identity

CategoryMeaning
External linkageCompatible declarations can denote the same entity across translation units.
Internal linkageDeclarations of that identifier within one translation unit denote its local entity.
No linkageThe declaration identifies an entity without linkage-based identity with another declaration.

At file scope, static on an object or function gives its identifier internal linkage. Another translation unit can use the same spelling for a different internal entity. A block-scope automatic variable normally has no linkage. A block-scope static object also has no linkage, while its storage duration is static. Linkage, scope, and storage duration therefore cannot be inferred from one word in isolation.

Internal linkage restricts external name linkage, not every possible access. A static function can still be called elsewhere through a function pointer deliberately returned by the module; a private object can be accessed through a deliberately exposed pointer. Avoid mixing internal and external linkage for the same identifier in one translation unit. These rules establish program meaning, not a security boundary.

4. Tentative definitions are a within-unit rule

Complete C17 program
#include <assert.h>

int codedile_total;
int codedile_total;

int main(void)
{
    assert(codedile_total == 0);
    return 0;
}

These two compatible file-scope tentative definitions in the same translation unit result in one zero-initialized definition when no full definition appears there. Moving a tentative definition into a header included by several source files is a different situation: each translation unit can supply a definition. Do not rely on a linker’s legacy common-symbol merging to make such a design portable.

5. One external entity needs a consistent program definition

The next deliberately invalid project gives the same externally linked object two initialized definitions. The checked GCC build rejects it at link time. C’s program-level definition requirements apply even when a tool happens to accept a bad program; the exact diagnostic is not a standard C promise. These files are shown only to explain the failure.

C17 · intentional invalid project · first.c
int codedile_shared = 1;
C17 · intentional invalid project · second.c
int codedile_shared = 2;
C17 · intentional invalid project · main.c
extern int codedile_shared;
int main(void) { return codedile_shared == 1 ? 0 : 1; }

For an externally linked identifier used in an expression, C normally requires exactly one external definition for the program; exceptions include specified unevaluated uses. If it is not used that way, there must still be no more than one. A successful link cannot establish all type, lifetime, bounds, or ownership contracts.

Primary references and further reading

Before you move on

  • Each translation unit has its own preprocessing and declaration context.
  • Linkage connects declarations referring to the same entity across appropriate contexts.
  • Shared interfaces require compatible declarations and the correct program-level definitions.
Keep these ideas separate
Internal linkage / Block scope
Internal linkage concerns entity identity across declarations; block scope concerns where a name is visible.
Explain it in your own words

How can two files both translate yet disagree about the interface of the entity they try to share?

Optional: say it aloud or keep a note. You can continue whenever you are ready.

Check your understanding

Optional. Answers are not saved or sent, and reading stays unrestricted.

Do two file-scope static objects in different translation units have to be the same object because their names match?
Read the explanation for every choice
  1. No. Their identifiers have internal linkage in their respective translation units.

    ✓ Correct reasoning. Matching spelling does not establish shared external identity for internal-linkage identifiers.

  2. Yes, every matching spelling names one global object.

    Scope and linkage rules matter; matching text alone is insufficient.

  3. static always means block scope.

    static can appear in file-scope declarations too; scope depends on declaration location.

C17

Ready for the next idea?

Mark this chapter as read whenever you feel ready.

CHAPTER 42 / 73

In this chapter

Translation units and linkage

Search all 73 chapters in both languages.EN + HG

Try “pointer”, “why int”, or “undefined behavior”.

Concepts connect. Follow your curiosity.↑ ↓ to explore · Enter to open
MAKE YOURSELF COMFORTABLE

Your reading space

Appearance

A clear canvas with balanced contrast.

Text size

100%
AA

Reading tools

Your data stays in this browser

Export a backup before changing browsers or replacing an older version of the reader.

YOUR PERSONAL MARGINS

My notebook

Saved on this device
A LITTLE CLARITY

The glossary

A starting meaning, then a chapter to go deeper.

A QUICK DEFINITION

A little clarity

Read the full explanation →

A thought worth keeping