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
#
The name of an entity that belongs to a 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 declared in the purview of a module interface unit (outside the private-module-fragment, if any) or module partition, or
    • (3.2.2)
      it is explicitly declared extern, or
    • (3.2.3)
      it is inline, or
    • (3.2.4)
      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.
The name of an entity that belongs to a 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, a static data member, a named class or enumeration that inhabits a class scope, or an unnamed class or enumeration defined in a typedef declaration that inhabits a class scope 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
#
[Example 1: static void f(); extern "C" void h(); static int i = 0; // #1 void q() { extern void f(); // internal linkage extern void g(); // ​::​g, external linkage extern void h(); // C language linkage int i; // #2: i has no linkage { extern void f(); // internal linkage extern int i; // #3: internal linkage } }
Even though the declaration at line #2 hides the declaration at line #1, the declaration at line #3 still redeclares #1 and receives internal linkage.
— end example]
7
#
Names not covered by these rules have no linkage.
Moreover, except as noted, a name declared at block scope has no linkage.
8
#
Two declarations of entities declare the same entity if, considering declarations of unnamed types to introduce their names for linkage purposes, if any ([dcl.typedef], [dcl.enum]), they correspond ([basic.scope.scope]), have the same target scope that is not a function or template parameter scope, and either
  • (8.1)
    they appear in the same translation unit, or
  • (8.2)
    they both declare names with module linkage and are attached to the same module, or
  • (8.3)
    they both declare names with external linkage.
[Note 2: 
There are other circumstances in which declarations declare the same entity ([dcl.link], [temp.type], [temp.spec.partial]).
— end note]
9
#
If a declaration H that declares a name with internal linkage precedes a declaration D in another translation unit U and would declare the same entity as D if it appeared in U, the program is ill-formed.
[Note 3: 
Such an H can appear only in a header unit.
— end note]
10
#
If two declarations of an entity are attached to different modules, the program is ill-formed; no diagnostic is required if neither is reachable from the other.
[Example 2: 

"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
#
For any two declarations of an entity E:
  • (11.1)
    If one declares E to be a variable or function, the other shall declare E as one of the same type.
  • (11.2)
    If one declares E to be an enumerator, the other shall do so.
  • (11.3)
    If one declares E to be a namespace, the other shall do so.
  • (11.4)
    If one declares E to be a type, the other shall declare E to be a type of the same kind ([dcl.type.elab]).
  • (11.5)
    If one declares E to be a class template, the other shall do so with the same kind and an equivalent template-head ([temp.over.link]).
    [Note 4: 
    The declarations can supply different default template arguments.
    — end note]
  • (11.6)
    If one declares E to be a function template or a (partial specialization of a) variable template, the other shall declare E to be one with an equivalent template-head and type.
  • (11.7)
    If one declares E to be an alias template, the other shall declare E to be one with an equivalent template-head and defining-type-id.
  • (11.8)
    If one declares E to be a concept, the other shall do so.
Types are compared after all adjustments of types (during which typedefs ([dcl.typedef]) are replaced by their definitions); declarations for an array object can specify array types that differ by the presence or absence of a major array bound ([dcl.array]).
No diagnostic is required if neither declaration is reachable from the other.
[Example 3: int f(int x, int x); // error: different entities for x void g(); // #1 void g(int); // OK, different entity from #1 int g(); // error: same entity as #1 with different type void h(); // #2 namespace h {} // error: same entity as #2, but not a function — end example]
12
#
[Note 5: 
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 7: 
An inline function template can be an exposure even though certain explicit specializations of it would 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 8: 
    A specialization can be produced by implicit or explicit instantiation.
    — 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 certain specializations are exposures

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]