cpp.texi

gcc库的原代码,对编程有很大帮助.

\input texinfo
@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
@end ifinfo
@end ignore

@c @smallbook
@c @cropmarks
@c @finalout
@setchapternewpage odd
@ifinfo
This file documents the GNU C Preprocessor.

Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 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
@c @finalout
@title The C Preprocessor
@subtitle Last revised July 1992
@subtitle for GCC version 2
@author Richard M. Stallman
@page
@vskip 2pc
This booklet is eventually intended to form the first chapter of a GNU 
C Language manual.

@vskip 0pt plus 1filll
Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995 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 preprocessing directives, 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.
* Directives::        General syntax of preprocessing directives.
* 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 Directives::  Miscellaneous preprocessing directives.
* 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 directives, predefined macros and options.
@end menu

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

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

@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 preprocessing directives 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} directive 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 Directives, Header Files, Global Actions, Top
@section Preprocessing Directives

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

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

The set of valid directive names is fixed.  Programs cannot define new
preprocessing directives.

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

A preprocessing directive 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
directive into multiple lines, but the comments are changed to Spaces
before the directive is interpreted.  The only way a significant Newline
can occur in a preprocessing directive 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 directive 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 preprocessing directive.

@node Header Files, Macros, Directives, 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 preprocessing directive
@samp{#include}.

@menu
* Header Uses::         What header files are used for.
* Include Syntax::      How to write @samp{#include} directives.
* Include Operation::   What @samp{#include} does.
* Once-Only::		Preventing multiple inclusion of one header file.
* Inheritance::         Including one header file in another 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 and
declarations 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}.  Avoid unusual characters in header file names, as they
reduce portability.

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

@findex #include
Both user and system header files are included using the preprocessing
directive @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 directive 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}
@cindex computed @samp{#include}
This variant is called a @dfn{computed #include}.  Any @samp{#include}
directive 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