41

I know this is a common question but I still can't fully get my head around it.

In a C or C++ program generated from multiple different source and header files, will each header file be only included once in the entire code when the header guards are used?

Someone told me previously that a header file (with include guards) will get included only once in one translation unit but multiple times in the entire code. Is this true?

If it gets included only once throughout the entire code, when one file wishes to include it and the preprocessor detects that it has already been included, how does that file that wishes to use it know whereabouts in the code it was previously included ?

4
  • 9
    "a header file (with include guards) will get included only once in one translation unit but multiple times in the entire code. Is this true?" Yes. Not once per program, it is (at most) once per translation unit. Commented Jun 16, 2015 at 16:30
  • 7
    With include guards, the header can still be included several times even in one translation unit - but most of it (the part within the guards) will be skipped after the first time. The preprocessor doesn't care where it was previously included... only whether the guard's macro has been defined yet (which happens the first time it's included if the guards are set up properly).
    – Dmitri
    Commented Jun 16, 2015 at 16:38
  • @Engineer999: If an answer helped, please do not forget to accept one. That's how this site works. Commented Jul 23, 2015 at 12:28
  • @MichaelGaskill I think it should be obvious from the level of detail of questions and answers, that this is not a duplicate.
    – Zulan
    Commented Jun 12, 2016 at 6:20

4 Answers 4

55

This is the process:

source           header   source header header
   \           /        \   |      /   /
    \         /          \  |     /   /
  PREPROCESSOR            PREPROCESSOR
       |                      |
       V                      V
 preprocessed code      preprocessed code
       |                      |
    COMPILER               COMPILER
       |                      |
       V                      V
  object code              object code
             \            /
              \          /
               \        /
                 LINKER
                   | 
                   V
               executable

Preprocessing

#include is for this first step. It instructs the preprocessor to processes the specified file, and insert the result into the output.

If A includes B and C, and B includes C, the preprocessor's output for A will include the processed text of C twice.

This is a problem, since it will result in duplicate declarations. A remedy is to use preprocessor variables track whether the source code has been included (aka header guards).

#ifndef EXAMPLE_H
#define EXAMPLE_H

// header contents

#endif

The first time, EXAMPLE_H is undefined, and the preprocessor will evaluate the contents within the ifndef/endif block. The second time, it will skip that block. So the processed output changes, and the definitions are included only once.

This is so common that there is a non-standard directive implemented by some compilers that is shorter and does not require choosing a unique preprocessor variable:

#pragma once

// header contents

You can figure out how portable you want your C/C++ code, and which header guard to use.

Headers guards will ensure the contents of each header file are present at most once in the preprocessed code for a translation unit.

Compiling

The compiler generates machine code from your preprocessed C/C++.

Generally, the header files only include declarations, not the actual definitions (aka implementations). The compiler includes a symbol table for anything that is currently missing a definition.

Linking

The linker combines the object files. It matches up the definitions (aka implementations) with the references to the symbol table.

It may be that two object files provide the definition, and the linker will take one. This happens if you've put executable code in your headers. This generally does not happen in C, but it happens very frequently in C++, because of templates.

The header "code", whether declarations or definitions, is included multiple times across all object files but the linker merges all of that together, so that it is only present once in the executable. (I'm excluding inlined functions, which are present multiple times.)

4
  • Excellent reply, but shouldn't you say "Generally, the header files only include declarations, not the actual implementations." since definitions are generally synonymous with implementations in c/c++?
    – Bryan Shaw
    Commented Jun 17, 2015 at 20:48
  • @BryanShaw, that has been fixed. Commented Jan 20, 2019 at 3:11
  • Fantastic reply! Exactly what I'm look for!
    – xwa130
    Commented Sep 9, 2020 at 5:05
  • Excellent answer! Well explained, thanks!
    – sai
    Commented Feb 18, 2021 at 9:50
17

A "header file" is actually inserted by the pre-processor before compilation starts. Just think of it as just "replacing" its #include directive.

The guard ...

#ifndef MY_HEADER_H
#define MY_HEADER_H

// the "guarded" part of the header file is here...

#endif

... is executed after the replacement. So, the header may actually be included multiple times, but the "guarded" part of the text is only passed to the compiler once by the preprocessor.

So, if there are any code-generation definitions in the header, they will - of course - be included into the object file of the compilation unit (aka "module"). If the same header is #includeded in multiple modules, these will appear multiple times.

For static definitions, this is no problem at all, as these will not be visible beyond the module (aka file scope). For program-global definitions, that is different and will result in "multiple definitions" error.

Note: this is mostly for C. For C++, there are significant differences, as classes, etc. add additional complexity to what/when multiple global objects are allowed.

6
  • 3
    you could also mention the non-standard #pragma once, it's worth knowing its existence
    – dlavila
    Commented Jun 16, 2015 at 16:47
  • 3
    @dlavila: I did not for a purpose. One should not rely on it, so you have to ad the guards anyway. Also, this might defy libraries like boost which intentionally use multiple includes. (I'm not to always stick to the standard, but link-once has too little benefit and can cause much trouble). Commented Jun 16, 2015 at 16:51
  • 5
    is worth knowing its existence anyway, not as a replacement, but sometimes it can be very useful, e.g: if you are sure it's supported (SWE guys in your company told you that) and you are working in a project with thousands of headers (compilation time can be speed up a lot).
    – dlavila
    Commented Jun 16, 2015 at 17:01
  • 1
    In the case of C++, aren't we supposed to put template class and function definitions into the header file only. In that case won't there be multiple definitions of the same functions throughout the program which is not allowed? Commented Jun 16, 2015 at 19:19
  • 1
    @Engineer999: That's why I wrote my answer is mostly for C. It's some time ago when I programmed in C++, I just emember it is more complicated, e.g. with inline methods or constants - these are different from C. It is always problemeatic to cover these two languages with a single question. They are different languages. If you cannot extrapolate my answer, it might be a good idea to delete the C++-tag and ask again for C++ only. Commented Jun 16, 2015 at 19:45
7

A header file with appropriate include guards will be included only once per translation unit. Strictly speaking, it may be included multiple times, but the parts between the preprocessor #ifndef and #endif will be skipped on subsequent inclusions. If done correctly, this should be all (or most) of the file.

A translation unit usually corresponds to a "source file", although some obscure implementations may use a different definition. If a separately compiled source file includes the same header, the preprocessor has no way of knowing that another file had already included it, or that any other file was part of the same project.

Note that when you come to link together multiple source files (translation units) into a single binary, you may encounter problems with multiple definitions if the header does not consist only of declarations, templates, function definitions that are marked inline, or static variable definitions. To avoid this, you should declare functions in the header and define them in a separate source file, which you link together with your other source files.

1
  • yes, this static declaration is important. in linux source there are many 'static inline' functions defined in the header files. even though they are used in multiple object files, it gives us no 'multiple definition' error during the linking process because of the 'static' nature.
    – Chan Kim
    Commented May 22, 2020 at 1:36
5

The header file will be included once per translation unit, yes. It can be included multiple times per program, as each translation unit is handled separately for the compile process. They are brought together during the linking process to form a complete program.

4
  • What will happen if we have the function definitions in the header file. Won't there be many definitions of the same function throughout the program which is not allowed? Commented Jun 16, 2015 at 19:16
  • @Engineer999 Function definitions are not typically included in header files, except for inline functions
    – Random832
    Commented Jun 16, 2015 at 19:25
  • Aren't functions implicitly inline if they are defined inside a class body in a header file (C++ of course) . How are the multiple definitions dealt with then? Commented Jun 16, 2015 at 19:44
  • @Engineer999 Inline functions are designed not to cause problems when included multiple times - either they will not have a definition at all in the final output, or the linker will know to throw away all but one of them.
    – Random832
    Commented Jun 17, 2015 at 4:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.