Include guard

Quality 0.50 · 0 views · Updated 2 months ago

Construct in C and C++

title: "Include guard" type: doc version: 1 created: 2026-02-28 author: "Wikipedia contributors" status: active scope: public tags: ["c-(programming-language)-headers"] description: "Construct in C and C++" topic_path: "general/c-programming-language-headers" source: "https://en.wikipedia.org/wiki/Include_guard" license: "CC BY-SA 4.0" wikipedia_page_id: 0 wikipedia_revision_id: 0

::summary Construct in C and C++ ::

In the C and C++ programming languages, an #include guard, sometimes called a macro guard, header guard or file guard, is a way to avoid the problem of double inclusion when dealing with the include directive.

The C preprocessor processes inclusion directives like #include "Foo.h" to include "Foo.h" and transcludes the code of that file into a copy of the main file often called the translation 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 a compilation error due to the One 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 a preprocessor 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 in C++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 a translation unit.

Double inclusion

Example

The following C code demonstrates a real problem that can arise if #include guards are missing:

File "Grandparent.h"

::code[lang=c] struct Foo { int member; }; ::

File "Parent.h"

::code[lang=c] #include "Grandparent.h"

::

File "Child.c"

::code[lang=c] #include "Grandparent.h" #include "Parent.h"

::

Result

::code[lang=c] struct Foo { // From "Grandparent.h" int member; }; struct Foo { // From "Parent.h" 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|one definition rule]]. ::

Use of #include guards

Example

The same code as the previous section 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 working source file.

File "Grandparent.h"

::code[lang=c] #ifndef GRANDPARENT_H #define GRANDPARENT_H

struct Foo { int member; };

#endif /* GRANDPARENT_H */ ::

File "Parent.h"

::code[lang=c] #include "Grandparent.h" ::

File "Child.c"

::code[lang=c] #include "Grandparent.h" #include "Parent.h" ::

Intermediate step

::code[lang=c] // Contents from "Grandparent.h" #ifndef GRANDPARENT_H // GRANDPARENT_H is not defined #define GRANDPARENT_H

struct Foo { // This definition is compiled int member; };

#endif /* GRANDPARENT_H */

// Contents from "Parent.h" #ifndef GRANDPARENT_H // GRANDPARENT_H is already defined #define GRANDPARENT_H

struct Foo { // This definition is not compiled int member; };

#endif /* GRANDPARENT_H */ ::

Result

::code[lang=c]

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

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](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](objective-c-import) directive, which works exactly like #include, except that it includes each file only once, thus obviating the need for #include guards.

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 an XPROCEDURE statement, similar to a PROCEDURE statement, which will ignore the second and subsequent occurrences of an XPROCEDURE with the same name.)
  • Objective-C's #import directive (see above)
  • PHP's include_once

References

References

  1. C++ standard (ISO/IEC 14882) section 17.4.3.1.2/1
  2. C standard (ISO/IEC 9899) section 7.1.3/1.
  3. (2014-09-17). "Objective C: Defining Classes".
  4. (August 2017). "Enterprise PL/I for z/OS PL/I for AIX Enterprise PL/I for z/OS Language Reference Version 5 Release 1".
  5. "include_once (PHP Language Reference)".

::callout[type=info title="Wikipedia Source"] This article was imported from Wikipedia and is available under the Creative Commons Attribution-ShareAlike 4.0 License. Content has been adapted to SurfDoc format. Original contributors can be found on the article history page. ::

c-(programming-language)-headers