Until the early 1980s, large software development projects had a continual problem with the inclusion of headers. One group might have produced a graphics.h, for example, which started by including io.h. Another group might have produced keyboard.h, which also included io.h. If io.h cannot safely be included several times, arguments would break out about which header should include it. Sometimes an agreement was reached that each header should include no other headers, and as a result, some application programs started with dozens of #include lines, and sometimes they got the ordering wrong or forgot a required header.
Compliant Solution
All these complications disappeared with the discovery of a simple technique: each header should #define a symbol that means "I have already been included." The entire header is then enclosed in an inclusion guard:
#ifndef HEADER_H #define HEADER_H /* ... contents of <header.h> ... */ #endif /* HEADER_H */
Consequently, the first time that header.h is #include'd, all of its contents are included. If the header file is subsequently #include'd again, its contents are bypassed.
Because solutions such as this one make it possible to create a header file that can be included more than once, the C standard [[ISO/IEC 9899:1999]] guarantees that the standard headers are safe for multiple inclusion.
Note that it is a common mistake to choose a reserved name for the name of the macro used in the inclusion guard. See DCL37-C. Do not use identifiers that are reserved for the implementation.
Risk Assessment
Failure to include header files in an inclusion guard can result in unexpected behavior.
Recommendation |
Severity |
Likelihood |
Remediation Cost |
Priority |
Level |
|---|---|---|---|---|---|
PRE06-C |
low |
unlikely |
low |
P3 |
L3 |
Automated Detection
The LDRA tool suite V 7.6.0 can detect violations of this recommendation.
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
Other Languages
This rule appears in the C++ Secure Coding Standard as PRE06-CPP. Enclose header files in an inclusion guard.
References
[[ISO/IEC 9899:1999]] Section 6.10, "Preprocessing directives," Section 5.1.1, "Translation environment," and Section 7.1.2, "Standard headers"
[[MISRA 04]] Rule 19.5
[[Plum 85]] Rule 1-14