cpp.texinfo

这是完整的gcc源代码

\input texinfo
@setfilename cpp.info
@settitle The C Preprocessor
@setchapternewpage odd
@ifinfo
This file documents the GNU C Preprocessor.

Copyright (C) 1987, 1989 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@titlepage
@sp 6
@center @titlefont{The C Preprocessor}
@sp 4
@center Last revised July 1990
@center for GCC version 1.38
@sp 5
@center Richard M. Stallman
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1987, 1989 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage
@page

@node Top, Global Actions,, (DIR)
@chapter The C Preprocessor

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
called a macro processor because it allows you to define @dfn{macros},
which are brief abbreviations for longer constructs.

The C preprocessor provides four separate facilities that you can use as
you see fit:

@itemize @bullet
@item
Inclusion of header files.  These are files of declarations that can be
substituted into your program.

@item
Macro expansion.  You can define @dfn{macros}, which are abbreviations
for arbitrary fragments of C code, and then the C preprocessor will
replace the macros with their definitions throughout the program.

@item
Conditional compilation.  Using special preprocessor commands, you
can include or exclude parts of the program according to various
conditions.

@item
Line control.  If you use a program to combine or rearrange source files into
an intermediate file which is then compiled, you can use line control
to inform the compiler of where each source line originally came from.
@end itemize

C preprocessors vary in some details.  This manual discusses the GNU C
preprocessor, the C Compatible Compiler Preprocessor.  The GNU C
preprocessor provides a superset of the features of ANSI Standard C.

ANSI Standard C requires the rejection of many harmless constructs commonly
used by today's C programs.  Such incompatibility would be inconvenient for
users, so the GNU C preprocessor is configured to accept these constructs
by default.  Strictly speaking, to get ANSI Standard C, you must use the
options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in
practice the consequences of having strict ANSI Standard C make it
undesirable to do this.  @xref{Invocation}.

@menu
* Global Actions::    Actions made uniformly on all input files.
* Commands::          General syntax of preprocessor commands.
* Header Files::      How and why to use header files.
* Macros::            How and why to use macros.
* Conditionals::      How and why to use conditionals.
* Combining Sources:: Use of line control when you combine source files.
* Other Commands::    Miscellaneous preprocessor commands.
* Output::            Format of output from the C preprocessor.
* Invocation::        How to invoke the preprocessor; command options.
* Concept Index::     Index of concepts and terms.
* Index::             Index of commands, predefined macros and options.
@end menu

@node Global Actions, Commands, Top, Top
@section Transformations Made Globally

