cpp.texinfo

这是完整的gcc源代码

/* File header.h */
char *test ();
@end example

@noindent
the output generated by the C preprocessor for @file{program.c} as input
would be

@example
int x;
char *test ();

main ()
@{
  printf (test ());
@}
@end example

Included files are not limited to declarations and macro definitions; they
are merely the typical use.  Any fragment of a C program can be included
from another file.  The include file could even contain the beginning of a
statement that is concluded in the containing file, or the end of a
statement that was started in the including file.  However, a comment or a
string or character constant may not start in the included file and finish
in the including file.  An unterminated comment, string constant or
character constant in an included file is considered to end (with an error
message) at the end of the file.

The line following the @samp{#include} command is always treated as a
separate line by the C preprocessor even if the included file lacks a final
newline.

@node Once-Only,, Include Operation, Header Files
@subsection Once-Only Include Files
@cindex repeated inclusion

Very often, one header file includes another.  It can easily result that a
certain header file is included more than once.  This may lead to errors,
if the header file defines structure types or typedefs, and is certainly
wasteful.  Therefore, we often wish to prevent multiple inclusion of a
header file.

The standard way to do this is to enclose the entire real contents of the
file in a conditional, like this:

@example
#ifndef __FILE_FOO_SEEN__
#define __FILE_FOO_SEEN__

@var{the entire file}

#endif /* __FILE_FOO_SEEN__ */
@end example

The macro @code{__FILE_FOO_SEEN__} indicates that the file has been
included once already; its name should begin with @samp{__}, and should
contain the name of the file to avoid accidental conflicts.

One drawback of this method is that the preprocessor must scan the input
file completely in order to determine that all of it is to be ignored.
This makes compilation slower.  You can avoid the delay by inserting the
following command near the beginning of file @emph{in addition to the
conditionals described above}:

@example
#pragma once
@end example

This command tells the GNU C preprocessor to ignore any future commands
to include the same file (whichever file the @samp{#pragma} appears in).

You should not @emph{rely} on @samp{#pragma once} to prevent multiple
inclusion of the file.  It is just a hint, and a nonstandard one at
that.  Most C compilers will ignore it entirely.  For this reason, you
still need the conditionals if you want to make certain that the file's
contents are not included twice.

Note that @samp{#pragma once} works by file name; if a file has more
than one name, it can be included once under each name, even in GNU CC,
despite @samp{#pragma once}.

@node Macros, Conditionals, Header Files, Top
@section Macros

A macro is a sort of abbreviation which you can define once and then
use later.  There are many complicated features associated with macros
in the C preprocessor.

@menu
* Simple Macros::    Macros that always expand the same way.
* Argument Macros::  Macros that accept arguments that are substituted
                       into the macro expansion.
* 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.
* Macro Pitfalls::   Macros can confuse the unwary.  Here we explain
                       several common problems and strange features.
@end menu

@node Simple Macros, Argument Macros, Macros, Macros
@subsection Simple Macros

A @dfn{simple macro} is a kind of abbreviation.  It is a name which stands
for a fragment of code.

Before you can use a macro, you must @dfn{define} it explicitly with the
@samp{#define} command.  @samp{#define} is followed by the name of the
macro and then the code it should be an abbreviation for.  For example,

@example
#define BUFFER_SIZE 1020
@end example

@noindent
defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text
@samp{1020}.  Therefore, if somewhere after this @samp{#define} command
there comes a C statement of the form

@example
foo = (char *) xmalloc (BUFFER_SIZE);
@end example

@noindent
then the C preprocessor will recognize and @dfn{expand} the macro
@samp{BUFFER_SIZE}, resulting in

@example
foo = (char *) xmalloc (1020);
@end example

@noindent
the definition must be a single line; however, it may not end in the
middle of a multi-line string constant or character constant.

The use of all upper case for macro names is a standard convention.
Programs are easier to read when it is possible to tell at a glance which
names are macros.

Normally, a macro definition must be a single line, like all C preprocessor
commands.  (You can split a long macro definition cosmetically with
Backslash-Newline.)  There is one exception: Newlines can be included in
the macro definition if within a string or character constant.  By the same
token, it is not possible for a macro definition to contain an unbalanced
quote character; the definition automatically extends to include the
matching quote character that ends the string or character constant.
Comments within a macro definition may contain Newlines, which make no
difference since the comments are entirely replaced with Spaces regardless
of their contents.

Aside from the above, there is no restriction on what can go in a macro
body.  Parentheses need not balance.  The body need not resemble valid C
code.  (Of course, you might get error messages from the C compiler when
you use the macro.)

The C preprocessor scans your program sequentially, so macro definitions
take effect at the place you write them.  Therefore, the following input to
the C preprocessor

@example
foo = X;
#define X 4
bar = X;
@end example

@noindent
produces as output

@example
foo = X;

bar = 4;
@end example

After the preprocessor expands a macro name, the macro's definition body is
appended to the front of the remaining input, and the check for macro calls
continues.  Therefore, the macro body can contain calls to other macros.
For example, after

@example
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
@end example

@noindent
the name @samp{TABLESIZE} when used in the program would go through two
stages of expansion, resulting ultimately in @samp{1020}.

This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
specify---in this case, @samp{BUFSIZE}---and does not check to see whether
it too is the name of a macro.  It's only when you @emph{use} @samp{TABLESIZE}
that the result of its expansion is checked for more macro names.
@xref{Cascaded Macros}.

@node Argument Macros, Predefined, Simple Macros, Macros
@subsection Macros with Arguments

A simple macro always stands for exactly the same text, each time it is
used.  Macros can be more flexible when they accept @dfn{arguments}.
Arguments are fragments of code that you supply each time the macro is
used.  These fragments are included in the expansion of the macro according
to the directions in the macro definition.

To define a macro that uses arguments, you write a @samp{#define} command
with a list of @dfn{argument names} in parentheses after the name of the
macro.  The argument names may be any valid C identifiers, separated by
commas and optionally whitespace.  The open-parenthesis must follow the
macro name immediately, with no space in between.

For example, here is a macro that computes the minimum of two numeric
values, as it is defined in many C programs:

@example
#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
@end example

@noindent
(This is not the best way to define a ``minimum'' macro in GNU C.
@xref{Side Effects}, for more information.)

To use a macro that expects arguments, you write the name of the macro
followed by a list of @dfn{actual arguments} in parentheses. separated by
commas.  The number of actual arguments you give must match the number of
arguments the macro expects.   Examples of use of the macro @samp{min}
include @samp{min (1, 2)} and @samp{min (x + 28, *p)}.

The expansion text of the macro depends on the arguments you use.
Each of the argument names of the macro is replaced, throughout the
macro definition, with the corresponding actual argument.  Using the
same macro @samp{min} defined above, @samp{min (1, 2)} expands into

@example
((1) < (2) ? (1) : (2))
@end example

@noindent
where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}.

Likewise, @samp{min (x + 28, *p)} expands into

@example
((x + 28) < (*p) ? (x + 28) : (*p))
@end example

Parentheses in the actual arguments must balance; a comma within
parentheses does not end an argument.  However, there is no requirement for
brackets or braces to balance; thus, if you want to supply @samp{array[x =
y, x + 1]} as an argument, you must write it as @samp{array[(x = y, x +
1)]}, which is equivalent C code.

After the actual arguments are substituted into the macro body, the entire
result is appended to the front of the remaining input, and the check for
macro calls continues.  Therefore, the actual arguments can contain calls
to other macros, either with or without arguments, or even to the same
macro.  The macro body can also contain calls to other macros.  For
example, @samp{min (min (a, b), c)} expands into

@example
((((a) < (b) ? (a) : (b))) < (c)
 ? (((a) < (b) ? (a) : (b)))
 : (c))
@end example

@noindent
(Line breaks shown here for clarity would not actually be generated.)

If you use the macro name followed by something other than an
open-parenthesis (after ignoring any spaces, tabs and comments that
follow), it is not a call to the macro, and the preprocessor leaves the
name unaltered.  Therefore, it is possible for the same name to be a
variable or function in your program as well as a macro, and you can
choose in each instance whether to refer to the macro (if an actual
argument list follows) or the variable or function (if an argument list
does not follow).

Such dual use of one name could be confusing and should be avoided
except when the two meanings are effectively synonymous: that is, when the
name is both a macro and a function and the two have similar effects.  You
can think of the name simply as a function; use of the name for purposes
other than calling it (such as, to take the address) will refer to the
function, while calls will expand the macro and generate better but
equivalent code.  For example, you can use a function named @samp{min} in
the same source file that defines the macro.  If you write @samp{&min} with
no argument list, you refer to the function.  If you write @samp{min (x,
bb)}, with an argument list, the macro is expanded.  If you write
@samp{(min) (a, bb)}, where the name @samp{min} is not followed by an
open-parenthesis, the macro is not expanded, so you wind up with a call to
the function @samp{min}.

It is not allowed to define the same name as both a simple macro and
a macro with arguments.

In the definition of a macro with arguments, the list of argument names
must follow the macro name immediately with no space in between.  If there
is a space after the macro name, the macro is defined as taking no
arguments, and all the rest of the name is taken to be the expansion.  The
reason for this is that it is often useful to define a macro that takes no
arguments and whose definition begins with an identifier in parentheses.
This rule about spaces makes it possible for you to do either this:

@example
#define FOO(x) - 1 / (x)
@end example

@noindent
(which defines @samp{FOO} to take an argument and expand into minus the
reciprocal of that argument) or this:

@example
#define BAR (x) - 1 / (x)
@end example

@noindent
(which defines @samp{BAR} to take no argument and always expand into
@samp{(x) - 1 / (x)}).

Note that the @emph{uses} of a macro with arguments can have spaces before
the left parenthesis; it's the @emph{definition} where it matters whether
there is a space.

@node Predefined, Stringification, Argument Macros, Macros
@subsection Predefined Macros

@cindex predefined macros
Several simple macros are predefined.  You can use them without giving
definitions for them.  They fall into two classes: standard macros and
system-specific macros.

@menu
* Standard Predefined::     Standard predefined macros.
* Nonstandard Predefined::  Nonstandard predefined macros.
@end menu

@node Standard Predefined, Nonstandard Predefined, Predefined, Predefined
@subsubsection Standard Predefined Macros

The standard predefined macros are available with the same meanings
regardless of the machine or operating system on which you are using GNU C.
Their names all start and end with double underscores.  Those preceding
@code{__GNUC__} in this table are standardized by ANSI C; the rest are
GNU C extensions.

@table @code
@item __FILE__
@findex __FILE__
This macro expands to the name of the current input file, in the form
of a C string constant.