Page History

...

• All identifiers that begin with an underscore and either an uppercase letter or another underscore are always reserved for any use.
• All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary and tag name spaces.
• Each macro name in any of the following subclauses (including the future library directions) is reserved for use as specified if any of its associated headers is included, unless explicitly stated otherwise.
• All identifiers with external linkage (including future library directions) and errno are always reserved for use as identifiers with external linkage.
• Each identifier with file scope listed in any of the following subclauses (including the future library directions) is reserved for use as a macro name and as an identifier with file scope in the same name space if any of its associated headers is included.

Additionally, subclause 7.31 defines many other reserved identifiers for future library directions.

No other identifiers are reserved. (Note that the POSIX standard extends the set of identifiers reserved by the C Standard to include an open-ended set of its own. See section 2.2, "The Compilation Environment," in IEEE Std 1003.1-2008.) The behavior of a program that declares or defines an identifier in a context in which it is reserved, or that defines a reserved identifier as a macro name, is undefined. See also undefined behavior 106  in Annex J of the C Standard. Trying to define a reserved identifier can result in its name conflicting with that used in implementation, which may or may not be detected at compile time.

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-C. 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 diagnostic message issued by the compiler.

#ifndef _MY_HEADER_H_
#define _MY_HEADER_H_

/* Contents of <my_header.h> */

#endif /* _MY_HEADER_H_ */

...

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

...

In this noncompliant code example, the names of the file scope objects _max_limit and _limit both begin with an underscore. Because 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 any C standard library header is 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 diagnostics issued by the compiler to linker errors to abnormal program behavior at runtime.

#include <stddef.h>  /* For size_t */

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

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

...

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

#include <stddef.h>  /* For size_t */

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

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

...

In this noncompliant code example, because the C standard library header <inttypes.h> is specified to include <stdint.h>, the name MAX_SIZE conflicts with a standard macro of the name of the <stdint.h> header macro same name, used to denote the upper limit of size_t. In addition, although the name INTFAST16_LIMIT_MAX is not defined by the C standard library, it encroaches on the reserved name space is a reserved identifier because it begins with the INT prefix and ends with the _MAX suffix. (See subclause 7.31.10 of the C Standard .) A typical manifestation of such a clash is a diagnostic message issued by the compiler.[ISO/IEC 9899:2011].)

#include <inttypes.h>  /* For int_fast16_t and PRIdFAST16 */
#include <stdio.h>     /* For sprintf and snprintf */

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) {
    sprintf(buf, "The value is too large");
  } else {
    snprintf(buf, MAX_SIZE, "The value is %" PRIdFAST16, val);
  }
  /* ... */
}

Compliant Solution (Reserved Macros)

...

#include <inttypes.h>  /* For int_fast16_t and PRIdFAST16 */
#include <stdio.h>     /* For sprintf and snprintf */
 
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) {
    sprintf(buf, "The value is too large");
  } else {
     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, and math_errhandling, setjmp(), and va_end(), regardless of whether any of them is them are masked by a macro of the same name.

This noncompliant example provides definitions for the C standard library functions malloc() and free(). Although this practice is permitted by many traditional implementations of UNIX (e.g., the Dmalloc library), it is disallowed by the C Standard because it is not generally portable and may lead to undefined behavior. Common effects range from diagnostics issued by the compiler to linker errors to abnormal program behavior at runtime. Even on systems that allow replacing malloc(), doing so without also replacing calloc() and realloc() is likely to cause problems as well.

#include <stddef.h>  /* For size_t */
 
void * malloc(size_t nbytes) {
  void *ptr;
  /* Allocate storage from own pool and set ptr */
  return ptr;
}

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

...

#include <stddef.h>  /* For size_t */

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

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

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

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

...

a macro definition of errno is suppressed in order to access an actual object, or the program defines an identifier with the name errno. [ISO/IEC 9899:2011]

(See subclause 7.5 paragraph 2, and undefined behavior 114 in Annex J of the C Standard.)

...

Implementations conforming to C are required to declare errno in <errno.h>, although some historic implementations failed to do so.

Noncompliant Code Example (malloc(), free())

In this noncompliant example, the identifiers for the C standard library functions malloc() and free() are reserved:

#include <stddef.h>  /* For size_t */
#include <stdlib.h>  /* General utilities */
 
void *malloc(size_t nbytes) {  /* Violation */
  void *ptr;
  /* ... */
  /* Allocate storage from own pool and set ptr */
  return ptr;
}
 
void free(void *ptr) {  /* Violation */
  /* ... */
  /* Return storage to own pool */
}

Compliant Solution ( malloc(), free() )

This complaint example changes the names of the identfiers to malloc_custom() and free_custom():

#include <stddef.h>  /* For size_t */
 
void *malloc_custom(size_t nbytes) {  
  void *ptr;
  /* ... */
  /* Allocate storage from own pool and set ptr */
  return ptr;
}
 
void free_custom(void *ptr) {  
  /* ... */
  /* Return storage to own pool */
}

Exceptions

DCL37-EX1: It is permissible to use reserved words in declarations when the risk of clashing with a preexisting variable is greater than the risk of clashing with a reserved word. In particular, the scope must be used in a macro that may be invoked with arbitrary preexisting variables (possibly as arguments). The following code demonstrates a SWAP_UNSAFE() macro that exchanges two values, and uses a __tmp variable as a temporary value. This code is permitted because the temporary variable is more likely to clash with a nonreserved variable in the current scope than with a reserved word. This code should be considered nonportable because it requires the current platform to allow the use of __tmp.

...

Related Guidelines

...

...