Include guard

The correct title of this article is #include guard. The omission of the # is due to technical restrictions.

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.

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

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"

#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"

Intermediate step

#ifndef GRANDPARENT_H // GRANDPARENT_H is not defined
#define GRANDPARENT_H

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

#endif /* GRANDPARENT_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

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

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.) [4]
  • Objective-C's #import directive (see above)
  • PHP's include_once[5]

See also

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. ^ "Objective C: Defining Classes". developer.apple.com. 2014-09-17. Retrieved 2018-10-03.
  4. ^ IBM Corporation (August 2017). Enterprise PL/I for z/OS PL/I for AIX Enterprise PL/I for z/OS Language Reference Version 5 Release 1 (PDF). p. 257. Retrieved Apr 7, 2022.
  5. ^ "include_once (PHP Language Reference)".