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 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.

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.

Different naming conventions for the guard macro may be used by different programmers. Other possible forms of the above example include GRANDFATHER_INCLUDED and _GRANDFATHER_H, although _GRANDFATHER_H is prohibited by the C++ standard as it begins with an underscore followed by an upper-case letter [C++ standard (ISO/IEC14882) section 17.4.3.1.2.1] .

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.

ee also

*C preprocessor
* #pragma once
*Circular dependency

External links

* [http://www.bobarcher.org/software/include/index.html Include guard optimisation]
* [http://c2.com/cgi/wiki?RedundantIncludeGuards Redundant Include Guards]
* [http://www.codeproject.com/tools/includeguard.asp Generator for Include File Guards]

References