![]() | This sectionmay be too technical for most readers to understand. Pleasehelp improve it tomake it understandable to non-experts, without removing the technical details.(September 2018) (Learn how and when to remove this message) |
In theC andC++ programming languages, an#include guard, sometimes called amacro guard,header guard orfile guard, is a way to avoid the problem ofdouble inclusion when dealing with theinclude directive.
TheC preprocessor processes inclusion directives like#include "Foo.h"
to include "Foo.h" andtranscludes the code of that file into a copy of the main file often called thetranslation unit.
However, if an #include directive for a given file appears multiple times during compilation, the code will effectively be duplicated in that file. If the included file includes a definition, this can cause acompilation error due to theOne Definition Rule, which says that definitions (such as the definition of a class) cannot be duplicated in a translation unit. #include guards prevent this by defining apreprocessor macro when a header is first included. In the event that header file is included a second time, the #include guard will prevent the actual code within that header from being compiled.
An alternative to #include guards is#pragma once. This non-standard but commonly supported directive among C and C++compilers has the same purpose as an #include guard, but has less code and does not require the definition of a variable.
Modules, introduced inC++20, eliminate the necessity of#include
guards, due to not being handled by the preprocessor. Modules can only be imported at most one time into atranslation unit.
The following C code demonstrates a real problem that can arise if #include guards are missing:
structFoo{intmember;};
#include"Grandparent.h"
#include"Grandparent.h"#include"Parent.h"
structFoo{// From "Grandparent.h"intmember;};structFoo{// From "Parent.h"intmember;};
Here, the file "Child.c" has indirectly included two copies of the text in theheader file "Grandparent.h". This causes acompilation error, since the structure typeFoo
will thus be defined twice. In C++, this would be called a violation of theone definition rule.
The same code as the previous section is used with the addition of #include guards. TheC preprocessor preprocesses the header files, including and further preprocessing themrecursively. This will result in a working source file.
#ifndef GRANDPARENT_H#define GRANDPARENT_HstructFoo{intmember;};#endif/* GRANDPARENT_H */
#include"Grandparent.h"
#include"Grandparent.h"#include"Parent.h"
// Contents from "Grandparent.h"#ifndef GRANDPARENT_H// GRANDPARENT_H is not defined#define GRANDPARENT_HstructFoo{// This definition is compiledintmember;};#endif/* GRANDPARENT_H */// Contents from "Parent.h"#ifndef GRANDPARENT_H// GRANDPARENT_H is already defined#define GRANDPARENT_HstructFoo{// This definition is not compiledintmember;};#endif/* GRANDPARENT_H */
structFoo{intmember;};
Here, the first inclusion of "Grandparent.h" has the macroGRANDPARENT_H
defined. When "Child.c" includes "Grandparent.h" at the second time (while including "Parent.h"), as the#ifndef
test returns false, the preprocessor skips down to the#endif
, thus avoiding the second definition ofstruct Foo
. The program compiles correctly.
Differentnaming conventions for the guardmacro may be used by differentprogrammers. Other common forms of the above example includeGRANDPARENT_INCLUDED
,CREATORSNAME_YYYYMMDD_HHMMSS
(with the appropriate time information substituted), and names generated from aUUID. (However,names starting with one underscore and acapital letter (C and C++) or any name containing double underscore (C++ only), such as_GRANDPARENT_H
andGRANDPARENT__H
, are reserved to the language 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.
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) has an#import
directive, which works exactly like#include
, except that it includes each file only once, thus obviating the need for #include guards.[3]
Some languages support specifying that the code should be included only once, in the including file, rather than in the included one (as with C/C++ include guards and#pragma once
):
%INCLUDE
statement as the equivalent to C's#include
directive. IBM Enterprise PL/I also supports the%XINCLUDE
statement which will "incorporate external text into the source program if it has not previously been included." (It also offers anXPROCEDURE
statement, similar to aPROCEDURE
statement, which will ignore the second and subsequent occurrences of anXPROCEDURE
with the same name.)[4]#import
directive (see above)include_once
[5]