cpp.texi

理解和实践操作系统的一本好书

\input texinfo
@setfilename cpp.info
@settitle The C Preprocessor
@setchapternewpage off
@c @smallbook
@c @cropmarks
@c @finalout

@include gcc-common.texi

@copying
@c man begin COPYRIGHT
Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.  A copy of
the license is included in the
@c man end
section entitled ``GNU Free Documentation License''.
@ignore
@c man begin COPYRIGHT
man page gfdl(7).
@c man end
@end ignore

@c man begin COPYRIGHT
This manual contains no Invariant Sections.  The Front-Cover Texts are
(a) (see below), and the Back-Cover Texts are (b) (see below).

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@c man end
@end copying

@c Create a separate index for command line options.
@defcodeindex op
@syncodeindex vr op

@c Used in cppopts.texi and cppenv.texi.
@set cppmanual

@ifinfo
@dircategory Software development
@direntry
* Cpp: (cpp).		       The GNU C preprocessor.
@end direntry
@end ifinfo

@titlepage
@title The C Preprocessor
@versionsubtitle
@author Richard M. Stallman, Zachary Weinberg
@page
@c There is a fill at the bottom of the page, so we need a filll to
@c override it.
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@page

@ifnottex
@node Top
@top
The C preprocessor implements the macro language used to transform C,
C++, and Objective-C programs before they are compiled.  It can also be
useful on its own.

@menu
* Overview::
* Header Files::
* Macros::
* Conditionals::
* Diagnostics::
* Line Control::
* Pragmas::
* Other Directives::
* Preprocessor Output::
* Traditional Mode::
* Implementation Details::
* Invocation::
* Environment Variables::
* GNU Free Documentation License::
* Index of Directives::
* Option Index::
* Concept Index::

@detailmenu
 --- The Detailed Node Listing ---

Overview

* Character sets::
* Initial processing::
* Tokenization::
* The preprocessing language::

Header Files

* Include Syntax::
* Include Operation::
* Search Path::
* Once-Only Headers::
* Computed Includes::
* Wrapper Headers::
* System Headers::

Macros

* Object-like Macros::
* Function-like Macros::
* Macro Arguments::
* Stringification::
* Concatenation::
* Variadic Macros::
* Predefined Macros::
* Undefining and Redefining Macros::
* Directives Within Macro Arguments::
* Macro Pitfalls::

Predefined Macros

* Standard Predefined Macros::
* Common Predefined Macros::
* System-specific Predefined Macros::
* C++ Named Operators::

Macro Pitfalls

* Misnesting::
* Operator Precedence Problems::
* Swallowing the Semicolon::
* Duplication of Side Effects::
* Self-Referential Macros::
* Argument Prescan::
* Newlines in Arguments::

Conditionals

* Conditional Uses::
* Conditional Syntax::
* Deleted Code::

Conditional Syntax

* Ifdef::
* If::
* Defined::
* Else::
* Elif::

Implementation Details

* Implementation-defined behavior::
* Implementation limits::
* Obsolete Features::
* Differences from previous versions::

Obsolete Features

* Assertions::
* Obsolete once-only headers::

@end detailmenu
@end menu

@insertcopying
@end ifnottex

@node Overview
@chapter Overview
@c man begin DESCRIPTION
The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor}
that is used automatically by the C compiler to transform your program
before 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 is intended to be used only with C, C++, and
Objective-C source code.  In the past, it has been abused as a general
text processor.  It will choke on input which does not obey C's lexical
rules.  For example, apostrophes will be interpreted as the beginning of
character constants, and cause errors.  Also, you cannot rely on it
preserving characteristics of the input which are not significant to
C-family languages.  If a Makefile is preprocessed, all the hard tabs
will be removed, and the Makefile will not work.

Having said that, you can often get away with using cpp on things which
are not C@.  Other Algol-ish programming languages are often safe
(Pascal, Ada, etc.) So is assembly, with caution.  @option{-traditional-cpp}
mode preserves more white space, and is otherwise more permissive.  Many
of the problems can be avoided by writing C or C++ style comments
instead of native language comments, and keeping macros simple.

Wherever possible, you should use a preprocessor geared to the language
you are writing in.  Modern versions of the GNU assembler have macro
facilities.  Most high level programming languages have their own
conditional compilation and inclusion mechanism.  If all else fails,
try a true general text processor, such as GNU M4.

C preprocessors vary in some details.  This manual discusses the GNU C
preprocessor, which provides a small superset of the features of ISO
Standard C@.  In its default mode, the GNU C preprocessor does not do a
few things required by the standard.  These are features which are
rarely, if ever, used, and may cause surprising changes to the meaning
of a program which does not expect them.  To get strict ISO Standard C,
you should use the @option{-std=c89} or @option{-std=c99} options, depending
on which version of the standard you want.  To get all the mandatory
diagnostics, you must also use @option{-pedantic}.  @xref{Invocation}.

