6 Basics [basic]

6.6 Program and linkage [basic.link]

1
#
A program consists of one or more translation units linked together.
A translation unit consists of a sequence of declarations.
2
#
A name is said to have linkage when it can denote the same object, reference, function, type, template, namespace or value as a name introduced by a declaration in another scope:
  • (2.1)
    When a name has external linkage, the entity it denotes can be referred to by names from scopes of other translation units or from other scopes of the same translation unit.
  • (2.2)
    When a name has module linkage, the entity it denotes can be referred to by names from other scopes of the same module unit or from scopes of other module units of that same module.
  • (2.3)
    When a name has internal linkage, the entity it denotes can be referred to by names from other scopes in the same translation unit.
  • (2.4)
    When a name has no linkage, the entity it denotes cannot be referred to by names from other scopes.
3
#
A name having namespace scope has internal linkage if it is the name of
  • (3.1)
    a variable, variable template, function, or function template that is explicitly declared static; or
  • (3.2)
    a non-template variable of non-volatile const-qualified type, unless
    • (3.2.1)
      it is explicitly declared extern, or
    • (3.2.2)
      it is inline or exported, or
    • (3.2.3)
      it was previously declared and the prior declaration did not have internal linkage; or
  • (3.3)
    a data member of an anonymous union.
[Note 1:
An instantiated variable template that has const-qualified type can have external or module linkage, even if not declared extern.
— end note]
4
#
An unnamed namespace or a namespace declared directly or indirectly within an unnamed namespace has internal linkage.
All other namespaces have external linkage.
A name having namespace scope that has not been given internal linkage above and that is the name of
  • (4.1)
    a variable; or
  • (4.2)
    a function; or
  • (4.3)
    a named class ([class.pre]), or an unnamed class defined in a typedef declaration in which the class has the typedef name for linkage purposes ([dcl.typedef]); or
  • (4.4)
    a named enumeration, or an unnamed enumeration defined in a typedef declaration in which the enumeration has the typedef name for linkage purposes ([dcl.typedef]); or
  • (4.5)
    an unnamed enumeration that has an enumerator as a name for linkage purposes ([dcl.enum]); or
  • (4.6)
    a template
has its linkage determined as follows:
  • (4.7)
    if the enclosing namespace has internal linkage, the name has internal linkage;
  • (4.8)
    otherwise, if the declaration of the name is attached to a named module ([module.unit]) and is not exported ([module.interface]), the name has module linkage;
  • (4.9)
    otherwise, the name has external linkage.
