CertC++-DCL60¶

Obey the one-definition rule

Required inputs: IR

Nontrivial C++ programs are generally divided into multiple translation units that are later linked together to form an executable. To support such a model, C++ restricts named object definitions to ensure that linking will behave deterministically by requiring a single definition for an object across all translation units. This model is called the one-definition rule (ODR), which is defined by the C++ Standard, [basic.def.odr], in paragraph 4 [ ISO/IEC 14882-2014]:

Every program shall contain exactly one definition of every non-inline function or variable that is odr-used in that program; no diagnostic required. The definition can appear explicitly in the program, it can be found in the standard or a user-defined library, or (when appropriate) it is implicitly-defined. An inline function shall be defined in every translation unit in which it is odr-used.

The most common approach to multitranslation unit compilation involves declarations residing in a header file that is subsequently made available to a source file via #include. These declarations are often also definitions, such as class and function template definitions. This approach is allowed by an exception defined in paragraph 6, which, in part, states the following:

There can be more than one definition of a class type, enumeration type, inline function with external linkage, class template, non-static function template, static data member of a class template, member function of a class template, or template specialization for which some template parameters are not specified in a program provided that each definition appears in a different translation unit, and provided the definitions satisfy the following requirements. Given such an entity named D defined in more than one translation unit....

If the definitions of D satisfy all these requirements, then the program shall behave as if there were a single definition of D. If the definitions of D do not satisfy these requirements, then the behavior is undefined.

The requirements specified by paragraph 6 essentially state that that two definitions must be identical (not simply equivalent). Consequently, a definition introduced in two separate translation units by an #include directive generally will not violate the ODR because the definitions are identical in both translation units.

However, it is possible to violate the ODR of a definition introduced via #include using block language linkage specifications, vendor-specific language extensions, and so on. A more likely scenario for ODR violations is that accidental definitions of differing objects will exist in different translation units.

Do not violate the one-definition rule; violations result in undefined behavior.

Noncompliant Code Example

In this noncompliant code example, two different translation units define a class of the same name with differing definitions. Although the two definitions are functionally equivalent (they both define a class named S with a single, public, nonstatic data member int a), they are not defined using the same sequence of tokens. This code example violates the ODR and results in undefined behavior.

// a.cpp
struct S {
  int a;
};
 
// b.cpp
class S {
public:
  int a;
};

Compliant Solution

The correct mitigation depends on programmer intent. If the programmer intends for the same class definition to be visible in both translation units because of common usage, the solution is to use a header file to introduce the object into both translation units, as shown in this compliant solution.

// S.h
struct S {
  int a;
};
 
// a.cpp
#include "S.h"

// b.cpp
#include "S.h"

Compliant Solution

If the ODR violation was a result of accidental name collision, the best mitigation solution is to ensure that both class definitions are unique, as in this compliant solution.

// a.cpp
namespace {
struct S {
  int a;
};
}

// b.cpp
namespace {
class S {
public:
  int a;
};
}

Alternatively, the classes could be given distinct names in each translation unit to avoid violating the ODR.

Noncompliant Code Example (Microsoft Visual Studio)

In this noncompliant code example, a class definition is introduced into two translation units using #include. However, one of the translation units uses an implementation-defined #pragma that is supported by Microsoft Visual Studio to specify structure field alignment requirements. Consequently, the two class definitions may have differing layouts in each translation unit, which is a violation of the ODR.

// s.h
struct S {
  char c;
  int a;
};
 
void init_s(S &s);
 
// s.cpp
#include "s.h"
 
void init_s(S &s); {
  s.c = 'a';
  s.a = 12;
}
 
// a.cpp
#pragma pack(push, 1)
#include "s.h"
#pragma pack(pop)
 
void f() {
  S s;
  init_s(s);
}

Implementation Details

It is possible for the preceding noncompliant code example to result in a.cpp allocating space for an object with a different size than expected by init_s() in s.cpp. When translating s.cpp, the layout of the structure may include padding bytes between the c and a data members. When translating a.cpp, the layout of the structure may remove those padding bytes as a result of the #pragma pack directive, so the object passed to init_s() may be smaller than expected. Consequently, when init_s() initializes the data members of s, it may result in a buffer overrun.

For more information on the behavior of #pragma pack, see the vendor documentation for your implementation, such as Microsoft Visual Studio or GCC.

Compliant Solution

In this compliant solution, the implementation-defined structure member-alignment directive is removed, ensuring that all definitions of S comply with the ODR.

// s.h
struct S {
  char c;
  int a;
};

void init_s(S &s);

// s.cpp
#include "s.h"

void init_s(S &s); {
  s.c = 'a';
  s.a = 12;
}

// a.cpp
#include "s.h"

void f() {
  S s;
  init_s(s);
}

Noncompliant Code Example

In this noncompliant code example, the constant object n has internal linkage but is odr-used within f(), which has external linkage. Because f() is declared as an inline function, the definition of f() must be identical in all translation units. However, each translation unit has a unique instance of n, resulting in a violation of the ODR.

const int n = 42;
 
int g(const int &lhs, const int &rhs);

inline int f(int k) {
  return g(k, n);
}

Compliant Solution

A compliant solution must change one of three factors: (1) it must not odr-use n within f(), (2) it must declare n such that it has external linkage, or (3) it must not use an inline definition of f().

If circumstances allow modification of the signature of g() to accept parameters by value instead of by reference, then n will not be odr-used within f() because n would then qualify as a constant expression. This solution is compliant but it is not ideal. It may not be possible (or desirable) to modify the signature of g(), such as if g() represented std::max() from <algorithm>. Also, because of the differing linkage used by n and f(), accidental violations of the ODR are still likely if the definition of f() is modified to odr-use n.

