The #include Directive


#include "[path-spec]"

#include < [path-spec] >

The general syntax of preprocessor directives applies as far as ending include. Thereafter, the first token must be either a string constant or a less-than sign. Any other type of token is an error (C2006).

In the first form shown above, the string constant has path-spec enclosed in double quotes. A wide-character constant is an error (C2002). The path-spec is optional in the sense that an empty string is permitted.

In the second form, the less-than token may be followed by any amount of white space, including none. The optional path-spec then begins and continues up to and including the last character that is not white space immediately before a greater-than sign. It is an error (C2012) if there is nothing but white space after the less-than token. It is an error (C2013) if there is no greater-than sign after the less-than token. If there is nothing but white space between the less-than token and the greater-than sign, then path-spec is empty.

Translation Precedence

In the form with double-quotes, the #include argument is fully tokenised. It is therefore unremarkable, except perhaps to stress that the argument provides for just one string constant, as one token, not as a concatenation of tokens.

The other form (with angle-brackets) is tokenised only at its start. This is enough so that the less-than token and subsequent characters may be produced by macro expansion. For example, the path-spec for

#include    TEST_HEADER

can be set from the command line through some such option as

/D TEST_HEADER="<test.h>"

and varied without having to edit the source file. The macro expansion may produce the whole of the #include argument, as in the preceding example, or just an initial portion. For example,

#define     TEST    <test

#include    TEST.h>

though contrived, is valid.