5
#
In addition, a member function, static data member, a named class or enumeration of class scope, or an unnamed class or enumeration defined in a class-scope typedef declaration such that the class or enumeration has the typedef name for linkage purposes ([dcl.typedef]), has the same linkage, if any, as the name of the class of which it is a member.
6
#
The name of a function declared in block scope and the name of a variable declared by a block scope extern declaration have linkage.
If such a declaration is attached to a named module, the program is ill-formed.
If there is a visible declaration of an entity with linkage, ignoring entities declared outside the innermost enclosing namespace scope, such that the block scope declaration would be a (possibly ill-formed) redeclaration if the two declarations appeared in the same declarative region, the block scope declaration declares that same entity and receives the linkage of the previous declaration.
If there is more than one such matching entity, the program is ill-formed.
Otherwise, if no matching entity is found, the block scope entity receives external linkage.
If, within a translation unit, the same entity is declared with both internal and external linkage, the program is ill-formed.
[Example 1: static void f(); extern "C" void h(); static int i = 0; // #1 void g() { extern void f(); // internal linkage extern void h(); // C language linkage int i; // #2: i has no linkage { extern void f(); // internal linkage extern int i; // #3: external linkage, ill-formed } }
Without the declaration at line #2, the declaration at line #3 would link with the declaration at line #1.
Because the declaration with internal linkage is hidden, however, #3 is given external linkage, making the program ill-formed.
— end example]
7
#
When a block scope declaration of an entity with linkage is not found to refer to some other declaration, then that entity is a member of the innermost enclosing namespace.
However such a declaration does not introduce the member name in its namespace scope.
[Example 2: namespace X { void p() { q(); // error: q not yet declared extern void q(); // q is a member of namespace X } void middle() { q(); // error: q not yet declared } void q() { /* ... */ } // definition of X​::​q } void q() { /* ... */ } // some other, unrelated q — end example]
8
#
Names not covered by these rules have no linkage.
Moreover, except as noted, a name declared at block scope has no linkage.
9
#
Two names that are the same ([basic.pre]) and that are declared in different scopes shall denote the same variable, function, type, template or namespace if
  • (9.1)
    both names have external or module linkage and are declared in declarations attached to the same module, or else both names have internal linkage and are declared in the same translation unit; and
  • (9.2)
    both names refer to members of the same namespace or to members, not by inheritance, of the same class; and
  • (9.3)
    when both names denote functions or function templates, the signatures ([defns.signature], [defns.signature.templ]) are the same.
If multiple declarations of the same name with external linkage would declare the same entity except that they are attached to different modules, the program is ill-formed; no diagnostic is required.
[Note 2:
using-declarations, typedef declarations, and alias-declarations do not declare entities, but merely introduce synonyms.
Similarly, using-directives do not declare entities.
Enumerators do not have linkage, but might serve as the name of an enumeration with linkage ([dcl.enum]).
— end note]
10
#
If a declaration would redeclare a reachable declaration attached to a different module, the program is ill-formed.
[Example 3:

"decls.h":int f(); // #1, attached to the global module int g(); // #2, attached to the global module

Module interface of M:module; #include "decls.h" export module M; export using ::f; // OK: does not declare an entity, exports #1 int g(); // error: matches #2, but attached to M export int h(); // #3 export int k(); // #4

Other translation unit:import M; static int h(); // error: matches #3 int k(); // error: matches #4 — end example]

As a consequence of these rules, all declarations of an entity are attached to the same module; the entity is said to be attached to that module.
11
#
After all adjustments of types (during which typedefs are replaced by their definitions), the types specified by all declarations referring to a given variable or function shall be identical, except that declarations for an array object can specify array types that differ by the presence or absence of a major array bound ([dcl.array]).
A violation of this rule on type identity does not require a diagnostic.
12
#
[Note 3:
Linkage to non-C++ declarations can be achieved using a linkage-specification ([dcl.link]).
— end note]
13
#
A declaration D names an entity E if
14
#
A declaration is an exposure if it either names a TU-local entity (defined below), ignoring
  • (14.1)
    the function-body for a non-inline function or function template (but not the deduced return type for a (possibly instantiated) definition of a function with a declared return type that uses a placeholder type ([dcl.spec.auto])),
  • (14.2)
    the initializer for a variable or variable template (but not the variable's type),
  • (14.3)
    friend declarations in a class definition, and
  • (14.4)
    any reference to a non-volatile const object or reference with internal or no linkage initialized with a constant expression that is not an odr-use ([basic.def.odr]),
or defines a constexpr variable initialized to a TU-local value (defined below).
[Note 5:
An inline function template can be an exposure even though explicit specializations of it might be usable in other translation units.
— end note]
15
#
An entity is TU-local if it is
  • (15.1)
    a type, function, variable, or template that
    • (15.1.1)
      has a name with internal linkage, or
    • (15.1.2)
      does not have a name with linkage and is declared, or introduced by a lambda-expression, within the definition of a TU-local entity,
  • (15.2)
    a type with no name that is defined outside a class-specifier, function body, or initializer or is introduced by a defining-type-specifier that is used to declare only TU-local entities,
  • (15.3)
    a specialization of a TU-local template,
  • (15.4)
    a specialization of a template with any TU-local template argument, or
  • (15.5)
    a specialization of a template whose (possibly instantiated) declaration is an exposure.
    [Note 6:
    The specialization might have been implicitly or explicitly instantiated.
    — end note]
16
#
A value or object is TU-local if either
  • (16.1)
    it is, or is a pointer to, a TU-local function or the object associated with a TU-local variable, or
  • (16.2)
    it is an object of class or array type and any of its subobjects or any of the objects or functions to which its non-static data members of reference type refer is TU-local and is usable in constant expressions.
17
#
If a (possibly instantiated) declaration of, or a deduction guide for, a non-TU-local entity in a module interface unit (outside the private-module-fragment, if any) or module partition ([module.unit]) is an exposure, the program is ill-formed.
Such a declaration in any other context is deprecated ([depr.local]).
18
#
If a declaration that appears in one translation unit names a TU-local entity declared in another translation unit that is not a header unit, the program is ill-formed.
A declaration instantiated for a template specialization ([temp.spec]) appears at the point of instantiation of the specialization ([temp.point]).
19
#
[Example 4:

Translation unit #1:export module A; static void f() {} inline void it() { f(); } // error: is an exposure of f static inline void its() { f(); } // OK template<int> void g() { its(); } // OK template void g<0>(); decltype(f) *fp; // error: f (though not its type) is TU-local auto &fr = f; // OK constexpr auto &fr2 = fr; // error: is an exposure of f constexpr static auto fp2 = fr; // OK struct S { void (&ref)(); } s{f}; // OK, value is TU-local constexpr extern struct W { S &s; } wrap{s}; // OK, value is not TU-local static auto x = []{f();}; // OK auto x2 = x; // error: the closure type is TU-local int y = ([]{f();}(),0); // error: the closure type is not TU-local int y2 = (x,0); // OK namespace N { struct A {}; void adl(A); static void adl(int); } void adl(double); inline void h(auto x) { adl(x); } // OK, but a specialization might be an exposure

Translation unit #2:module A; void other() { g<0>(); // OK, specialization is explicitly instantiated g<1>(); // error: instantiation uses TU-local its h(N::A{}); // error: overload set contains TU-local N​::​adl(int) h(0); // OK, calls adl(double) adl(N::A{}); // OK; N​::​adl(int) not found, calls N​::​adl(N​::​A) fr(); // OK, calls f constexpr auto ptr = fr; // error: fr is not usable in constant expressions here } — end example]