Английская Википедия:Include guard
Шаблон:Short description Шаблон:Correct title Шаблон:Lowercase title Шаблон:Technical In the C and C++ programming languages, an #include guard, sometimes called a macro guard, header guard or file guard, is a particular construct used to avoid the problem of double inclusion when dealing with the include directive.
The C preprocessor processes directives of the form #include <file>
in a source file by locating the associated file
on disk and transcluding ("including") its contents into a copy of the source file known as the translation unit, replacing the include directive in the process. The files included in this regard are generally header files, which typically contain declarations of functions and classes or structs.
If an #include directive for a given file appears multiple times during compilation (i.e. because it appeared in multiple other headers), the file is processed again each time. However, if certain C or C++ language constructs are defined twice, the resulting translation unit is invalid. #include guards prevent this erroneous construct from arising by defining a preprocessor macro when a header is first included, and detecting its presence to skip the file's contents on subsequent inclusions.
The addition of #include guards to a header file is one way to make that file idempotent. Another construct to combat double inclusion is #pragma once, which is non-standard but nearly universally supported among C and C++ compilers.
Double inclusion
Example
The following C code demonstrates a real problem that can arise if #include guards are missing:
File "grandparent.h"
struct foo {
int member;
};
File "parent.h"
#include "grandparent.h"
File "child.c"
#include "grandparent.h"
#include "parent.h"
Result
struct foo {
int member;
};
struct foo {
int member;
};
Here, the file "child.c" has indirectly included two copies of the text in the header file "grandparent.h". This causes a compilation error, since the structure type foo
will thus be defined twice. In C++, this would be called a violation of the one definition rule.
Use of #include guards
Example
In this section, the same code is used with the addition of #include guards. The C preprocessor preprocesses the header files, including and further preprocessing them recursively. This will result in a correct source file, as we will see.
File "grandparent.h"
#ifndef GRANDPARENT_H
#define GRANDPARENT_H
struct foo {
int member;
};
#endif /* GRANDPARENT_H */
File "parent.h"
#include "grandparent.h"
File "child.c"
#include "grandparent.h"
#include "parent.h"
Result
struct foo {
int member;
};
Here, the first inclusion of "grandparent.h" has the macro GRANDPARENT_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 of struct foo
. The program compiles correctly.
Discussion
Different naming conventions for the guard macro may be used by different programmers. Other common forms of the above example include GRANDPARENT_INCLUDED
, CREATORSNAME_YYYYMMDD_HHMMSS
(with the appropriate time information substituted), and names generated from a UUID. (However, names starting with one underscore and a capital letter (C and C++) or any name containing double underscore (C++ only), such as _GRANDPARENT_H
and GRANDPARENT__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.
Difficulties
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]
Other languages
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
:
- PL/I uses the
%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] - Objective-C's
#import
directive (see above) - PHP's
include_once
[5]
See also
References
- ↑ C++ standard (ISO/IEC 14882) section 17.4.3.1.2/1
- ↑ C standard (ISO/IEC 9899) section 7.1.3/1.
- ↑ Шаблон:Cite web
- ↑ Шаблон:Cite book
- ↑ Шаблон:Cite web
External links