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 programming language, an #include guard, sometimes called a macro guard, or referred to as making a header file idempotent, is a particular construct used to avoid the problem of double inclusion when dealing with the #include directive, as demonstrated in the following sample C code:

1 Double inclusion
2 Use of #include guards
3 Difficulties
4 See also

[edit] Double inclusion

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 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 "father.h" includes "grandfather.h" the second time, the #ifndef test fails, and the compiler 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, see Symbolic link). Also, since #pragma once is not a standard directive, its semantics may be subtly different on different implementations.