Include guard
From Wikipedia, the free encyclopedia
- The correct title of this article is #include guard. The substitution or omission of a # sign is because of technical restrictions.
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.
Contents |
[edit] Double inclusion
The following C code demonstrates a 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 is apparently defined twice.
[edit] Use of #include guards
- File "grandfather.h"
#ifndef H_GRANDFATHER
#define H_GRANDFATHER
struct foo {
int member;
};
#endif
- 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 H_GRANDFATHER to be defined. Then, when "child.c" includes "grandfather.h" the second time, the #ifndef test fails, and the preprocessor skips down to the #endif, thus avoiding the second definition of struct foo. The program compiles correctly.
[edit] 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, many C and C++ implementations provide the non-standard directive #pragma once. This directive, inserted at the top of a header file, will ensure that the file is only included once. This approach, however, can be thwarted by the potential difficulty of telling whether two #include directives in different places actually refer to the same header (for example, via a symbolic link on Unix-like systems). Also, since #pragma once is not a standard directive, its semantics may be subtly different on different implementations.
