6 Basics [basic]

6.6 Program and linkage [basic.link]

1
#
A program consists of one or more translation units ([lex.separate]) 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 ([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 ([basic.scope.namespace]) 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 ([dcl.enum]), 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 ([basic.scope.block]) 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, neither is a name-independent declaration, 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]