This manual describes the behavior of the ISO preprocessor.  To
minimize gratuitous differences, where the ISO preprocessor's
behavior does not conflict with traditional semantics, the
traditional preprocessor should behave the same way.  The various
differences that do exist are detailed in the section @ref{Traditional
Mode}.

For clarity, unless noted otherwise, references to @samp{CPP} in this
manual refer to GNU CPP@.
@c man end

@menu
* Character sets::
* Initial processing::
* Tokenization::
* The preprocessing language::
@end menu

@node Character sets
@section Character sets

Source code character set processing in C and related languages is
rather complicated.  The C standard discusses two character sets, but
there are really at least four.

The files input to CPP might be in any character set at all.  CPP's
very first action, before it even looks for line boundaries, is to
convert the file into the character set it uses for internal
processing.  That set is what the C standard calls the @dfn{source}
character set.  It must be isomorphic with ISO 10646, also known as
Unicode.  CPP uses the UTF-8 encoding of Unicode.

The character sets of the input files are specified using the
@option{-finput-charset=} option.

All preprocessing work (the subject of the rest of this manual) is
carried out in the source character set.  If you request textual
output from the preprocessor with the @option{-E} option, it will be
in UTF-8.

After preprocessing is complete, string and character constants are
converted again, into the @dfn{execution} character set.  This
character set is under control of the user; the default is UTF-8,
matching the source character set.  Wide string and character
constants have their own character set, which is not called out
specifically in the standard.  Again, it is under control of the user.
The default is UTF-16 or UTF-32, whichever fits in the target's
@code{wchar_t} type, in the target machine's byte
order.@footnote{UTF-16 does not meet the requirements of the C
standard for a wide character set, but the choice of 16-bit
@code{wchar_t} is enshrined in some system ABIs so we cannot fix
this.}  Octal and hexadecimal escape sequences do not undergo
conversion; @t{'\x12'} has the value 0x12 regardless of the currently
selected execution character set.  All other escapes are replaced by
the character in the source character set that they represent, then
converted to the execution character set, just like unescaped
characters.

Unless the experimental @option{-fextended-identifiers} option is used,
GCC does not permit the use of characters outside the ASCII range, nor
@samp{\u} and @samp{\U} escapes, in identifiers.  Even with that
option, characters outside the ASCII range can only be specified with
the @samp{\u} and @samp{\U} escapes, not used directly in identifiers.

@node Initial processing
@section Initial processing

The preprocessor performs a series of textual transformations on its
input.  These happen before all other processing.  Conceptually, they
happen in a rigid order, and the entire file is run through each
transformation before the next one begins.  CPP actually does them
all at once, for performance reasons.  These transformations correspond
roughly to the first three ``phases of translation'' described in the C
standard.

@enumerate
@item
@cindex line endings
The input file is read into memory and broken into lines.

Different systems use different conventions to indicate the end of a
line.  GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR
LF}} and @kbd{CR} as end-of-line markers.  These are the canonical
sequences used by Unix, DOS and VMS, and the classic Mac OS (before
OSX) respectively.  You may therefore safely copy source code written
on any of those systems to a different one and use it without
conversion.  (GCC may lose track of the current line number if a file
doesn't consistently use one convention, as sometimes happens when it
is edited on computers with different conventions that share a network
file system.)

If the last line of any input file lacks an end-of-line marker, the end
of the file is considered to implicitly supply one.  The C standard says
that this condition provokes undefined behavior, so GCC will emit a
warning message.

@item
@cindex trigraphs
@anchor{trigraphs}If trigraphs are enabled, they are replaced by their
corresponding single characters.  By default GCC ignores trigraphs,
but if you request a strictly conforming mode with the @option{-std}
option, or you specify the @option{-trigraphs} option, then it
converts them.

These are nine three-character sequences, all starting with @samp{??},
that are defined by ISO C to stand for single characters.  They permit
obsolete systems that lack some of C's punctuation to use C@.  For
example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character
constant for a newline.

Trigraphs are not popular and many compilers implement them
incorrectly.  Portable code should not rely on trigraphs being either
converted or ignored.  With @option{-Wtrigraphs} GCC will warn you
when a trigraph may change the meaning of your program if it were
converted.  @xref{Wtrigraphs}.

In a string constant, you can prevent a sequence of question marks
from being confused with a trigraph by inserting a backslash between
the question marks, or by separating the string literal at the
trigraph and making use of string literal concatenation.  @t{"(??\?)"}
is the string @samp{(???)}, not @samp{(?]}.  Traditional C compilers
do not recognize these idioms.

The nine trigraphs and their replacements are

@smallexample
Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-