Page History

...

<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="c959367536d354ff-6374099d-455246fe-b34e98b4-0d83a9ba4986016560f29f0c"><ac:parameter ac:name="">1</ac:parameter></ac:structured-macro> \[1\] Note that the POSIX ^&#xAE;^ standard extends the set of identifiers reserved by C99 to include an open-ended set of its own. See section [2.2 Compilation Environment|http://www.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_02] in [\[IEEE Std 1003.1-2008\]|AA. References#IEEE Std 1003.1-2008].

Noncompliant Code Example (Header Guard)

A common but noncompliant practice is to choose a reserved name for a macro used in a preprocessor conditional guarding against multiple inclusion of a header file. See also PRE06-CPP. Enclose header files in an inclusion guard. The name may clash with reserved names defined by the implementation of the C standard library in its headers, or with reserved names implicitly predefined by the compiler even when no C standard library header is included. A typical manifestation of such a clash is a compilation error.

#ifndef _MY_HEADER_H_
#define _MY_HEADER_H_

// contents of <my_header.h>

#endif // _MY_HEADER_H_

Compliant Solution (Header Guard)

This compliant solution avoids using leading or trailing underscores in the name of the header guard.

#ifndef MY_HEADER_H
#define MY_HEADER_H

// contents of <my_header.h>

#endif // MY_HEADER_H

Noncompliant Code Example (File Scope Objects)

In this noncompliant code example, the names of the file scope objects _max_limit and _limit both begin with an underscore. Since it is static, the declaration of _max_limit might seem to be impervious to clashes with names defined by the implementation. However, because the header <stddef.h> is included to define size_t a potential for a name clash exists (note, however, that a conforming compiler may implicitly declare reserved names regardless of whether or not any C standard library header has been explicitly included). In addition, because _limit has external linkage, it may clash with a symbol with the same name defined in the language runtime library even if such a symbol is not declared in any header. Consequently, it is unsafe to start the name of any file scope identifier with an underscore, even if its linkage limits its visibility to a single translation unit. Common effects of such clashes range from compiler errors, to linker errors, to abnormal program behavior at runtime.

#include <cstddef>   // for size_t

static const std::size_t _max_limit = 1024;
std::size_t _limit = 100;

unsigned int getValue(unsigned int count) {
  return count < _limit ? count : _limit;
}

Compliant Solution (File Scope Objects)

In this compliant solution, names of no file scope objects begin with an underscore and, hence, do not encroach on the reserved name space.

#include <cstddef>   // for size_t

static const std::size_t max_limit = 1024;
std::size_t limit = 100;

unsigned int getValue(unsigned int count) {
  return count < limit ? count : limit;
}

Noncompliant Code Example (Reserved Macros)

In the noncompliant code example below, because the C standard library header <inttypes.h> is specified to include <stdint.h>, the name MAX_SIZE conflicts with the name of the <stdint.h> header macro used to denote the upper limit of size_t. In addition, while the name INTFAST16_LIMIT_MAX isn't defined by the C standard library, because it begins with the INT prefix and ends with the _MAX suffix it encroaches on the reserved name space (see section 8.26.8 of C99). A typical manifestation of such a clash is a compilation error.

#include <inttypes.h>   // for int_fast16_t and PRIdFAST16

static const int_fast16_t INTFAST16_LIMIT_MAX = 12000;

void print_fast16(int_fast16_t val) {
    enum { MAX_SIZE = 80 };
    char buf [MAX_SIZE];
    if (INTFAST16_LIMIT_MAX < val)
      std::sprintf(buf, "The value is too large");
    else
      std::snprintf(buf, MAX_SIZE, "The value is %" PRIdFAST16, val);
    // ...
}

Compliant Solution (Reserved Macros)

The compliant solution below avoids redefining reserved names or using reserved prefixes and suffixes.

#include <inttypes.h>   // for int_fast16_t and PRIdFAST16

static const int_fast16_t MY_INTFAST16_UPPER_LIMIT = 12000;

void print_fast16(int_fast16_t val) {
    enum { BUFSIZE = 80 };
    char buf [BUFSIZE];
    if (MY_INTFAST16_UPPER_LIMIT < val)
      std::sprintf(buf, "The value is too large");
    else
      std::snprintf(buf, BUFSIZE, "The value is %" PRIdFAST16, val);
    // ...
}

Noncompliant Code Example (Identifiers With External Linkage)

In addition to symbols defined as functions in each C standard library header, identifiers with external linkage include, among many others, errno, math_errhandling, setjmp(), and va_end(), regardless of whether any of them is masked by a macro of the same name or not.

...

#include <cstddef>

void* malloc(std::size_t nbytes) {
  void *ptr;
  // allocate storage from own pool and set ptr
  return ptr;
}

void free(void *ptr) {
  // return storage to own pool
}

Compliant Solution (Identifiers With External Linkage)

The compliant, portable solution avoids redefining any C standard library identifiers with external linkage. In addition, it provides definitions for all memory allocation functions.

#include <cstddef>

void* my_malloc(std::size_t nbytes) {
  void *ptr;
  // allocate storage from own pool and set ptr
  return ptr;
}

void* my_calloc(std::size_t nelems, std::size_t elsize) {
  void *ptr;
  /// allocate storage from own pool and set ptr
  return ptr;
}

void* my_realloc(void *ptr, std::size_t nbytes) {
  // reallocate storage from own pool and set ptr
  return ptr;
}

void my_free(void *ptr) {
  // return storage to own pool
}

Risk Assessment

Using reserved identifiers can lead to incorrect program operation.

Automated Detection

A module written in Compass/ROSE can detect violations of this rule.

Other Languages

This rule appears in the C Secure Coding Standard as DCL37-C. Do not declare or define a reserved identifier.

Bibliography

\[[ISO/IEC 14882-2003|AA. Bibliography#ISO/IEC 14882-2003]\] Section 17.4.3.1.2, "Global names"
\[[ISO/IEC 9899:1999|AA. Bibliography#ISO/IEC 9899-1999]\] Section 7.1.3, "Reserved Identifiers"
[\[IEEE Std 1003.1-2008\]|AA. References#IEEE Std 1003.1-2008] Section 2.2 "The Compilation Environment"

...