Most C preprocessor features are inactive unless you give specific commands
to request their use.  (Preprocessor commands are lines starting with
@samp{#}; @pxref{Commands}).  But there are three transformations that the
preprocessor always makes on all the input it receives, even in the absence
of commands.

@itemize @bullet
@item
All C comments are replaced with single spaces.

@item
Backslash-Newline sequences are deleted, no matter where.  This
feature allows you to break long lines for cosmetic purposes without
changing their meaning.

@item
Predefined macro names are replaced with their expansions
(@pxref{Predefined}).
@end itemize

The first two transformations are done @emph{before} nearly all other parsing
and before preprocessor commands are recognized.  Thus, for example, you
can split a line cosmetically with Backslash-Newline anywhere (except
when trigraphs are in use; see below).

@example
/*
*/ # /*
*/ defi\
ne FO\
O 10\
20
@end example

@noindent
is equivalent into @samp{#define FOO 1020}.  You can split even an escape
sequence with Backslash-Newline.  For example, you can split @code{"foo\bar"}
between the @samp{\} and the @samp{b} to get

@example
"foo\\
bar"
@end example

@noindent
This behavior is unclean: in all other contexts, a Backslash can be
inserted in a string constant as an ordinary character by writing a double
Backslash, and this creates an exception.  But the ANSI C standard requires
it.  (Strict ANSI C does not allow Newlines in string constants, so they
do not consider this a problem.)

But there are a few exceptions to all three transformations.

@itemize @bullet
@item
C comments and predefined macro names are not recognized inside a
@samp{#include} command in which the file name is delimited with
@samp{<} and @samp{>}.

@item
C comments and predefined macro names are never recognized within a
character or string constant.  (Strictly speaking, this is the rule,
not an exception, but it is worth noting here anyway.)

@item
Backslash-Newline may not safely be used within an ANSI ``trigraph''.
Trigraphs are converted before Backslash-Newline is deleted.  If you
write what looks like a trigraph with a Backslash-Newline inside, the
Backslash-Newline is deleted as usual, but it is then too late to
recognize the trigraph.

This exception is relevant only if you use the @samp{-trigraphs}
option to enable trigraph processing.  @xref{Invocation}.
@end itemize

@node Commands, Header Files, Global Actions, Top
@section Preprocessor Commands

@cindex preprocessor commands
@cindex commands
Most preprocessor features are active only if you use preprocessor commands
to request their use.

Preprocessor commands are lines in your program that start with @samp{#}.
The @samp{#} is followed by an identifier that is the @dfn{command name}.
For example, @samp{#define} is the command that defines a macro.
Whitespace is also allowed before and after the @samp{#}.

The set of valid command names is fixed.  Programs cannot define new
preprocessor commands.

Some command names require arguments; these make up the rest of the command
line and must be separated from the command name by whitespace.  For example,
@samp{#define} must be followed by a macro name and the intended expansion
of the macro.

A preprocessor command cannot be more than one line in normal circumstances.
It may be split cosmetically with Backslash-Newline, but that has no effect
on its meaning.  Comments containing Newlines can also divide the command into
multiple lines, but the comments are changed to Spaces before the command
is interpreted.  The only way a significant Newline can occur in a preprocessor
command is within a string constant or character constant.  Note that
most C compilers that might be applied to the output from the preprocessor
do not accept string or character constants containing Newlines.

The @samp{#} and the command name cannot come from a macro expansion.  For
example, if @samp{foo} is defined as a macro expanding to @samp{define},
that does not make @samp{#foo} a valid preprocessor command.

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

@cindex header file
A header file is a file containing C declarations and macro definitions
(@pxref{Macros}) to be shared between several source files.  You request
the use of a header file in your program with the C preprocessor command
@samp{#include}.

@menu
* Header Uses::         What header files are used for.
* Include Syntax::      How to write @samp{#include} commands.
* Include Operation::   What @samp{#include} does.
* Once-Only::		Preventing multiple inclusion of one header file.
@end menu

@node Header Uses, Include Syntax, Header Files, Header Files
@subsection Uses of Header Files

Header files serve two kinds of purposes.

@itemize @bullet
@item
@findex system header files
System header files declare the interfaces to parts of the operating
system.  You include them in your program to supply the definitions
you need to invoke system calls and libraries.

@item
Your own header files contain declarations for interfaces between the
source files of your program.  Each time you have a group of related
declarations and macro definitions all or most of which are needed in
several different source files, it is a good idea to create a header
file for them.
@end itemize

Including a header file produces the same results in C compilation as
copying the header file into each source file that needs it.  But such
copying would be time-consuming and error-prone.  With a header file, the
related declarations appear in only one place.  If they need to be changed,
they can be changed in one place, and programs that include the header file
will automatically use the new version when next recompiled.  The header
file eliminates the labor of finding and changing all the copies as well as
the risk that a failure to find one copy will result in inconsistencies
within a program.

The usual convention is to give header files names that end with @file{.h}.

@node Include Syntax, Include Operation, Header Uses, Header Files
@subsection The @samp{#include} Command

@findex #include
Both user and system header files are included using the preprocessor
command @samp{#include}.  It has three variants:

@table @code
@item #include <@var{file}>
This variant is used for system header files.  It searches for a file
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}).  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{}>}.
Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment
and the command specifies inclusion of a system header file named
@file{x/*y}.  Of course, a header file with such a name is unlikely to
exist on Unix, where shell wildcard features would make it hard to
manipulate.@refill

The argument @var{file} may not contain a @samp{>} character.  It may,
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 directory,
then in the same directories used for system header files.  The
current directory is the directory of the current input file.  It is
tried first because it is presumed to be the location of the files
that the current input file refers to.  (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
characters, not escape characters.  None of the character escape
sequences appropriate to string constants in C are processed.  Thus,
@samp{#include "x\n\\y"} specifies a filename containing three
backslashes.  It is not clear why this behavior is ever useful, but
the ANSI standard specifies it.

@item #include @var{anything else}
This variant is called a @dfn{computed #include}.  Any @samp{#include}
command whose argument does not fit the above two forms is a computed
include.  The text @var{anything else} is checked for macro calls,
which are expanded (@pxref{Macros}).  When this is done, the result
must fit one of the above two variants.

This feature allows you to define a macro which controls the file name
to be used at a later point in the program.  One application of this
is to allow a site-configuration file for your program to specify the
names of the system include files to be used.  This can help in
porting the program to various operating systems in which the
necessary system header files are found in different places.
@end table

@node Include Operation, Once-Only, Include Syntax, Header Files
@subsection How @samp{#include} Works

The @samp{#include} command works by directing the C preprocessor to scan
the specified file as input before continuing with the rest of the current
file.  The output from the preprocessor contains the output already
generated, followed by the output resulting from the included file,
followed by the output that comes from the text after the @samp{#include}
command.  For example, given two files as follows:

@example
/* File program.c */
int x;
#include "header.h"

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