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

@macro copyrightnotice
@c man begin COPYRIGHT
Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
1997, 1998, 1999, 2000, 2001
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 accompanying manual for GCC, in the
section ``GNU Free Documentation License''.
@c man end
@end macro

@c The manpage doesn't have Front-Cover and Back-Cover Texts, but the
@c complete manual does.  -zw

@ignore
@c man begin COPYRIGHT
This manual contains no Invariant Sections, and has no Front-Cover Texts
or Back-Cover Texts.
@c man end
@end ignore

@macro covertexts
This manual contains no Invariant Sections.  The Front-Cover Texts are
(a) (see below), and the 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.
@end macro

@macro gcctabopt{body}
@code{\body\}
@end macro

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

@titlepage
@title The C Preprocessor
@subtitle Last revised April 2001
@subtitle for GCC version 3
@author Richard M. Stallman
@author 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
@copyrightnotice{}
@covertexts{}
@end titlepage
@contents
@page

@ifinfo
@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::
* Index of Directives::
* Concept Index::

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

Overview

* 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::
* 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::
* Miscellaneous obsolete features::

@end detailmenu
@end menu

@copyrightnotice{}
@covertexts{}
@end ifinfo

@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}
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}.
@c man end

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

@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.  GNU 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 character sets
@cindex line endings
The input file is read into memory and broken into lines.

GNU CPP expects its input to be a text file, that is, an unstructured
stream of ASCII characters, with some characters indicating the end of a
line of text.  Extended ASCII character sets, such as ISO Latin-1 or
Unicode encoded in UTF-8, are also acceptable.  Character sets that are
not strict supersets of seven-bit ASCII will not work.  We plan to add
complete support for international character sets in a future release.

Different systems use different conventions to indicate the end of a
line.  GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR
LF}}, @kbd{CR}, and @kbd{@w{LF CR}} as end-of-line markers.  The first
three 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.)  @kbd{@w{LF CR}} is included because it has been
reported as an end-of-line marker under exotic conditions.

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
If trigraphs are enabled, they are replaced by their corresponding
single characters.

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.  By default, GCC ignores trigraphs, but if you
request a strictly conforming mode with the @option{-std} option, then
it converts them.

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

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.  @t{"(??\?)"} is the string @samp{(???)}, not
@samp{(?]}.  Traditional C compilers do not recognize this idiom.

The nine trigraphs and their replacements are

@example
Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
Replacement:      [    ]    @{    @}    #    \    ^    |    ~
@end example

@item
@cindex continued lines
@cindex backslash-newline
Continued lines are merged into one long line.

A continued line is a line which ends with a backslash, @samp{\}.  The
backslash is removed and the following line is joined with the current
one.  No space is inserted, so you may split a line anywhere, even in
the middle of a word.  (It is generally more readable to split lines
only at white space.)

The trailing backslash on a continued line is commonly referred to as a
@dfn{backslash-newline}.

If there is white space between a backslash and the end of a line, that
is still a continued line.  However, as this is usually the result of an
editing mistake, and many compilers will not accept it as a continued
line, GCC will warn you about it.

@item
@cindex comments
@cindex line comments
@cindex block comments
All comments are replaced with single spaces.

There are two kinds of comments.  @dfn{Block comments} begin with
@samp{/*} and continue until the next @samp{*/}.  Block comments do not
nest:

@example
/* @r{this is} /* @r{one comment} */ @r{text outside comment}
@end example

@dfn{Line comments} begin with @samp{//} and continue to the end of the
current line.  Line comments do not nest either, but it does not matter,
because they would end in the same place anyway.

@example
// @r{this is} // @r{one comment}
@r{text outside comment}
@end example
@end enumerate

It is safe to put line comments inside block comments, or vice versa.

@example