@setfilename cpp.info
@settitle The C Preprocessor
-@ignore
@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* Cpp: (cpp). The C preprocessor.
-END-INFO-DIR-ENTRY
-@end format
+@dircategory Programming
+@direntry
+* Cpp: (cpp). The GNU C preprocessor.
+@end direntry
@end ifinfo
-@end ignore
@c @smallbook
@c @cropmarks
@ifinfo
This file documents the GNU C Preprocessor.
-Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc.
+Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@titlepage
@c @finalout
@title The C Preprocessor
-@subtitle Last revised March 1997
+@subtitle Last revised May 1999
@subtitle for GCC version 2
@author Richard M. Stallman
@page
C Language manual.
@vskip 0pt plus 1filll
-Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free
-Software Foundation, Inc.
+@c man begin COPYRIGHT
+Copyright @copyright{} 1987, 1989, 1991-1999
+Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
+@c man end
@end titlepage
@page
@node Top, Global Actions,, (DIR)
@chapter The C Preprocessor
+@c man begin DESCRIPTION
The C preprocessor is a @dfn{macro processor} that is used automatically by
the C compiler to transform your program before actual compilation. It is
that it is dealing with C@. For example, the C preprocessor sometimes
outputs extra white space to avoid inadvertent C token concatenation,
and this may cause problems with other languages.
+@c man end
@menu
* Global Actions:: Actions made uniformly on all input files.
@node Global Actions, Directives, Top, Top
@section Transformations Made Globally
+@cindex ASCII NUL handling
Most C preprocessor features are inactive unless you give specific directives
to request their use. (Preprocessing directives are lines starting with
option to enable trigraph processing. @xref{Invocation}.
@end itemize
+The preprocessor handles null characters embedded in the input file
+depending upon the context in which the null appears. Note that here we
+are referring not to the two-character escape sequence "\0", but to the
+single character ASCII NUL.
+
+There are three different contexts in which a null character may
+appear:-
+
+@itemize @bullet
+@item
+Within comments. Here, null characters are silently ignored.
+
+@item
+Within a string or character constant. Here the preprocessor emits a
+warning, but preserves the null character and passes it through to the
+output file.
+
+@item
+In any other context, the preprocessor issues a warning, and discards
+the null character. In all other respects the preprocessor treats it
+like whitespace, combining it with any surrounding whitespace to become
+a single whitespace token. Representing the null character by "^@@",
+this means that code like
+
+@example
+#define X^@@1
+@end example
+
+is equivalent to
+
+@example
+#define X 1
+@end example
+
+and X is defined with replacement text "1".
+@end itemize
+
@node Directives, Header Files, Global Actions, Top
@section Preprocessing Directives
* Simple Macros:: Macros that always expand the same way.
* Argument Macros:: Macros that accept arguments that are substituted
into the macro expansion.
+* Macro Varargs:: Macros with variable number of arguments.
* Predefined:: Predefined macros that are always available.
* Stringification:: Macro arguments converted into string constants.
* Concatenation:: Building tokens from parts taken from macro arguments.
* Undefining:: Cancelling a macro's definition.
* Redefining:: Changing a macro's definition.
+* Poisoning:: Ensuring a macro is never defined or used.
* Macro Pitfalls:: Macros can confuse the unwary. Here we explain
several common problems and strange features.
@end menu
that the result of its expansion is checked for more macro names.
@xref{Cascaded Macros}.
-@node Argument Macros, Predefined, Simple Macros, Macros
+@node Argument Macros, Macro Varargs, Simple Macros, Macros
@subsection Macros with Arguments
@cindex macros with argument
@cindex arguments in macro definitions
the left parenthesis; it's the @emph{definition} where it matters whether
there is a space.
-@node Predefined, Stringification, Argument Macros, Macros
+@node Macro Varargs, Predefined, Argument Macros, Macros
+@subsection Macros with Variable Numbers of Arguments
+@cindex variable number of arguments
+@cindex macro with variable arguments
+@cindex rest argument (in macro)
+
+In GNU C, a macro can accept a variable number of arguments, much as a
+function can. The syntax for defining the macro looks much like that
+used for a function. Here is an example:
+
+@example
+#define eprintf(format, args...) \
+ fprintf (stderr, format , ## args)
+@end example
+
+Here @code{args} is a @dfn{rest argument}: it takes in zero or more
+arguments, as many as the call contains. All of them plus the commas
+between them form the value of @code{args}, which is substituted into
+the macro body where @code{args} is used. Thus, we have this expansion:
+
+@example
+eprintf ("%s:%d: ", input_file_name, line_number)
+@expansion{}
+fprintf (stderr, "%s:%d: " , input_file_name, line_number)
+@end example
+
+@noindent
+Note that the comma after the string constant comes from the definition
+of @code{eprintf}, whereas the last comma comes from the value of
+@code{args}.
+
+The reason for using @samp{##} is to handle the case when @code{args}
+matches no arguments at all. In this case, @code{args} has an empty
+value. In this case, the second comma in the definition becomes an
+embarrassment: if it got through to the expansion of the macro, we would
+get something like this:
+
+@example
+fprintf (stderr, "success!\n" , )
+@end example
+
+@noindent
+which is invalid C syntax. @samp{##} gets rid of the comma, so we get
+the following instead:
+
+@example
+fprintf (stderr, "success!\n")
+@end example
+
+This is a special feature of the GNU C preprocessor: @samp{##} before a
+rest argument that is empty discards the preceding sequence of
+non-whitespace characters from the macro definition. (If another macro
+argument precedes, none of it is discarded.)
+
+It might be better to discard the last preprocessor token instead of the
+last preceding sequence of non-whitespace characters; in fact, we may
+someday change this feature to do so. We advise you to write the macro
+definition so that the preceding sequence of non-whitespace characters
+is just a single token, so that the meaning will not change if we change
+the definition of this feature.
+
+@node Predefined, Stringification, Macro Varargs, Macros
@subsection Predefined Macros
@cindex predefined macros
be used to work around differences between different releases of the
compiler (for example, if gcc 2.6.3 is known to support a feature, you
can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}).
-The last number, @samp{3} in the
-example above, denotes the bugfix level of the compiler; no macro
-contains this value.
+
+@item __GNUC_PATCHLEVEL__
+@findex __GNUC_PATCHLEVEL__
+This macro contains the patch level of the compiler. This can be
+used to work around differences between different patch level releases
+of the compiler (for example, if gcc 2.6.2 is known to contain a bug,
+whereas gcc 2.6.3 contains a fix, and you have code which can workaround
+ths problem depending on whether the bug is fixed or not, you can test for
+@code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 6) ||
+(__GNUC__ == 2 && __GNUC_MINOR__ == 6 && __GNUC_PATCHLEVEL__ > 3)}).
@item __GNUG__
@findex __GNUG__
@item __cplusplus
@findex __cplusplus
-The draft ANSI standard for C++ used to require predefining this
-variable. Though it is no longer required, GNU C++ continues to define
-it, as do other popular C++ compilers. You can use @samp{__cplusplus}
-to test whether a header is compiled by a C compiler or a C++ compiler.
+The ISO standard for C++ requires predefining this variable. You can
+use @samp{__cplusplus} to test whether a header is compiled by a C
+compiler or a C++ compiler. The compiler currently uses a value of
+@samp{1}, instead of the value @samp{199711L}, which would indicate
+full conformance with the standard.
@item __STRICT_ANSI__
@findex __STRICT_ANSI__
arguments or definitions that don't expect arguments. The @samp{#undef}
directive has no effect when used on a name not currently defined as a macro.
-@node Redefining, Macro Pitfalls, Undefining, Macros
+@node Redefining, Poisoning, Undefining, Macros
@subsection Redefining Macros
@cindex redefining macros
Recall that a comment counts as whitespace.
-@node Macro Pitfalls,, Redefining, Macros
+@node Poisoning, Macro Pitfalls, Redefining, Macros
+@subsection Poisoning Macros
+@cindex poisoning macros
+
+Sometimes, there is an identifier that you want to remove completely
+from your program, and make sure that it never creeps back in. To
+enforce this, the @samp{#pragma poison} directive can be used.
+@samp{#pragma poison} is followed by a list of identifiers to poison,
+and takes effect for the rest of the source. You cannot @samp{#undef} a
+poisoned identifier or test to see if it's defined with @samp{#ifdef}.
+
+For example,
+
+@example
+#pragma poison printf sprintf fprintf
+sprintf(some_string, "hello");
+@end example
+
+@noindent
+will produce an error.
+
+@node Macro Pitfalls,, Poisoning, Macros
@subsection Pitfalls and Subtleties of Macros
@cindex problems with macros
@cindex pitfalls of macros
characters:
@example
-#define SKIP_SPACES (p, limit) \
+#define SKIP_SPACES(p, limit) \
@{ register char *lim = (limit); \
while (p != lim) @{ \
if (*p++ != ' ') @{ \
this problem, using a @samp{do @dots{} while} statement. Here is how:
@example
-#define SKIP_SPACES (p, limit) \
+#define SKIP_SPACES(p, limit) \
do @{ register char *lim = (limit); \
while (p != lim) @{ \
if (*p++ != ' ') @{ \
explicitly: the C compiler will do so automatically. However, the
preprocessor is sometimes useful on its own.
+@ignore
+@c man begin SYNOPSIS
+cpp [@samp{-P}] [@samp{-C}] [@samp{-gcc}] [@samp{-traditional}]
+ [@samp{-undef}] [@samp{-trigraphs}] [@samp{-pedantic}]
+ [@samp{-W}@var{warn}...] [@samp{-I}@var{dir}...]
+ [@samp{-D}@var{macro}[=@var{defn}]...] [@samp{-U}@var{macro}]
+ [@samp{-A}@var{predicate}(@var{answer})]
+ [@samp{-M}|@samp{-MM}|@samp{-MD}|@samp{-MMD} [@samp{-MG}]]
+ [@samp{-x} @var{language}] [@samp{-std=}@var{standard}]
+ @var{infile} @var{outfile}
+
+Only the most useful options are listed here; see below for the remainder.
+@c man end
+@c man begin SEEALSO
+gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and
+@file{binutils}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS
The C preprocessor expects two file names as arguments, @var{infile} and
@var{outfile}. The preprocessor reads @var{infile} together with any other
files it specifies with @samp{#include}. All the output generated by the
combined input files is written in @var{outfile}.
-Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
-means to read from standard input and as @var{outfile} means to write to
-standard output. Also, if @var{outfile} or both file names are omitted,
-the standard output and standard input are used for the omitted file names.
+Either @var{infile} or @var{outfile} may be @samp{-}, which as
+@var{infile} means to read from standard input and as @var{outfile}
+means to write to standard output. Also, if either file is omitted, it
+means the same as if @samp{-} had been specified for that file.
@cindex options
Here is a table of command options accepted by the C preprocessor.
significance of the following character.
@end itemize
+@cindex Fortran
+@cindex unterminated
+Use the @samp{-traditional} option when preprocessing Fortran code,
+so that singlequotes and doublequotes
+within Fortran comment lines
+(which are generally not recognized as such by the preprocessor)
+do not cause diagnostics
+about unterminated character or string constants.
+
+However, this option does not prevent diagnostics
+about unterminated comments
+when a C-style comment appears to start, but not end,
+within Fortran-style commentary.
+
+So, the following Fortran comment lines are accepted with
+@samp{-traditional}:
+
+@smallexample
+C This isn't an unterminated character constant
+C Neither is "20000000000, an octal constant
+C in some dialects of Fortran
+@end smallexample
+
+However, this type of comment line will likely produce a diagnostic,
+or at least unexpected output from the preprocessor,
+due to the unterminated comment:
+
+@smallexample
+C Some Fortran compilers accept /* as starting
+C an inline comment.
+@end smallexample
+
+@cindex g77
+Note that @code{g77} automatically supplies
+the @samp{-traditional} option
+when it invokes the preprocessor.
+However, a future version of @code{g77}
+might use a different, more-Fortran-aware preprocessor
+in place of @code{cpp}.
+
@item -trigraphs
@findex -trigraphs
Process ANSI standard trigraph sequences. These are three-character
Like @samp{-pedantic}, except that errors are produced rather than
warnings.
-@item -Wtrigraphs
-@findex -Wtrigraphs
-Warn if any trigraphs are encountered (assuming they are enabled).
-
@item -Wcomment
@findex -Wcomment
@ignore
Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
+@item -Wtrigraphs
+@findex -Wtrigraphs
+Warn if any trigraphs are encountered (assuming they are enabled).
+
+@item -Wwhite-space
+@findex -Wwhite-space
+Warn about possible white space confusion, e.g. white space between a
+backslash and a newline.
+
@item -Wall
@findex -Wall
-Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not
-@samp{-Wtraditional} or @samp{-Wundef}).
+Requests @samp{-Wcomment}, @samp{-Wtrigraphs}, and @samp{-Wwhite-space}
+(but not @samp{-Wtraditional} or @samp{-Wundef}).
@item -Wtraditional
@findex -Wtraditional
@item -U @var{name}
@findex -U
Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are
-specified for one name, the @samp{-U} beats the @samp{-D} and the name
-is not predefined.
+specified for one name, whichever one appears later on the command line
+wins.
@item -undef
@findex -undef
Do not predefine any nonstandard macros.
+@item -gcc
+@findex -gcc
+Define the macros @var{__GNUC__}, @var{__GNUC_MINOR__} and
+@var{__GNUC_PATCHLEVEL__}. These are defined automatically when you use
+@samp{gcc -E}; you can turn them off in that case with @samp{-no-gcc}.
+
@item -A @var{predicate}(@var{answer})
@findex -A
Make an assertion with the predicate @var{predicate} and answer
@var{answer}. @xref{Assertions}.
-@noindent
-You can use @samp{-A-} to disable all predefined assertions; it also
-undefines all predefined macros that identify the type of target system.
+@item -A -@var{predicate}(@var{answer})
+Disable an assertion with the predicate @var{predicate} and answer
+@var{answer}. Specifiying no predicate, by @samp{-A-} or @samp{-A -},
+disables all predefined assertions and all assertions preceding it on
+the command line; and also undefines all predefined macros and all
+macros preceding it on the command line.
@item -dM
@findex -dM
This is in addition to compiling the file as specified---@samp{-MD} does
not inhibit ordinary compilation the way @samp{-M} does.
-When invoking gcc, do not specify the @var{file} argument.
-Gcc will create file names made by replacing ".c" with ".d" at
+When invoking @code{gcc}, do not specify the @var{file} argument.
+@code{gcc} will create file names made by replacing ".c" with ".d" at
the end of the input file names.
In Mach, you can use the utility @code{md} to merge multiple dependency
as a system directory, so that it gets the same special treatment as
is applied to the standard system directories.
-@item -lang-c
-@itemx -lang-c89
-@itemx -lang-c++
-@itemx -lang-objc
-@itemx -lang-objc++
-@findex -lang-c
-@findex -lang-c89
-@findex -lang-c++
-@findex -lang-objc
-@findex -lang-objc++
-Specify the source language. @samp{-lang-c} is the default; it
-allows recognition of C++ comments (comments that begin with
-@samp{//} and end at end of line) and hexadecimal floating-point constants,
-since these features will most likely appear in the next C standard.
-@samp{-lang-c89} disables recognition of C++ comments and
-hexadecimal floating-point constants. @samp{-lang-c++}
-handles C++ comment syntax and includes extra default include
-directories for C++. @samp{-lang-objc} enables the Objective C
-@samp{#import} directive. @samp{-lang-objc++} enables both C++ and Objective C
-extensions.
-
-These options are generated by the compiler driver @code{gcc}, but not
-passed from the @samp{gcc} command line unless you use the driver's
-@samp{-Wp} option.
-
-@item -lint
+@item -x c
+@itemx -x c++
+@itemx -x objective-c
+@itemx -x assembler-with-cpp
+@findex -x c
+@findex -x objective-c
+@findex -x assembler-with-cpp
+Specify the source language: C, C++, Objective-C, or assembly. This has
+nothing to do with standards conformance or extensions; it merely
+selects which base syntax to expect. If you give none of these options,
+cpp will deduce the language from the extension of the source file:
+@samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common
+extensions for C++ and assembly are also recognized. If cpp does not
+recognize the extension, it will treat the file as C; this is the most
+generic mode.
+
+@strong{Note:} Previous versions of cpp accepted a @samp{-lang} option
+which selected both the language and the standards conformance level.
+This option has been removed, because it conflicts with the @samp{-l}
+option.
+
+@item -std=@var{standard}
+@itemx -ansi
+@findex -std
+@findex -ansi
+Specify the standard to which the code should conform. Currently cpp
+only knows about the standards for C; other language standards will be
+added in the future.
+
+@var{standard}
+may be one of:
+@table @code
+@item iso9899:1990
+The ISO C standard from 1990.
+
+@item iso9899:199409
+@itemx c89
+The 1990 C standard, as amended in 1994. @samp{c89} is the customary
+shorthand for this version of the standard.
+
+The @samp{-ansi} option is equivalent to @samp{-std=c89}.
+
+@item iso9899:199x
+@itemx c9x
+The revised ISO C standard, which is expected to be promulgated some
+time in 1999. It has not been approved yet, hence the @samp{x}.
+
+@item gnu89
+The 1990 C standard plus GNU extensions. This is the default.
+
+@item gnu9x
+The 199x C standard plus GNU extensions.
+@end table
+
+@item -Wp,-lint
+@findex -lint
Look for commands to the program checker @code{lint} embedded in
comments, and emit them preceded by @samp{#pragma lint}. For example,
the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint
NOTREACHED}.
-This option is available only when you call @code{cpp} directly;
-@code{gcc} will not pass it from its command line.
+Because of the clash with @samp{-l}, you must use the awkward syntax
+above. In a future release, this option will be replaced by
+@samp{-flint} or @samp{-Wlint}; we are not sure which yet.
@item -$
@findex -$
-Forbid the use of @samp{$} in identifiers. This was formerly required
-for strict conformance to the C Standard before the standard was
-corrected.
-
-This option is available only when you call @code{cpp} directly;
-@code{gcc} will not pass it from its command line.
-
+Forbid the use of @samp{$} in identifiers. The C standard does not
+permit this, but it is a common extension.
@end table
+@c man end
@node Concept Index, Index, Invocation, Top
@unnumbered Concept Index
OSDN Git Service
