Skip to end of metadata
Go to start of metadata

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 could not 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 include guard:

#ifndef HEADER_H
#define HEADER_H

/* ... Contents of <header.h> ... */

#endif /* HEADER_H */

Consequently, the first time 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 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 include guard. See DCL37-C. Do not declare or define a reserved identifier.

Risk Assessment

Failure to include header files in an include guard can result in unexpected behavior.

Recommendation

Severity

Likelihood

Remediation Cost

Priority

Level

PRE06-C

Low

Unlikely

Low

P3

L3

Automated Detection

ToolVersionCheckerDescription
Astrée
19.04
multiple-includePartially checked
Axivion Bauhaus Suite

6.9.0

CertC-PRE06

ECLAIR

1.2

CC2.PRE06

Fully implemented
Klocwork
2018
MISRA.INCGUARD
LDRA tool suite
9.7.1

243 S

Fully implemented
Parasoft C/C++test10.4.2

CERT_C-PRE06-a

Use multiple include guards

Polyspace Bug Finder

R2019a

CERT C: Rec. PRE06-CChecks for content of header file not guarded from multiple inclusions (rec. fully covered)


PRQA QA-C
9.5
0883Fully implemented
RuleChecker
19.04
multiple-includePartially checked

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Related Guidelines

Bibliography

[Plum 1985]Rule 1-14



2 Comments

  1. I think you have an exclusion here for the cases when you do want to include headers more than once.

    Some headers do need to be included more than once (e.g. the standard header assert.h).

    Sometimes, generated code can result in headers that need to be included multiply too.

  2. This is a double-edged sword. Including the same file multiple times has it's benefits when you know what you are doing. I realize that you are trying to set up a common set of rules to make people compliant and safe, but in some cases there are are much broader applicability for including the header file multiple times like here. One of the common problems with C/C++ code is the repeated switch statements where a given "enum" type is being used in multiple contexts. Multiple-header-inclusion solves this to be lazy and auto generated.

    YMMV. (wink)