Page History

According to the C Standard, 6.4.2.1 paragraph 7 [ISO/IEC 9899:TC3 Section 7.1.3 on reserved identifiers,2024],

Some identifiers are reserved.

    —  All identifiers that begin with a double underscore (__) or

All identifiers that

begin with an underscore

and either

(_) followed by an uppercase letter

or another underscore

are

always

reserved for any use

, except those identifiers which are lexically identical to keywords.

    —  All

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.

Other identifiers may be reserved, see 7.1.3.

C Standard, 7.1.3 paragraph 1 [ISO/IEC 9899:2024],

Each header declares or defines all identifiers listed in its associated subclause, and optionally declares or defines identifiers listed in its associated future library directions subclause and identifiers which are always reserved either for any use or for use as file scope identifiers.

    — All potentially reserved identifiers (including ones listed in the future library directions) that are provided by an implementation with an external definition are reserved for any use. An implementation shall not provide an external definition of a potentially reserved identifier unless that identifier is reserved for a use where it would have external linkage. All other potentially reserved identifiers that are provided by an implementation (including in the form of a macro) are reserved for any use when the associated header is included. No other potentially reserved identifiers are reserved.

    — 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 (see 7.1.4).

    — All identifiers with external linkage in any of the following subclauses (including the 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

above

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.33 defines many other reserved identifiers for future library directions.

No other identifiers are reserved

...

. (The POSIX standard extends the set of identifiers reserved by the C Standard to include an open-ended set of its own. See Portable Operating System Interface [POSIX^®], Base Specifications, Issue 7, Section 2.2, "The Compilation Environment" [IEEE Std 1003.1-2013].) 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

...

Noncompliant Code Example

In this example, variables are defined with names reserved for the implementation.

long _Max_Value;
int __length; 

Compliant Solution

This compliant solution uses identifiers that are not reserved.

...

...

is undefined. (See undefined behavior 106.)

Noncompliant Code Example (

...

Include Guard)

A common, but non-compliant noncompliant, practice is to choose a reserved name for a macro used in a preprocessor conditional guarding against multiple inclusion inclusions of a header file. (See also PRE06-C. Enclose header files in an inclusion include 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.

#ifndef _MY_HEADER_H_
#define _MY_HEADER_H_

/* contentsContents of <my_header.h> */

#endif /* _MY_HEADER_H_ */

Compliant Solution (

...

Include Guard)

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

#ifndef MY_HEADER_H
#define MY_HEADER_H

/* contentsContents of <my_header.h> */

#endif /* MY_HEADER_H */

Noncompliant Code Example (

...

File Scope Objects)

In this example, a variable beginning with an underscore is defined with implicit global scope.

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

size_t _limit = 100;

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

Noncompliant Code Example (Static Variable)

In this example, the variable is declared as static and, hence, has file scope.

noncompliant code example, the names of the file scope objects _max_limit and _limit both begin with an underscore. Because _max_limit is static, this declaration 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 of the same name defined in the language runtime library even if such a symbol is not declared in any header. Consequently, it is not safe to start the name of any file scope identifier with an underscore even if its linkage limits its visibility to a single translation unitThis code might have been safe if the C file containing it includes no header files. However, it requires that the header stddef.h be included in order to define size_t. Including any standard header files will introduce a potential name clash. Consequently it is not safe to prepend any identifier with an underline, even if its usage is confined to a single file.

#include <stddef.h>   /* for

static const size_t */

static  _max_limit = 1024;
size_t _limit = 100;

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

Compliant Solution (

...

File Scope Objects)

In this compliant solution, the variable name does names of file scope objects do not begin with an underscore and, hence, is not reserved. :

#include <stddef.h>   /* for

static const size_t */

max_limit = 1024;
size_t limit = 100;

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

Noncompliant Code Example

...

Identifiers with external linkage include, among many others, setjmp, errno, math_errhandling, and va_end.
In the example, errno is defined. The errno value set by the function open() would not be accessible to the program because its definition is suppressed. For information regarding redefining errno, see ERR31-C. Don't redefine errno.

#include <errno.h>

#define errno 200

int validate(unsigned int secretValue){
  
  char fname[] = "non_exist.txt";
  int fd;
  int result = -1;

  fd = open(fname, O_RDONLY); 

  if(fd == -1){
    printf("Error opening file. Error code : %d\n", errno); 
    return result;
  }

  close(fd); 

  if(errno % secretValue == 20){
    result = 0;
  }
  else{
    result = -1;
  } 
  
  return result;
  
}

Compliant Solution

In this compliant solution, the reserved identifier errno is not used.

(Reserved Macros)

In this noncompliant code example, because the C standard library header <inttypes.h> is specified to include <stdint.h>, the name SIZE_MAX conflicts with a standard macro of the same name, which is 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 is a reserved identifier because it begins with the INT prefix and ends with the _MAX suffix. (See the C Standard, 7.33.14.)

#include <inttypes.h>
#include <stdio.h>

static const int_fast16_t INTFAST16_LIMIT_MAX = 12000;

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

Compliant Solution (Reserved Macros)

This compliant solution avoids redefining reserved names or using reserved prefixes and suffixes:

#include <inttypes.h>
#include <stdio.h>
 
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)

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 (for example, the Dmalloc library), it is undefined behavior according to the C Standard. Even on systems that allow replacing malloc(), doing so without also replacing aligned_alloc(), calloc(), and realloc() is likely to cause problems.

#include <stddef.h>
 
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 */
}

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 <stddef.h>

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

