[basic.link] (original) (raw)

6 Basics [basic]

6.6 Program and linkage [basic.link]

A translation unit consists of a sequence of declarations.

A name can haveexternal linkage,module linkage,internal linkage, orno linkage, as determined by the rules below.

[Note 1:

All declarations of an entity with a name with internal linkage appear in the same translation unit.

All declarations of an entity with module linkage are attached to the same module.

— _end note_]

The name of an entity that belongs to a namespace scopehas internal linkage if it is the name of

• a variable, variable template, function, or function template that is explicitly declared static; or
• a non-template variable of non-volatile const-qualified type, unless
  • it is declared in the purview of a module interface unit (outside the private-module-fragment, if any) or module partition, or
  • it is explicitly declared extern, or
  • it is inline, or
  • it was previously declared and the prior declaration did not have internal linkage; or
• a data member of an anonymous union.

[Note 2:

An instantiated variable template that has const-qualified type can have external or module linkage, even if not declared extern.

— _end note_]

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

• a variable; or
• a function; or
• 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
• 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
• an unnamed enumeration that has an enumerator as a name for linkage purposes ([dcl.enum]); or
• a template

has its linkage determined as follows:

• if the entity is a function or function template first declared in a friend declaration and that declaration is a definition and the enclosing class is defined within an export-declaration, the name has the same linkage, if any, as the name of the enclosing class ([class.friend]);
• otherwise,if the entity is a function or function template declared in a friend declaration and a corresponding non-friend declaration is reachable, the name has the linkage determined from that prior declaration,
• otherwise, if the enclosing namespace has internal linkage, the name has internal linkage;
• 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;
• otherwise, the name has external linkage.

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.

[Example 1: static void f();extern "C" void h();static int i = 0; void q() { extern void f(); extern void g(); extern void h(); int i; { extern void f(); extern int i; } }

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_]

Names not covered by these rules have no linkage.

Moreover, except as noted, a name declared at block scope has no linkage.

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

• they appear in the same translation unit, or
• they both declare names with module linkage and are attached to the same module, or
• they both declare names with external linkage.

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 4:

Such an H can appear only in a header unit.

— _end note_]

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(); int g();

Module interface of M:module;#include "decls.h" export module M;export using ::f; int g(); export int h(); export int k();

Other translation unit:import M;static int h(); int k(); — _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.

For any two declarations of an entity E:

• If one declares E to be a variable or function, the other shall declare E as one of the same type.
• If one declares E to be an enumerator, the other shall do so.
• If one declares E to be a namespace, the other shall do so.
• If one declares E to be a type, the other shall declare E to be a type of the same kind ([dcl.type.elab]).
• 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 5:
  The declarations can supply different default template arguments.
  — _end note_]
• 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.
• 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); void g(); void g(int); int g(); void h(); namespace h {} — _end example_]

A declaration D names an entity E if

• D contains a lambda-expression whose closure type is E,
• E is not a function or function template and D contains anid-expression,type-specifier,nested-name-specifier,template-name, orconcept-namedenoting E, or
• E is a function or function template andD contains an expression that names E ([basic.def.odr]) or an id-expressionthat refers to a set of overloads that contains E.
  [Note 7:
  Non-dependent names in an instantiated declaration do not refer to a set of overloads ([temp.res]).
  — _end note_]

A declaration is an exposureif it either names a TU-local entity (defined below), ignoring

• the function-bodyfor 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])),
• the initializerfor a variable or variable template (but not the variable's type),
• friend declarations in a class definition, and
• 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 8:

An inline function template can be an exposure even though certain explicit specializations of it would be usable in other translation units.

— _end note_]

An entity is TU-local if it is

• a type, function, variable, or template that
  • has a name with internal linkage, or
  • does not have a name with linkage and is declared, or introduced by a lambda-expression, within the definition of a TU-local entity,
• a type with no name that is defined outside aclass-specifier, function body, orinitializeror is introduced by a defining-type-specifierthat is used to declare only TU-local entities,
• a specialization of a TU-local template,
• a specialization of a template with any TU-local template argument, or
• a specialization of a template whose (possibly instantiated) declaration is an exposure.
  [Note 9:
  A specialization can be produced by implicit or explicit instantiation.
  — _end note_]

A value or object is TU-local if either

• it is, or is a pointer to, a TU-local function or the object associated with a TU-local variable, or
• 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.

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]).

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]).

[Example 4:

Translation unit #1:export module A;static void f() {} inline void it() { f(); } static inline void its() { f(); } template<int> void g() { its(); } template void g<0>();decltype(f) *fp; auto &fr = f; constexpr auto &fr2 = fr; constexpr static auto fp2 = fr; struct S { void (&ref)(); } s{f}; constexpr extern struct W { S &s; } wrap{s}; static auto x = []{f();}; auto x2 = x; int y = ([]{f();}(),0); int y2 = (x,0); namespace N { struct A {};void adl(A);static void adl(int);} void adl(double);inline void h(auto x) { adl(x); }

Translation unit #2:module A;void other() { g<0>(); g<1>(); h(N::A{}); h(0); adl(N::A{}); fr(); constexpr auto ptr = fr; } — _end example_]