According to the C Standard, subclause 7.1.3 [ISO/IEC 9899:2011],
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. (
...
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
...
"
...
...
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
...
is undefined. (See
...
...
.)
Noncompliant Code Example (
...
Include Guard)
A common, but 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.
Code Block | ||||
---|---|---|---|---|
| ||||
#ifndef _MY_HEADER_H_ #define _MY_HEADER_H_ /* Contents of <my_header.h> */ #endif /* _MY_HEADER_H_ */ |
Compliant Solution (
...
Include Guard)
This compliant solution avoids using leading underscores in the macro name of the header include guard:
Code Block | ||||
---|---|---|---|---|
| ||||
#ifndef MY_HEADER_H #define MY_HEADER_H /* Contents of <my_header.h> */ #endif /* MY_HEADER_H */ |
...
In this noncompliant code example, the names of the file scope objects _max_limit
and _limit
both begin with an underscore. Because it _max_limit
is static, the this 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 in order 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 of the same name defined in the language runtime library even if such a symbol is not declared in any header. Consequently, it is unsafe 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 unit.
...
In this compliant solution, names of file - scope objects do not begin with an underscore:
...
In this noncompliant code example, because the C standard library header <inttypes.h>
is specified to include <stdint.h>
, the name SIZE_MAX_SIZE
conflicts with a standard macro of the same name, used 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 subclause the C Standard, 7.31.10 of the C Standard [ISO/IEC 9899:2011].)
Code Block | ||||
---|---|---|---|---|
| ||||
#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_SIZE = 80 }; char buf[SIZE_MAX_SIZE]; if (INTFAST16_LIMIT_MAX < val) { sprintf(buf, "The value is too large"); } else { snprintf(buf, MAXSIZE_SIZEMAX, "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 (e.g.for example, the Dmalloc library), it is disallowed by undefined behavior according to the C Standard because it is undefined behavior. Even on systems that allow replacing malloc()
, doing so without also replacing aligned_alloc()
, calloc()
, and realloc()
is likely to cause problems.
...
Code Block | ||||
---|---|---|---|---|
| ||||
#include <stddef.h> void *my_malloc(size_t nbytes) { void *ptr; /* Allocate storage from own pool and set ptr */ return ptr; } void *my_aligned_callocalloc(size_t nelemsalignment, size_t elsizesize) { void *ptr; /* Allocate storage from own pool, andalign properly, set ptr */ return ptr; } void *my_realloccalloc(void *ptrsize_t nelems, size_t nbyteselsize) { void *ptr; /* ReallocateAllocate storage from own pool, and set zero memory, and set ptr */ return ptr; } void *my_freerealloc(void *ptr, size_t nbytes) { /* ReturnReallocate storage tofrom own pool and set ptr */ return ptr; } |
Noncompliant Code Example (errno
)
The behavior of a program is undefined when
...
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 nameerrno
.
The errno
identifier
(See subclause 7.5 paragraph 2, and undefined behavior 114 in Annex J of the C Standard.)
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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
#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-EX0: 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
.
Code Block | ||||
---|---|---|---|---|
| ||||
#define SWAP_UNSAFE(type, a, b) do { type __tmp = a; a = b; b = __tmp; } while(0)
|
Such macros should be used only with great care. See PRE31-C. Avoid side effects in arguments to unsafe macros and PRE00-C. Prefer inline or static functions to function-like macros for more information.
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.
Code Block | ||||
---|---|---|---|---|
| ||||
/* 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:
Code Block | ||||
---|---|---|---|---|
| ||||
/* 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:DCL37-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 as long as that declaration is compatible with the standard declaration.
Code Block | ||||
---|---|---|---|---|
| ||||
/* 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. It would not be acceptable to provide a definition for the free()
function in the preceding example.
Risk Assessment
Using reserved identifiers can lead to incorrect program operation.
Rule | Severity | Likelihood | Remediation Cost | Priority | Level |
---|---|---|---|---|---|
DCL37-C | Low | Unlikely | Low | P3 | L3 |
Automated Detection
...
Tool
...
Version
...
Checker
...
Description
...
...
...
...
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); |
Risk Assessment
Using reserved identifiers can lead to incorrect program operation.
Rule | Severity | Likelihood | Remediation Cost | Priority | Level |
---|---|---|---|---|---|
DCL37-C | Low | Unlikely | Low | P3 | L3 |
Automated Detection
Tool | Version | Checker | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
Astrée |
| future-library-use language-override language-override-c99 reserved-declaration reserved-declaration-c99 reserved-identifier | Partially checked | ||||||
Axivion Bauhaus Suite |
| CertC-DCL37 | Fully implemented. Reserved identifiers, as in DCL37-C-EX3, are configurable. | ||||||
CodeSonar |
| LANG.STRUCT.DECL.RESERVED | Declaration of reserved name | ||||||
Compass/ROSE | |||||||||
Coverity |
| 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 | ||||||
ECLAIR |
| CC2.DCL37 | Fully implemented | ||||||
Klocwork |
| MISRA.DEFINE.WRONGNAME.UNDERSCORE MISRA.STDLIB.WRONGNAME.UNDERSCORE MISRA.STDLIB.WRONGNAME | |||||||
LDRA tool suite |
| 86 S, 218 S, 219 S, 580 S, 626 S | Fully Implemented | ||||||
Parasoft C/C++test |
| CERT_C-DCL37-a | Do not #define or #undef identifiers with names which start with underscore | ||||||
Polyspace Bug Finder |
| Checks for:
Rule partially covered | |||||||
PRQA QA-C |
| 0602, 0603, 4600, 4601, 4602, 4603, 4604, 4605, 4606, 4607, 4608, 4620, 4621, 4622, 4623, 4624, 4640, 4641, 4642, 4643, 4644, 4645 | |||||||
SonarQube C/C++ Plugin |
| S978 | |||||||
RuleChecker |
| 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)
Taxonomy | Taxonomy item | Relationship |
---|---|---|
CERT C Secure Coding Standard | PRE00-C. Prefer inline or static functions to function-like macros | Prior to 2018-01-12: CERT: Unspecified Relationship |
CERT C Secure Coding Standard | PRE06-C. Enclose header files in an include guard | Prior to 2018-01-12: CERT: Unspecified Relationship |
CERT C Secure Coding Standard | PRE31-C. Avoid side effects in arguments to unsafe macros | Prior to 2018-01-12: CERT: Unspecified Relationship |
CERT C | DCL51-CPP. Do not declare or define a reserved identifier | Prior to 2018-01-12: CERT: Unspecified Relationship |
ISO/IEC TS 17961 | Using identifiers that are reserved for the implementation [resident] | Prior to 2018-01-12: CERT: Unspecified Relationship |
MISRA C:2012 | Rule 21.1 (required) | Prior to 2018-01-12: CERT: Unspecified Relationship |
MISRA C:2012 | Rule 21.2 (required) | Prior to 2018-01-12: CERT: Unspecified Relationship |
...
...
...
Related Guidelines
PRE06-C. Enclose header files in an inclusion guard
PRE31-C. Avoid side effects in arguments to unsafe macros
Bibliography
[IEEE Std 1003.1- |
2013] | Section 2.2, "The Compilation Environment" |
[ISO/IEC 9899:2011] |
7.1.3, "Reserved Identifiers" |
7.31.10, "Integer Types <stdint.h> " |
...