void *my_aligned_alloc(size_t alignment, size_t size) {
  void *ptr;
  /* Allocate storage from own pool, align properly, set ptr */
  return ptr;
}

void *my_calloc(size_t nelems, size_t elsize) {
  void *ptr;
  /* Allocate storage from own pool, zero memory, 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 */
}

Noncompliant Code Example (errno)

In addition to symbols defined as functions in each C standard library header, identifiers with external linkage include errno and math_errhandling.  According to the C Standard, 7.5, paragraph 2 [ISO/IEC 9899:2011], the behavior of a program is undefined when

A macro definition of errno is suppressed in order to access an actual object, or the program defines an identifier with the name errno. 

See undefined behavior 114.

The errno identifier expands to a modifiable lvalue that has type int but is not necessarily the identifier of an object. It might expand to a modifiable lvalue resulting from a function call, such as *errno(). It is unspecified whether errno is a macro or an identifier declared with external linkage. If a macro definition is suppressed to access an actual object, or if a program defines an identifier with the name errno, the behavior is undefined.

Legacy code is apt to include an incorrect declaration, such as the following:

extern int errno;

Compliant Solution (errno)

The correct way to declare errno is to include the header <errno.h>:

#include <errno.h>

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

Exceptions

DCL37-C-EX1: Provided that a library function can be declared without reference to any type defined in a header, it is permissible to declare that function without including its header provided that declaration is compatible with the standard declaration.

/* Not including stdlib.h */
void free(void *);
 
void func(void *ptr) {
  free(ptr);
}

Such code is compliant because the declaration matches what stdlib.h would provide and does not redefine the reserved identifier. However, it would not be acceptable to provide a definition for the free() function in this example.

DCL37-C-EX2: For compatibility with other compiler vendors or language standard modes, it is acceptable to create a macro identifier that is the same as a reserved identifier so long as the behavior is idempotent, as in this example:

/* Sometimes generated by configuration tools such as autoconf */
#define const const
 
/* Allowed compilers with semantically equivalent extension behavior */
#define inline __inline

DCL37-C-EX3: As a compiler vendor or standard library developer, it is acceptable to use identifiers reserved for your implementation. Reserved identifiers may be defined by the compiler, in standard library headers or headers included by a standard library header, as in this example declaration from the glibc standard C library implementation:

