include guard
In the C and C++ programming languages, an #include guard, sometimes called a macro guard, is a particular construct used to avoid the problem of double inclusion when dealing with the include directive. The addition of #include guards to a header file is one way to make that file idempotent.
Double inclusion
The following C code demonstrates a real problem that can arise if #include guards are missing:
- File "grandfather.h"
struct foo {
int member;
};
- File "father.h"
#include "grandfather.h"
- File "child.c"
#include "grandfather.h"
#include "father.h"
Here, the file "child.c" has indirectly included two copies of the text in the header file "grandfather.h". This causes a compilation error, since the structure type foo will thus be defined twice. In C++, this would be a violation of the One Definition Rule.
Use of #include guards
- File "grandfather.h"
#ifndef GRANDFATHER_H
#define GRANDFATHER_H
struct foo {
int member;
};
#endif /* GRANDFATHER_H */
- File "father.h"
#include "grandfather.h"
- File "child.c"
#include "grandfather.h"
#include "father.h"
Here, the first inclusion of "grandfather.h" causes the macro GRANDFATHER_H to be defined. Then, when "child.c" includes "grandfather.h" the second time, the #ifndef test returns false, and the preprocessor skips down to the #endif, thus avoiding the second definition of struct foo. The program compiles correctly.
Different naming conventions for the guard macro may be used by different programmers. Other common forms of the above example include GRANDFATHER_INCLUDED, CREATORSNAME_YYYYMMDD_HHMMSS (with the appropriate time information substituted), and names generated from a UUID. (However, names starting with one or two underscores, such as _GRANDFATHER_H and __GRANDFATHER_H, are reserved to the implementation and should not be used by the user.[1][2])
Of course, it is important to avoid duplicating the same include-guard macro name in different header files, as including the 1st will prevent the 2nd from being included, leading to the loss of any declarations, inline definitions, or other #includes in the 2nd header.
Difficulties
In order for #include guards to work properly, each guard must test and conditionally set a different preprocessor macro. Therefore, a project using #include guards must work out a coherent naming scheme for its include guards, and make sure its scheme doesn't conflict with that of any third-party headers it uses, or with the names of any globally visible macros.
For this reason, most C and C++ implementations provide a non-standard #pragma once directive. This directive, inserted at the top of a header file, will ensure that the file is included only once. The Objective-C language (which is a superset of C) introduced an #import directive, which works exactly like #include, except that it includes each file only once, thus obviating the need for #include guards.[3]