const int n = 42;
 
int g(int lhs, int rhs);

inline int f(int k) {
  return g(k, n);
}

Compliant Solution

In this compliant solution, the constant object n is replaced with an enumerator of the same name. Named enumerations defined at namespace scope have the same linkage as the namespace they are contained in. The global namespace has external linkage, so the definition of the named enumeration and its contained enumerators also have external linkage. Although less aesthetically pleasing, this compliant solution does not suffer from the same maintenance burdens of the previous code because n and f() have the same linkage.

enum Constants {
  N = 42
};

int g(const int &lhs, const int &rhs);

inline int f(int k) {
  return g(k, N);
}

Risk Assessment

Violating the ODR causes undefined behavior, which can result in exploits as well as denial-of-service attacks. As shown in "Support for Whole-Program Analysis and the Verification of the One-Definition Rule in C++" [ Quinlan 06], failing to enforce the ODR enables a virtual function pointer attack known as the VPTR exploit. In this exploit, an object's virtual function table is corrupted so that calling a virtual function on the object results in malicious code being executed. See the paper by Quinlan and colleagues for more details. However, note that to introduce the malicious class, the attacker must have access to the system building the code.

Rule	Severity	Likelihood	Remediation Cost	Priority	Level
DCL60-CPP	High	Unlikely	High	P3	L3

Bibliography

[ ISO/IEC 14882-2014]	Subclause 3.2, "One Definition Rule"
[ Quinlan 2006]

Excerpt from SEI CERT C++ Coding Standard [https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/declarations-and-initialization-dcl/dcl60-cpp], Copyright (C) 1995-2026 Carnegie Mellon University. See section 9.4. "3rd-Party Licenses" in the documentation for full details.

Possible Messages

Key	Text	Severity	Disabled
bad_odr_use_in_function	Inline functions should not odr-use objects with internal linkage.	None	False
bad_odr_use_in_initializer	Field initializers should not odr-use objects with internal linkage.	None	False
bad_odr_use_in_variable	Inline variables should not odr-use objects with internal linkage.	None	False
class_struct_difference	{}	None	False
different_enumerators	{}	None	False
extra_field	ODR violation for {defn}; {kind} field {field} at {field_pos} compared to definition at {pos}	None	False
extra_method_definition	ODR violation for {defn}; extra method {method} compared to definition at {pos}{check}	None	False
general_odr_violation	{}	None	False
incompatible_field_name	ODR violation for {defn} compared to definition at {pos}; field {field} at {pos1} does not match field name {field2} at {pos2}{check}	None	False
incompatible_field_type	ODR violation for {defn} compared to definition at {pos}; field {field} has incompatible type {type1} at {pos1} compared to type {type2} at {pos2}{check}	None	False
incompatible_method_redefinition	ODR violation for {defn} compared to definition at {pos}; incompatible signature {method} versus {versus}{check}	None	False

Options¶

This rule shares the following common options: exclude_in_macros, exclude_messages_in_system_headers, excludes, extend_exclude_to_macro_invocations, includes, justification_checker, languages, post_processing, provider, report_at, severity
The following places define options that affect this rule: Stylechecks, Analysis-GlobalOptions

reported_messages¶

reported_messages

Type: set[LinkerMessage] | None

Default: {'Field_Offset_Mismatch', 'Type_Alignment_Mismatch', 'Type_Size_Mismatch'}

If provided, only the listed message types are reported. If set to None, all message types are reported.

reported_severities¶

reported_severities

Type: set[LinkerSeverity]

Default: {'error', 'remark', 'warning'}

List of severities to display.

use_error_number¶

use_error_number : bool = False

If enabled, the error number from the linker is used, else this rule's error number is used.

use_rule_severity¶

use_rule_severity : bool = True

If enabled, this rule's severity is used, else the severity from the linker is used.

Option Types¶

These types are used by options listed above:

LinkerMessage¶

An enumeration.

Adding_Library
Reference_To_Library
Cannot_Open_Error
Cannot_Open_Warning
Cannot_Open_Ignored
No_IR_File
Old_IR_File_Error
Old_IR_File_Warning
Cylic_PCH
Runtimelib_PCH
Runtimelib_Archive
Missing_PCH_Error
Missing_PCH_Warning
PCH_Without_Clients
Basepath_Mismatch
Compiler_Mismatch
General_ODR_Violation
ODR_Violation_In_Fields
ODR_Violation_In_Field_Types
Tolerated_Type_Difference
ODR_Violation_In_Enumerators
Implicit_Func_Decl_Return_Type_Mismatch
Type_Size_Mismatch
Type_Alignment_Mismatch
Field_Offset_Mismatch
Multiple_Definition
Unresolved_Declaration
General_Field_Remark
General_Field_Warning
Missing_Main
Multiple_Main
Template_Specialization_Vs_Instance
Class_Struct_Mismatch
Unused_Archive_Member
Unused_Library
Empty_Linker_Result
User_System_Include_Mismatch
Different_Symbols

LinkerSeverity¶

An enumeration.

disabled
progress
remark
warning
error

Axivion Suite 7.12.0

Navigation

CertC++-DCL60¶

Noncompliant Code Example

Compliant Solution

Compliant Solution

Noncompliant Code Example (Microsoft Visual Studio)

Implementation Details

Compliant Solution

Noncompliant Code Example

Compliant Solution

Compliant Solution

Risk Assessment

Bibliography

Options¶

reported_messages¶

reported_severities¶

use_error_number¶

use_rule_severity¶

Option Types¶

LinkerMessage¶

LinkerSeverity¶