/*
  The following declarations of reserved identifiers exist in the glibc implementation of
  <stdio.h>. The original source code may be found at:
  https://sourceware.org/git/?p=glibc.git;a=blob_plain;f=include/stdio.h;hb=HEAD
*/
 
#  define __need_size_t
#  include <stddef.h>
/* Generate a unique file name (and possibly open it).  */
extern int __path_search (char *__tmpl, size_t __tmpl_len,
			  const char *__dir, const char *__pfx,
			  int __try_tempdir);

#include <errno.h>

#define keyNum 200

int validate(unsigned int secretValue){
  
  char fname[] = "non_exist.txt";
  int fd;
  int result = -1;

  fd = open(fname, O_RDONLY); 

  if(fd == -1){
    printf("Error opening file. Error code : %d\n", errno); 
    return result;
  }

  close(fd); 

  if(errno % secretValue == 20){
    result = 0;
  }
  else{
    result = -1;
  } 
  
  return result;
  
}

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.

References

Tool	Version	Checker	Description
Astrée	Include Page Astrée_V Astrée_V	future-library-use language-override language-override-c99 reserved-declaration reserved-declaration-c99 reserved-identifier	Partially checked
Axivion Bauhaus Suite	Include Page Axivion Bauhaus Suite_V Axivion Bauhaus Suite_V	CertC-DCL37	Fully implemented. Reserved identifiers, as in DCL37-C-EX3, are configurable.
CodeSonar	Include Page CodeSonar_V CodeSonar_V	LANG.STRUCT.DECL.RESERVED	Declaration of reserved name
Compass/ROSE
Coverity	Include Page Coverity_V Coverity_V	MISRA C 2004 Rule 20.1 MISRA C 2004 Rule 20.2 MISRA C 2012 Rule 21.1 MISRA C 2012 Rule 21.2	Implemented
Cppcheck Premium	Include Page Cppcheck Premium_V Cppcheck Premium_V	premium-cert-dcl37-c	Partially Implemented Can detect use of reserved name for a macro
ECLAIR	Include Page ECLAIR_V ECLAIR_V	CC2.DCL37	Fully implemented
Helix QAC	Include Page Helix QAC_V Helix QAC_V	C0602, C0603, C4600, C4601, C4602, C4603, C4604, C4605, C4606, C4607, C4608, C4620, C4621, C4622, C4623, C4624, C4640, C4641, C4642, C4643, C4644, C4645	Fully implemented
Klocwork	Include Page Klocwork_V Klocwork_V	MISRA.DEFINE.WRONGNAME.UNDERSCORE MISRA.STDLIB.WRONGNAME.UNDERSCORE MISRA.STDLIB.WRONGNAME	Fully implemented
LDRA tool suite	Include Page LDRA_V LDRA_V	86 S, 218 S, 219 S, 580 S, 626 S	Fully Implemented
Parasoft C/C++test	Include Page Parasoft_V Parasoft_V	CERT_C-DCL37-a	Do not #define or #undef identifiers with names which start with underscore
PC-lint Plus	Include Page PC-lint Plus_V PC-lint Plus_V	978, 9071, 9093	Partially supported
Polyspace Bug Finder	Include Page Polyspace Bug Finder_V Polyspace Bug Finder_V	CERT C: Rule DCL37-C	Checks for: Defining and undefining reserved identifiers or macros Declaring a reserved identifier or macro name Rule partially covered
PVS-Studio	Include Page PVS-Studio_V PVS-Studio_V	V677
SonarQube C/C++ Plugin	Include Page SonarQube C/C++ Plugin_V SonarQube C/C++ Plugin_V	S978
RuleChecker	Include Page RuleChecker_V RuleChecker_V	future-library-use language-override language-override-c99 reserved-declaration reserved-declaration-c99 reserved-identifier	Partially checked

Related Guidelines

Key here (explains table format and definitions)

Bibliography

...

Image Added Image Added Image Added Wiki Markup\[[ISO/IEC 9899:1999|AA. C References#ISO/IEC 9899-1999]\] Section 7.1.3, "Reserved Identifiers"