Home      Discussion      Topics      Dictionary      Almanac
Signup       Login
Include guard

Include guard

Discussion
Ask a question about 'Include guard'
Start a new discussion about 'Include guard'
Answer questions from other users
Full Discussion Forum
 
Encyclopedia
In the C
C (programming language)
C is a general-purpose computer programming language developed between 1969 and 1973 by Dennis Ritchie at the Bell Telephone Laboratories for use with the Unix operating system....

 and C++
C++
C++ is a statically typed, free-form, multi-paradigm, compiled, general-purpose programming language. It is regarded as an intermediate-level language, as it comprises a combination of both high-level and low-level language features. It was developed by Bjarne Stroustrup starting in 1979 at Bell...

 programming languages, an #include guard, sometimes called a macro guard, is a particular construct used to avoid the problem of double inclusion when dealing with the #include directive. The addition of #include guards to a header file
Header file
Some programming languages use header files. These files allow programmers to separate certain elements of a program's source code into reusable files. Header files commonly contain forward declarations of classes, subroutines, variables, and other identifiers...

 is one way to make that file idempotent.

Double inclusion


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

File "grandfather.h"

struct foo {
int member;
};


File "father.h"
  1. include "grandfather.h"



File "child.c"
  1. include "grandfather.h"
  2. include "father.h"



Here, the file "child.c" has indirectly included two copies of the text in the header file
Header file
Some programming languages use header files. These files allow programmers to separate certain elements of a program's source code into reusable files. Header files commonly contain forward declarations of classes, subroutines, variables, and other identifiers...

 "grandfather.h". This causes a compilation error, since the structure type foo is apparently defined twice. In C++, this would be a violation of the One Definition Rule
One Definition Rule
The One Definition Rule is an important concept in the C++ programming language. It's defined in the ISO C++ Standard 2003, at section 3.2.- Summary :In short the ODR states that:...

.

Use of #include guards


File "grandfather.h"
  1. ifndef GRANDFATHER_H
  2. define GRANDFATHER_H


struct foo {
int member;
};
  1. endif



File "father.h"
  1. include "grandfather.h"



File "child.c"
  1. include "grandfather.h"
  2. include "father.h"



Here, the first inclusion of "grandfather.h" causes the macro GRANDFATHER_H to be defined. Then, when "child.c" includes "grandfather.h" the second time, the #ifndef test returns false, and the preprocessor skips down to the #endif, thus avoiding the second definition of struct foo. The program compiles correctly.

Different naming conventions
Naming conventions (programming)
In computer programming, a naming convention is a set of rules for choosing the character sequence to be used for identifiers which denote variables, types and functions etc...

 for the guard macro may be used by different programmers. Other common forms of the above example include GRANDFATHER_INCLUDED, CREATORSNAME_YYYYMMDD_HHMMSS (with the appropriate time information substituted), and names generated from a UUID
Universally Unique Identifier
A universally unique identifier is an identifier standard used in software construction, standardized by the Open Software Foundation as part of the Distributed Computing Environment ....

. (However, names starting with one or two underscores, such as _GRANDFATHER_H and __GRANDFATHER_H, are reserved to the implementation and must not be used by the user.) It is important to avoid the common pitfall of duplicating the name in a different file (even one in a different project), which defeats the purpose of include guards.

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
Pragma once
In the C and C++ programming languages, #pragma once is a non-standard but widely supported preprocessor directive designed to cause the current source file to be included only once in a single compilation...

. 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, via a symbolic link
Symbolic link
In computing, a symbolic link is a special type of file that contains a reference to another file or directory in the form of an absolute or relative path and that affects pathname resolution. Symbolic links were already present by 1978 in mini-computer operating systems from DEC and Data...

 on Unix-like
Unix-like
A Unix-like operating system is one that behaves in a manner similar to a Unix system, while not necessarily conforming to or being certified to any version of the Single UNIX Specification....

 systems). Also, since #pragma once is not a standard directive, its semantics may be subtly different on different implementations. The Objective-C
Objective-C
Objective-C is a reflective, object-oriented programming language that adds Smalltalk-style messaging to the C programming language.Today, it is used primarily on Apple's Mac OS X and iOS: two environments derived from the OpenStep standard, though not compliant with it...

 language (which is a superset of C) introduced an #import directive, which works exactly like #include, except that it only includes each file once, thus obviating the need for #include guards.

Another solution to this problem is to simply not include header files from other header files. This, however, has its own yawning pitfalls -- particularly when the headers are subject to changing requirements (development).

See also

  • #pragma once
    Pragma once
    In the C and C++ programming languages, #pragma once is a non-standard but widely supported preprocessor directive designed to cause the current source file to be included only once in a single compilation...

  • C preprocessor
    C preprocessor
    The C preprocessor is the preprocessor for the C and C++ computer programming languages. The preprocessor handles directives for source file inclusion , macro definitions , and conditional inclusion ....

  • Circular dependency
    Circular dependency
    In software engineering, a circular dependency is a relation between two or more modules which either directly or indirectly depend on each other to function properly.-Overview:...


External links