cpp.info: Once-Only Headers
Go forward to Computed Includes
Go backward to Search Path
Go up to Header Files
Go to the top op cpp
If a header file happens to be included twice, the compiler will
process its contents twice. This is very likely to cause an error,
e.g. when the compiler sees the same structure definition twice. Even
if it does not, it will certainly waste time.
The standard way to prevent this is to enclose the entire real
contents of the file in a conditional, like this:
/* File foo. */
THE ENTIRE FILE
#endif /* !FILE_FOO_SEEN */
This construct is commonly known as a "wrapper #ifndef". When the
header is included again, the conditional will be false, because
`FILE_FOO_SEEN' is defined. The preprocessor will skip over the entire
contents of the file, and the compiler will not see it twice.
GNU CPP optimizes even further. It remembers when a header file has
a wrapper `#ifndef'. If a subsequent `#include' specifies that header,
and the macro in the `#ifndef' is still defined, it does not bother to
rescan the file at all.
You can put comments outside the wrapper. They will not interfere
with this optimization.
The macro `FILE_FOO_SEEN' is called the "controlling macro" or
"guard macro". In a user header file, the macro name should not begin
with `_'. In a system header file, it should begin with `__' to avoid
conflicts with user programs. In any kind of header file, the macro
name should contain the name of the file and some additional text, to
avoid conflicts with other header files.
Created Mon Nov 8 17:42:10 2004 on tillpc with info_to_html version 0.9.6.