DCL00-C. Const-qualify immutable objects

Immutable objects should be const-qualified. Enforcing object immutability using const-qualification helps ensure the correctness and security of applications. ISO/IEC PDTR 24772, for example, recommends labeling parameters as constant to avoid the unintentional modification of function arguments [[ISO/IEC PDTR 24772]]. STR05-C. Use pointers to const when referring to string literals describes a specialized case of this recommendation.

Adding const qualification may propagate through a program; as you add const qualifiers, still more become necessary. This phenomenon is sometimes called const poisoning, which can frequently lead to violations of EXP05-C. Do not cast away a const qualification. While const qualification is a good idea, the costs may outweigh the value in the remediation of existing code.

Macros, or an enumeration constant, may also be used instead of a const-qualified object. DCL06-C. Use meaningful symbolic constants to represent literal values in program logic describes the relative merits of using const-qualified objects, enumeration constants, and object-like macros. However, adding a const qualifier to an existing variable is a better first step than replacing the variable with an enumeration constant or macro, because the compiler will issue warnings on any code that changes your const-qualified variable. Once you have verified that a const-qualified variable is not changed by any code, you may consider changing it to an enumeration constant or macro, as best fits your design.

Noncompliant Code Example

In this noncompliant code, pi is declared as a float. Although pi is a mathematical constant, its value is not protected from accidental modification.

float pi = 3.14159f;
float degrees;
float radians;
/* ... */
radians = degrees * pi / 180;

Compliant Solution

In this compliant solution, pi is declared as a const-qualified object.

const float pi = 3.14159f;
float degrees;
float radians;
/* ... */
radians = degrees * pi / 180;

Non-Compliant Code Example

In this example, adapted from [[Dewhurst 02]] Gotcha #25, a macro is used to define a maximum value, but there is no type information associated with the macro.

#define MAX (1<<16)
// ...
void f(int);
void f(long);
// ...
f(MAX);  // which f?

The value 1 << 16 could be an int or a long depending on the platform. As a result, this code becomes platform dependent.

Compliant Solution

Using a constant associates type information with the value and eliminates the possibility of confusion.

int const max = 1<<16;
// ...
void f(int);
void f(long);
// ...
f(max);

Exceptions

DCL00-EX1: It is acceptable to define valueless macros to serve as 'inclusion guards'. That is, the macro serves to control the multiple inclusion of header files, as in the following example:

#ifndef SOME_HEADER_H
#define SOME_HEADER_H
...  // content of header file
#endif

See PRE06-C. Enclose header files in an inclusion guard for more information on inclusion guards.

Risk Assessment

Failing to const-qualify immutable objects can result in a constant being modified at runtime.

Automated Detection

Compass/ROSE can detect most violations of this recommendation.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Other Languages

This rule appears in the C++ Secure Coding Standard as DCL00-CPP. Const-qualify immutable objects.

References

[[Dewhurst 02]] Gotcha #25, "#define Literals"
[[ISO/IEC 9899:1999]] Section 6.7.3, "Type qualifiers"
[[Saks 00]]

02. Declarations and Initialization (DCL)      02. Declarations and Initialization (DCL)