Skip to content
Tutorials Center
My learning

Topics

C Reference ยท Preprocessor

Include guards

Reference for C include guards: how #ifndef/#define/#endif and #pragma once stop a header from being processed twice, with naming rules and pitfalls.

An include guard makes a header safe to include more than once in the same translation unit. Without one, a header that defines a struct or a typedef breaks as soon as two other headers both include it: the compiler sees the same definition twice and reports a redefinition error.

The classic guard wraps the whole header in #ifndef NAME / #define NAME / #endif. The first time the file is seen, NAME is not defined, so the contents are processed and NAME gets defined. Every later inclusion skips straight to #endif.

C
#ifndef GEOMETRY_H
#define GEOMETRY_H

typedef struct { double x, y; } Point;

#endif /* GEOMETRY_H */

Try it

A single-file demonstration: the guarded block below is pasted twice, which is exactly what two inclusions of a header look like after preprocessing. Without the guard, the second copy would be a redefinition error.

C The guard in action

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C A guard name clash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Choosing a guard

The #ifndef form

This form is part of the standard and works with every compiler, file system and build setup. Its weakness is that the macro name must be unique across the whole project. Derive it from the path or project name, in capitals: MYLIB_GEOMETRY_H is safer than GEOMETRY_H, because two headers named util.h in different libraries would otherwise silently disable each other. Do not start the name with an underscore followed by a capital or with two underscores; those names are reserved for the implementation.

#pragma once

C
#pragma once

typedef struct { double x, y; } Point;

#pragma once is not in the C standard (even in C23), but GCC, Clang, MSVC and every other mainstream compiler support it. It is shorter, cannot suffer a name clash, and may compile slightly faster because the compiler can skip reopening the file. Its drawbacks are theoretical: it identifies a file by its location, which can go wrong with the same file reachable under two names (some network file systems, symbolic or hard links, copied directories).

Many projects use both, or just the #ifndef form when portability to unusual compilers matters.

Usage notes

  • Place the guard around everything. Put the #ifndef before any declarations and the #endif at the end. Content outside the guard is processed on each inclusion.
  • Guards solve duplicates inside one translation unit. They do not stop a header from being compiled once per .c file; that is normal, which is why headers should hold declarations, not definitions of functions and variables (see header files).
  • Do not guard a header that is meant to be included repeatedly. X-macro lists and assert.h rely on being processed again with different macro settings (assert.h behaves differently each time depending on NDEBUG).
  • Match #define to #ifndef exactly. A typo in the second name leaves the guard ineffective, and the compiler does not warn. GCC and Clang offer -Wheader-guard style checks in some tools.
  • Comment the #endif. A trailing /* NAME */ helps when a header grows to hundreds of lines.
  • Circular includes. A guard stops infinite recursion between two headers that include each other, but the second one then sees an incomplete first one. Break cycles with forward declarations (struct Node;).
  • Source files need no guard. Only headers get included by others.