Page History

Immutable (constant values) objects should be declared as const-qualified objects (unmodifiable lvalues), enumerations values, or as a last resort, a #define.

In general, it is preferable to declare immutable values as const-qualified objects rather than as macro definitions. Using a const declared value means that the compiler is able to check the type of the object, the object has scope, and (certain) debugging tools can show the name of the object. const-qualified objects cannot be used where compile-time integer constants are required, namely to define the:

• size of a bit-field member of a structure
• size of an array (except in the case of variable length arrays)
• value of an enumeration constant
• value of a case constant.

If any of these are required, then an integer constant (an rvalue) must be used. For integer constants, it is preferable to use an enum instead of a const-qualified object as this eliminates the possibility of taking the address of the integer constant and does not required that storage is allocated for the value.

This recommendation is related to EXP10-A. Do not diminish the benefits of constants by assuming their values in expressions.

Non-Compliant Code (object-like macro)

A preprocessing directive of the form:

# define identifier replacement-list new-line

defines an _object-like_ macro that causes each subsequent instance of the macro name to be replaced by the replacement list of preprocessing tokens that constitute the remainder of the directive \[[ISO/IEC 9899-1999|AA. C References#ISO/IEC 9899-1999]\].

. Enforcing object immutability using const qualification helps ensure the correctness and security of applications. ISO/IEC TR 24772, for example, recommends labeling parameters as constant to avoid the unintentional modification of function arguments [ISO/IEC TR 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 become still more necessary. This phenomenon is sometimes called const poisoning, which can frequently lead to violations of EXP05-C. Do not cast away a const qualification. Although const qualification is a good idea, the costs may outweigh the value in the remediation of existing code.

A macro or an enumeration constant may also be used instead of a const-qualified object. DCL06-C. Use meaningful symbolic constants to represent literal values 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 modificationIn this non-compliant code example, PI is defined as an object-like macro. Following the definition, each subsequent occurrence of the string "PI" is replaced by the string "3.14159" by textual substitution.

float pi =
#define PI 3.1415914159f;
float degrees;
float radians;
/* ... */
radians = degrees * PIpi / 180;

An unsuffixed floating constant, as in this example, has type double. If suffixed by the letter f or F, it has type float. If suffixed by the letter l or L, it has type long double.

Compliant Solution

In this compliant solution, pi is declared as a const-qualified object, allowing the constant to have scope.:

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

While inadequate in some ways, this is the best that can be done for non-integer constants.

Non-Compliant Code Example (immutable integer values)

In this non-compliant code example, max is declared as a const-qualified object. While declaring non-integer constants as const-qualified object is the best that can be done in C, for integer constants we can do better. Declaring immutable integer values as const-qualified objects still allows the programmer to take the address of the object. Also, const-qualified integers cannot be used in locations where an integer constant is required, such as the value of a case constant.

int const max = 15;
int a[max]; /* invalid declaration outside of a function */
int const *p;

p = &max; /* legal to take the address of a const-qualified object */

Most C compilers allocate memory for const-qualified objects.

Compliant Solution (enum)

This compliant solution declares max as an enum rather than a const-qualified object or a macro definition.

enum { max = 15 };
int a[max]; /* OK */
int const *p;

p = &max; /* error: '&' on constant */

Risk Assessment

Failing to declare immutable values using const or enum can result in a value intended to be constant being changed at runtime.

...

Rule

...

Severity

...

Likelihood

...

Remediation Cost

...

Priority

...

Level

...

DCL00-A

...

1 (low)

...

1 (unlikely)

...

2 (medium)

...

P2

Risk Assessment

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

Automated Detection

Related Vulnerabilities

...

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

References

Related Guidelines

 Bibliography

...

Image Added Image Added Image Added Wiki Markup\[[ISO/IEC 9899-1999|AA. C References#ISO/IEC 9899-1999]\] Section 6.3.2.1, "Lvalues, arrays, and function designators," Section 6.7.2.2, "Enumeration specifiers," and Section 6.10.3, "Macro replacement"