standard uses the term @dfn{string literal} to refer only to what we are
calling @dfn{string constants}.} String constants and character
constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In
-either case the closing quote may be escaped with a backslash:
+either case embedded quotes should be escaped with a backslash:
@t{'\'@:'} is the character constant for @samp{'}. There is no limit on
the length of a character constant, but the value of a character
constant that contains more than one character is
Operation}.
In standard C, no string literal may extend past the end of a line. GNU
-CPP accepts multi-line string constants, but not character constants or
-header file names. This extension is deprecated and will be removed in
-GCC 3.1. You may use continued lines instead, or string constant
-concatenation. @xref{Differences from previous versions}.
+CPP accepts multi-line string constants, but not multi-line character
+constants or header file names. This extension is deprecated and will
+be removed in GCC 3.1. You may use continued lines instead, or string
+constant concatenation. @xref{Differences from previous versions}.
@cindex punctuators
@dfn{Punctuators} are all the usual bits of punctuation which are
or warnings.
@end itemize
-There are a few more, less useful features.
+There are a few more, less useful, features.
Except for expansion of predefined macros, all these operations are
triggered with @dfn{preprocessing directives}. Preprocessing directives
@option{-I./-}.
There are several more ways to adjust the header search path. They are
-less generally useful. @xref{Invocation}.
+generally less useful. @xref{Invocation}.
@node Once-Only Headers
@section Once-Only Headers
@var{the entire file}
-#endif /* FILE_FOO_SEEN */
+#endif /* !FILE_FOO_SEEN */
@end group
@end example
like running text would be.
If the line expands to a single string constant, the contents of that
-string constant are the file to be included. CPP does not reexamine the
+string constant are the file to be included. CPP does not re-examine the
string for embedded quotes, but neither does it process backslash
escapes in the string. Therefore
standard. To minimize the risk of different compilers interpreting your
computed includes differently, we recommend you use only a single
object-like macro which expands to a string constant. This will also
-minimize confusion of people reading your program.
+minimize any confusion to people reading your program.
@node Wrapper Headers
@section Wrapper Headers
The use of @samp{#include_next} can lead to great confusion. We
recommend it be used only when there is no other alternative. In
-particular, it should not be used in the headers belonging to a
-specific program, only to make global corrections along the lines
-of @command{fixincludes}.
+particular, it should not be used in the headers belonging to a specific
+program; it should be used only to make global corrections along the
+lines of @command{fixincludes}.
@node System Headers
@section System Headers
The @option{-isystem} command line option adds its argument to the list of
directories to search for headers, just like @option{-I}. Any headers
-found in that directory will be considered system headers. Note that
-unlike @option{-I}, you must put a space between @option{-isystem} and its
-argument.
+found in that directory will be considered system headers.
All directories named by @option{-isystem} are searched @emph{after} all
directories named by @option{-I}, no matter what their order was on the
(Line breaks shown here for clarity would not actually be generated.)
@cindex empty macro arguments
-You can leave macro arguments empty; this is not an error for the
+You can leave macro arguments empty; this is not an error to the
preprocessor (but many macros will then expand to invalid code).
You cannot leave out arguments entirely; if a macro takes two arguments,
there must be exactly one comma at the top level of its argument list.
function-like macro that takes a single argument be passed a space if an
empty argument was required.
-Macro parameters are not replaced by their corresponding actual
-arguments if they appear inside string literals.
+Macro parameters appearing inside string literals are not replaced by
+their corresponding actual arguments.
@example
#define foo(x) x, "x"
There is no way to combine an argument with surrounding text and
stringify it all together. Instead, you can write a series of adjacent
string constants and stringified arguments. The preprocessor will
-replace the stringified arguments with more string constants. The C
+replace the stringified arguments with string constants. The C
compiler will then combine all the adjacent string constants into one
long string.
@ref{Swallowing the Semicolon}.
Stringification in C involves more than putting double-quote characters
-around the fragment. The preprocessor backslash-escapes the surrounding
-quotes of string literals, and all backslashes within string and
+around the fragment. The preprocessor backslash-escapes the quotes
+surrounding embedded string constants, and all backslashes within string and
character constants, in order to get a valid C string constant with the
proper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in
@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string
@expansion{} fprintf(stderr, "success!\n", );
@end example
-GNU CPP has a pair of extensions which deal with this problem. First,
+GNU CPP has a pair of extensions which deals with this problem. First,
you are allowed to leave the variable argument out entirely:
@example
same as the old one, the preprocessor issues a warning and changes the
macro to use the new definition. If the new definition is effectively
the same, the redefinition is silently ignored. This allows, for
-instance, two different headers to define a common macro. The compiler
-will only complain if the definitions do not match.
+instance, two different headers to define a common macro. The
+preprocessor will only complain if the definitions do not match.
@node Macro Pitfalls
@section Macro Pitfalls
In this section we describe some special rules that apply to macros and
macro expansion, and point out certain cases in which the rules have
-counterintuitive consequences that you must watch out for.
+counter-intuitive consequences that you must watch out for.
@menu
* Misnesting::
following line and all subsequent lines are reported to come from the
file it specifies, until something else happens to change that.
-@item #line @var{linenum} @var{filename} @var{flags@dots{}}
-This form is a GCC extension. @var{linenum} and @var{filename} are the
-same as the second form. The @var{flags} are small positive integers,
-which have the same meaning as the flags which can appear at the end of a
-linemarker in the preprocessor's output. @xref{Preprocessor Output}.
-
@item #line @var{anything else}
@var{anything else} is checked for macro calls, which are expanded.
The result should match one of the above three forms.
+
+@item # @var{linenum} @var{filename} @var{flags@dots{}}
+This form is a GCC extension. @var{linenum} and @var{filename} are the
+same as the second form. The @var{flags} are small increasing positive
+integers, which have the same meaning as the flags which can appear at
+the end of a linemarker in the preprocessor's output.
+@xref{Preprocessor Output}. Note that this form does not use the
+directive name @samp{line}.
@end table
@samp{#line} directives alter the results of the @code{__FILE__} and
@end example
The standard is unclear on where a @code{_Pragma} operator can appear.
-The preprocessor accepts it even within a preprocessing conditional
+The preprocessor does not accept it within a preprocessing conditional
directive like @samp{#if}. To be safe, you are probably best keeping it
out of directives other than @samp{#define}, and putting it on a line of
its own.
@item
None of the GNU extensions to the preprocessor are available in
-traditional mode, with the exception of assertions, and those may be
-removed in the future.
+traditional mode, with the exception of a partial implementation of
+assertions, and those may be removed in the future.
@item
A true traditional C preprocessor does not recognize @samp{#elif},
Traditional mode used to be implemented in the same program as normal
preprocessing. Therefore, all the GNU extensions to the preprocessor
-were still available in traditional mode. It is now a separate program,
-and does not implement any of the GNU extensions except assertions.
-Even those may be removed in a future release.
+were still available in traditional mode. It is now a separate program
+and does not implement any of the GNU extensions, except for a partial
+implementation of assertions. Even those may be removed in a future
+release.
@end itemize
@node Invocation
All single-letter options which take an argument may have that argument
appear immediately after the option letter, or with a space between
option and argument: @option{-Ifoo} and @option{-I foo} have the same
-effect. Long options that take arguments require a space between option
-and argument.
+effect.
@cindex options
@table @gcctabopt
Indicate to the preprocessor that the input file has already been
preprocessed. This suppresses things like macro expansion, trigraph
conversion, escaped newline splicing, and processing of most directives.
-In this mode the integrated preprocessor is little more than a tokenizer
-for the front ends.
+The preprocessor still recognizes and removes comments, so that you can
+pass a file preprocessed with @option{-C} to the compiler without
+problems. In this mode the integrated preprocessor is little more than
+a tokenizer for the front ends.
@option{-fpreprocessed} is implicit if the input file has one of the
extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the
projects / gcc.git / commitdiff