What are actual use cases for double header inclusion in C?

Question

Inclusion guards (as well as the #pragma once) in C header files are frequently used and well described in a wikipedia article and a way to prevent mistakingly double include a header file.

This questions asks in which cases it would be desired, in C programming, to make a double inclusion after all?

update This is not to suggest that I assume a priori that there was a good reason (some sort of preprocessor magic) worthwhile the negative effect of know requiring each programmer the overhead of generating include guards. It seems odd that the preprocessor behaves so inconveniently and I though there must be a valid reason? The question ask for such reasons, i.e. usefulness of a double inclusion

update 2 As a paraphrase to the question I would assume the following question:

Is the double inclusion problem (solved by include guards & #pragma once) simply a preprocessor imperfection, which its causes being sorts of historical?

Answer 1

There is no imperfection. Including a file as many times as a #include statement is found is what it should do.

Check chapter 7.2 of the standard:

The assert macro is redefined according to the current state of NDEBUG each time that assert.h is included.

This implies that you could use it like this:

#define NDEBUG
#include <assert.h>
assert( <expr1> );

#undef NDEBUG
#include <assert.h>
assert( <expr2> );

Whether this is very useful or not may be a different story.

You could also use your header to define something similar to X-Macros in a header.

header.h

  ELEMENT(x, _a_, _b_)
  ELEMENT(y, _a_, _b_)
  ELEMENT(z, _a_, _b_)

source.c

#define ELEMENT(_x_, _a_, _b_) printf("%s: %d, %d", _x_, _a_, _b_);
  #include <header.h>

#define ELEMENT(_x_, _a_, _b_) {_x_, _a_, _b_},
struct something xy[] = {
  #include <header.h>
};

There might be cases where it cannot be solved by X-Macros

Answer 2

The #include directive is not limited to headers. There is an uncommon practice of including prepared blocks of executable code in the middle of source code.

For example:

max = calculateMax(a, b, c);
#include "debug-helper.c"; // NOTE: It may be cleaner to organize helper into functions
...

This would not work correctly (i.e. in all cases) with implicit and obligatory header guards.

Answer 3

Is the double inclusion problem (solved by include guards & #pragma once) simply a preprocessor imperfection, which its causes being sorts of historical?

There is no double inclusion problem; rather, there is a multiple definition problem. Though it depends on the content of the header, without multiple-inclusion guards it would be relatively common for multiple inclusion of the same header to effect disallowed multiple definition of one or more identifiers. The convention of using multiple-inclusion guards was developed to protect against that, and it has become routine practice even for headers that don't actually present a multiple-inclusion problem.

Functions and objects should not be defined in headers, though declaring these in headers is one of headers' main use cases. It's fairly easy to avoid that aspect of the issue. It used to be the case, however, that it was an technically an error to redeclare the same typedef name, even with an identical definition, and some pre-standardization compilers rejected even identical redefinition of macros. Neither of these is an issue in modern C (C2011).

What does remain an issue is redefinition of struct, union, and enum types -- this is still disallowed, even if the redefinition changes nothing. Secondarily, it is not uncommon for the meaning of the contents of a header file to be dependent on symbols that may be defined elsewhere in the translation unit. If such a header's contents are included more than once in the TU then it is possible for them to have different meaning on the two inclusions. That can lead to incompatible multiple declarations.

The point to be understood is that whether multiple-inclusion of the contents of a given header is wrong is a function of those contents.

Additionally, I already described how conditional compilation makes it possible for the meaning of a header to differ depending on where it is included relative to the rest of the translation unit. Although this can contribute to producing disallowed incompatible declarations or multiple definitions, it can also produce perfectly valid code.

TL;DR: multiple inclusion of header files is not inherently wrong, and can serve a useful purpose. It is therefore not a flaw that the C preprocessor does not automatically protect against multiple inclusion. It is reasonable for the responsibility to rest on the contents of each header to exhibit suitable behavior when that header is included more than once into the same translation unit.

Answer 4

One place where I've used multiple includes of the same file is as a glorified super-sized macro.

#define ARG1 "First arg"
#define ARG2 345
#include "run.macro"

The "run.macro" file would then undefine ARG1 and ARG2 when its finished, so it can be used all over the place.

I've used this trick to refactor a large system of macros into something much more manageable (and far better commented), though in the longer term I continued to refactor it until it was removed entirely.

In short, it can be useful for refactoring, but I wouldn't recommend it as a general practice.