--- gcc/cpp.texinfo 2018/04/24 16:38:22 1.1.1.2 +++ gcc/cpp.texinfo 2018/04/24 16:50:39 1.1.1.5 @@ -277,7 +277,9 @@ This variant is used for system header f named @var{file} in a list of directories specified by you, then in a standard list of system directories. You specify directories to search for header files with the command option @samp{-I} -(@pxref{Invocation}). +(@pxref{Invocation}). The option @samp{-nostdinc} inhibits searching +the standard system directories; in this case only the directories +you specify are searched. The parsing of this form of @samp{#include} is slightly special because comments are not recognized within the @samp{<@dots{}>}. @@ -292,11 +294,12 @@ however, contain a @samp{<} character. @item #include "@var{file}" This variant is used for header files of your own program. It -searches for a file named @var{file} first in the current working +searches for a file named @var{file} first in the current directory, then in the same directories used for system header -files. The current working directory is tried first because it is +files. The current directory is tried first because it is presumed to be the location of the files of the program being -compiled. +compiled. (If the @samp{-I-} option is used, the special treatment +of the current directory is inhibited.) The argument @var{file} may not contain @samp{"} characters. If backslashes occur within @var{file}, they are considered ordinary text @@ -675,8 +678,8 @@ if a @samp{#line} command is used. @xre @findex __DATE__ This macro expands to a string constant that describes the date on which the preprocessor is being run. The string constant contains -eleven characters and looks like @samp{"Jan 29 1987"} or @samp{"Apr -@ 1 1905"}. +eleven characters and looks like @samp{"Jan 29 1987"} or @w{@samp{"Apr +1 1905"}}. @item __TIME__ @findex __TIME__ @@ -1120,7 +1123,7 @@ a = (b & c + sizeof (int) - 1) / sizeof @noindent which does not do what is intended. The operator-precedence rules of -C make it equivalent to this: +C make it equivalent to this: @example a = (b & (c + sizeof (int) - 1)) / sizeof (int); @@ -1380,10 +1383,7 @@ what happens. The self-references that marked so that they will not expand in the second scan either. The prescan is not done when an argument is stringified or concatenated. -(More precisely, stringification and concatenation use the argument as -written, in un-prescanned form. The same actual argument would be used in -prescanned form if it is substituted elsewhere without stringification or -concatenation.) Thus, +Thus, @example #define str(s) #s @@ -1395,9 +1395,22 @@ str (foo) expands to @samp{"foo"}. Once more, prescan has been prevented from having any noticeable effect. +More precisely, stringification and concatenation use the argument as +written, in un-prescanned form. The same actual argument would be used in +prescanned form if it is substituted elsewhere without stringification or +concatenation. + +@example +#define str(s) #s lose(s) +#define foo 4 +str (foo) +@end example + +expands to @samp{"foo" lose(4)}. + You might now ask, ``Why mention the prescan, if it makes no difference? -Why not skip it and make the preprocessor faster?'' The answer is that the -prescan does make a difference in two special cases: +And why not skip it and make the preprocessor faster?'' The answer is +that the prescan does make a difference in three special cases: @itemize @bullet @item @@ -1405,6 +1418,9 @@ Nested calls to a macro. @item Macros that call other macros that stringify or concatenate. + +@item +Macros whose expansions contain unshielded commas. @end itemize We say that @dfn{nested} calls to a macro occur when a macro's actual @@ -1420,6 +1436,52 @@ be expanded. Here, the prescan cancels (in the medical, not computational, sense of the term) of the special rule for self-referential macros. +But prescan causes trouble in certain other cases of nested macro calls. +Here is an example: + +@example +#define foo a,b +#define bar(x) lose(x) +#define lose(x) (1 + (x)) + +bar(foo) +@end example + +@noindent +We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which +would then turn into @samp{(1 + (a,b))}. But instead, @samp{bar(foo)} +expands into @samp{lose(a,b)}, and you get an error because @code{lose} +requires a single argument. In this case, the problem is easily solved +by the same parentheses that ought to be used to prevent misnesting of +arithmetic operations: + +@example +#define foo (a,b) +#define bar(x) lose((x)) +@end example + +The problem is more serious when the operands of the macro are not +expressions; for example, when they are statements. Then parentheses +are unacceptable because they would make for invalid C code: + +@example +#define foo @{ int a, b; @dots{} @} +@end example + +@noindent +In GNU C you can shield the commas using the @samp{(@{@dots{}@})} +construct which turns a compound statement into an expression: + +@example +#define foo (@{ int a, b; @dots{} @}) +@end example + +Or you can rewrite the macro definition to avoid such commas: + +@example +#define foo @{ int a; int b; @dots{} @} +@end example + There is also one case where prescan is useful. It is possible to use prescan to expand an argument and then stringify it---if you use two levels of macros. Let's add a new macro @samp{xstr} to the @@ -1964,6 +2026,27 @@ header file directories. If you use mor the directories are scanned in left-to-right order; the standard system directories come after. +@item -I- +Any directories specified with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +directives. + +In addition, the @samp{-I-} option inhibits the use of the current +directory as the first search directory for @samp{#include "@var{file}"}. +Therefore, the current directory is searched only if it is requested +explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.} +allows you to control precisely which directories are searched before +the current one and which are searched after. + +@item -nostdinc +Do not search the standard system directories for header files. +Only the directories you have specified with @samp{-I} options +(and the current directory, if appropriate) are searched. + @item -D @var{name} @findex -D Predefine @var{name} as a macro, with definition @samp{1}.