This is ../../gcc-3.4/gcc/doc/cpp.info, produced by makeinfo version
4.2 from ../../gcc-3.4/gcc/doc/cpp.texi.

Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
1998, 1999, 2000, 2001, 2002, 2003 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 section entitled "GNU Free Documentation
License".

   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.  
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* Cpp: (cpp).		       The GNU C preprocessor.
END-INFO-DIR-ENTRY


File: cpp.info,  Node: Newlines in Arguments,  Prev: Argument Prescan,  Up: Macro Pitfalls

Newlines in Arguments
---------------------

   The invocation of a function-like macro can extend over many logical
lines.  However, in the present implementation, the entire expansion
comes out on one line.  Thus line numbers emitted by the compiler or
debugger refer to the line the invocation started on, which might be
different to the line containing the argument causing the problem.

   Here is an example illustrating this:

     #define ignore_second_arg(a,b,c) a; c
     
     ignore_second_arg (foo (),
                        ignored (),
                        syntax error);

The syntax error triggered by the tokens `syntax error' results in an
error message citing line three--the line of ignore_second_arg-- even
though the problematic code comes from line five.

   We consider this a bug, and intend to fix it in the near future.


File: cpp.info,  Node: Conditionals,  Next: Diagnostics,  Prev: Macros,  Up: Top

Conditionals
************

   A "conditional" is a directive that instructs the preprocessor to
select whether or not to include a chunk of code in the final token
stream passed to the compiler.  Preprocessor conditionals can test
arithmetic expressions, or whether a name is defined as a macro, or both
simultaneously using the special `defined' operator.

   A conditional in the C preprocessor resembles in some ways an `if'
statement in C, but it is important to understand the difference between
them.  The condition in an `if' statement is tested during the
execution of your program.  Its purpose is to allow your program to
behave differently from run to run, depending on the data it is
operating on.  The condition in a preprocessing conditional directive is
tested when your program is compiled.  Its purpose is to allow different
code to be included in the program depending on the situation at the
time of compilation.

   However, the distinction is becoming less clear.  Modern compilers
often do test `if' statements when a program is compiled, if their
conditions are known not to vary at run time, and eliminate code which
can never be executed.  If you can count on your compiler to do this,
you may find that your program is more readable if you use `if'
statements with constant conditions (perhaps determined by macros).  Of
course, you can only use this to exclude code, not type definitions or
other preprocessing directives, and you can only do it if the code
remains syntactically valid when it is not to be used.

   GCC version 3 eliminates this kind of never-executed code even when
not optimizing.  Older versions did it only when optimizing.

* Menu:

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


File: cpp.info,  Node: Conditional Uses,  Next: Conditional Syntax,  Up: Conditionals

Conditional Uses
================

   There are three general reasons to use a conditional.

   * A program may need to use different code depending on the machine
     or operating system it is to run on.  In some cases the code for
     one operating system may be erroneous on another operating system;
     for example, it might refer to data types or constants that do not
     exist on the other system.  When this happens, it is not enough to
     avoid executing the invalid code.  Its mere presence will cause
     the compiler to reject the program.  With a preprocessing
     conditional, the offending code can be effectively excised from
     the program when it is not valid.

   * You may want to be able to compile the same source file into two
     different programs.  One version might make frequent time-consuming
     consistency checks on its intermediate data, or print the values of
     those data for debugging, and the other not.

   * A conditional whose condition is always false is one way to
     exclude code from the program but keep it as a sort of comment for
     future reference.

   Simple programs that do not need system-specific logic or complex
debugging hooks generally will not need to use preprocessing
conditionals.


File: cpp.info,  Node: Conditional Syntax,  Next: Deleted Code,  Prev: Conditional Uses,  Up: Conditionals

Conditional Syntax
==================

   A conditional in the C preprocessor begins with a "conditional
directive": `#if', `#ifdef' or `#ifndef'.

* Menu:

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


File: cpp.info,  Node: Ifdef,  Next: If,  Up: Conditional Syntax

Ifdef
-----

   The simplest sort of conditional is

     #ifdef MACRO
     
     CONTROLLED TEXT
     
     #endif /* MACRO */

   This block is called a "conditional group".  CONTROLLED TEXT will be
included in the output of the preprocessor if and only if MACRO is
defined.  We say that the conditional "succeeds" if MACRO is defined,
"fails" if it is not.

   The CONTROLLED TEXT inside of a conditional can include
preprocessing directives.  They are executed only if the conditional
succeeds.  You can nest conditional groups inside other conditional
groups, but they must be completely nested.  In other words, `#endif'
always matches the nearest `#ifdef' (or `#ifndef', or `#if').  Also,
you cannot start a conditional group in one file and end it in another.

   Even if a conditional fails, the CONTROLLED TEXT inside it is still
run through initial transformations and tokenization.  Therefore, it
must all be lexically valid C.  Normally the only way this matters is
that all comments and string literals inside a failing conditional group
must still be properly ended.

   The comment following the `#endif' is not required, but it is a good
practice if there is a lot of CONTROLLED TEXT, because it helps people
match the `#endif' to the corresponding `#ifdef'.  Older programs
sometimes put MACRO directly after the `#endif' without enclosing it in
a comment.  This is invalid code according to the C standard.  CPP
accepts it with a warning.  It never affects which `#ifndef' the
`#endif' matches.

   Sometimes you wish to use some code if a macro is _not_ defined.
You can do this by writing `#ifndef' instead of `#ifdef'.  One common
use of `#ifndef' is to include code only the first time a header file
is included.  *Note Once-Only Headers::.

   Macro definitions can vary between compilations for several reasons.
Here are some samples.

   * Some macros are predefined on each kind of machine (*note
     System-specific Predefined Macros::).  This allows you to provide
     code specially tuned for a particular machine.

   * System header files define more macros, associated with the
     features they implement.  You can test these macros with
     conditionals to avoid using a system feature on a machine where it
     is not implemented.

   * Macros can be defined or undefined with the `-D' and `-U' command
     line options when you compile the program.  You can arrange to
     compile the same source file into two different programs by
     choosing a macro name to specify which program you want, writing
     conditionals to test whether or how this macro is defined, and
     then controlling the state of the macro with command line options,
     perhaps set in the Makefile.  *Note Invocation::.

   * Your program might have a special header file (often called
     `config.h') that is adjusted when the program is compiled.  It can
     define or not define macros depending on the features of the
     system and the desired capabilities of the program.  The
     adjustment can be automated by a tool such as `autoconf', or done
     by hand.


File: cpp.info,  Node: If,  Next: Defined,  Prev: Ifdef,  Up: Conditional Syntax

If
--

   The `#if' directive allows you to test the value of an arithmetic
expression, rather than the mere existence of one macro.  Its syntax is

     #if EXPRESSION
     
     CONTROLLED TEXT
     
     #endif /* EXPRESSION */

   EXPRESSION is a C expression of integer type, subject to stringent
restrictions.  It may contain

   * Integer constants.

   * Character constants, which are interpreted as they would be in
     normal code.

   * Arithmetic operators for addition, subtraction, multiplication,
     division, bitwise operations, shifts, comparisons, and logical
     operations (`&&' and `||').  The latter two obey the usual
     short-circuiting rules of standard C.

   * Macros.  All macros in the expression are expanded before actual
     computation of the expression's value begins.

   * Uses of the `defined' operator, which lets you check whether macros
     are defined in the middle of an `#if'.

   * Identifiers that are not macros, which are all considered to be the
     number zero.  This allows you to write `#if MACRO' instead of
     `#ifdef MACRO', if you know that MACRO, when defined, will always
     have a nonzero value.  Function-like macros used without their
     function call parentheses are also treated as zero.

     In some contexts this shortcut is undesirable.  The `-Wundef'
     option causes GCC to warn whenever it encounters an identifier
     which is not a macro in an `#if'.

   The preprocessor does not know anything about types in the language.
Therefore, `sizeof' operators are not recognized in `#if', and neither
are `enum' constants.  They will be taken as identifiers which are not
macros, and replaced by zero.  In the case of `sizeof', this is likely
to cause the expression to be invalid.

   The preprocessor calculates the value of EXPRESSION.  It carries out
all calculations in the widest integer type known to the compiler; on
most machines supported by GCC this is 64 bits.  This is not the same
rule as the compiler uses to calculate the value of a constant
expression, and may give different results in some cases.  If the value
comes out to be nonzero, the `#if' succeeds and the CONTROLLED TEXT is
included; otherwise it is skipped.

   If EXPRESSION is not correctly formed, GCC issues an error and
treats the conditional as having failed.


File: cpp.info,  Node: Defined,  Next: Else,  Prev: If,  Up: Conditional Syntax

Defined
-------

   The special operator `defined' is used in `#if' and `#elif'
expressions to test whether a certain name is defined as a macro.
`defined NAME' and `defined (NAME)' are both expressions whose value is
1 if NAME is defined as a macro at the current point in the program,
and 0 otherwise.  Thus,  `#if defined MACRO' is precisely equivalent to
`#ifdef MACRO'.

   `defined' is useful when you wish to test more than one macro for
existence at once.  For example,

     #if defined (__vax__) || defined (__ns16000__)

would succeed if either of the names `__vax__' or `__ns16000__' is
defined as a macro.

   Conditionals written like this:

     #if defined BUFSIZE && BUFSIZE >= 1024

can generally be simplified to just `#if BUFSIZE >= 1024', since if
`BUFSIZE' is not defined, it will be interpreted as having the value
zero.

   If the `defined' operator appears as a result of a macro expansion,
the C standard says the behavior is undefined.  GNU cpp treats it as a
genuine `defined' operator and evaluates it normally.  It will warn
wherever your code uses this feature if you use the command-line option
`-pedantic', since other compilers may handle it differently.


File: cpp.info,  Node: Else,  Next: Elif,  Prev: Defined,  Up: Conditional Syntax

Else
----

   The `#else' directive can be added to a conditional to provide
alternative text to be used if the condition fails.  This is what it
looks like:

     #if EXPRESSION
     TEXT-IF-TRUE
     #else /* Not EXPRESSION */
     TEXT-IF-FALSE
     #endif /* Not EXPRESSION */

If EXPRESSION is nonzero, the TEXT-IF-TRUE is included and the
TEXT-IF-FALSE is skipped.  If EXPRESSION is zero, the opposite happens.

   You can use `#else' with `#ifdef' and `#ifndef', too.


File: cpp.info,  Node: Elif,  Prev: Else,  Up: Conditional Syntax

Elif
----

   One common case of nested conditionals is used to check for more
than two possible alternatives.  For example, you might have

     #if X == 1
     ...
     #else /* X != 1 */
     #if X == 2
     ...
     #else /* X != 2 */
     ...
     #endif /* X != 2 */
     #endif /* X != 1 */

   Another conditional directive, `#elif', allows this to be
abbreviated as follows:

     #if X == 1
     ...
     #elif X == 2
     ...
     #else /* X != 2 and X != 1*/
     ...
     #endif /* X != 2 and X != 1*/

   `#elif' stands for "else if".  Like `#else', it goes in the middle
of a conditional group and subdivides it; it does not require a
matching `#endif' of its own.  Like `#if', the `#elif' directive
includes an expression to be tested.  The text following the `#elif' is
processed only if the original `#if'-condition failed and the `#elif'
condition succeeds.

   More than one `#elif' can go in the same conditional group.  Then
the text after each `#elif' is processed only if the `#elif' condition
succeeds after the original `#if' and all previous `#elif' directives
within it have failed.

   `#else' is allowed after any number of `#elif' directives, but
`#elif' may not follow `#else'.


File: cpp.info,  Node: Deleted Code,  Prev: Conditional Syntax,  Up: Conditionals

Deleted Code
============

   If you replace or delete a part of the program but want to keep the
old code around for future reference, you often cannot simply comment it
out.  Block comments do not nest, so the first comment inside the old
code will end the commenting-out.  The probable result is a flood of
syntax errors.

   One way to avoid this problem is to use an always-false conditional
instead.  For instance, put `#if 0' before the deleted code and
`#endif' after it.  This works even if the code being turned off
contains conditionals, but they must be entire conditionals (balanced
`#if' and `#endif').

   Some people use `#ifdef notdef' instead.  This is risky, because
`notdef' might be accidentally defined as a macro, and then the
conditional would succeed.  `#if 0' can be counted on to fail.

   Do not use `#if 0' for comments which are not C code.  Use a real
comment, instead.  The interior of `#if 0' must consist of complete
tokens; in particular, single-quote characters must balance.  Comments
often contain unbalanced single-quote characters (known in English as
apostrophes).  These confuse `#if 0'.  They don't confuse `/*'.


File: cpp.info,  Node: Diagnostics,  Next: Line Control,  Prev: Conditionals,  Up: Top

Diagnostics
***********

   The directive `#error' causes the preprocessor to report a fatal
error.  The tokens forming the rest of the line following `#error' are
used as the error message.

   You would use `#error' inside of a conditional that detects a
combination of parameters which you know the program does not properly
support.  For example, if you know that the program will not run
properly on a VAX, you might write

     #ifdef __vax__
     #error "Won't work on VAXen.  See comments at get_last_object."
     #endif

   If you have several configuration parameters that must be set up by
the installation in a consistent way, you can use conditionals to detect
an inconsistency and report it with `#error'.  For example,

     #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO)
     #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP."
     #endif

   The directive `#warning' is like `#error', but causes the
preprocessor to issue a warning and continue preprocessing.  The tokens
following `#warning' are used as the warning message.

   You might use `#warning' in obsolete header files, with a message
directing the user to the header file which should be used instead.

   Neither `#error' nor `#warning' macro-expands its argument.
Internal whitespace sequences are each replaced with a single space.
The line must consist of complete tokens.  It is wisest to make the
argument of these directives be a single string constant; this avoids
problems with apostrophes and the like.


File: cpp.info,  Node: Line Control,  Next: Pragmas,  Prev: Diagnostics,  Up: Top

Line Control
************

   The C preprocessor informs the C compiler of the location in your
source code where each token came from.  Presently, this is just the
file name and line number.  All the tokens resulting from macro
expansion are reported as having appeared on the line of the source
file where the outermost macro was used.  We intend to be more accurate
in the future.

   If you write a program which generates source code, such as the
`bison' parser generator, you may want to adjust the preprocessor's
notion of the current file name and line number by hand.  Parts of the
output from `bison' are generated from scratch, other parts come from a
standard parser file.  The rest are copied verbatim from `bison''s
input.  You would like compiler error messages and symbolic debuggers
to be able to refer to `bison''s input file.

   `bison' or any such program can arrange this by writing `#line'
directives into the output file.  `#line' is a directive that specifies
the original line number and source file name for subsequent input in
the current preprocessor input file.  `#line' has three variants:

`#line LINENUM'
     LINENUM is a non-negative decimal integer constant.  It specifies
     the line number which should be reported for the following line of
     input.  Subsequent lines are counted from LINENUM.

`#line LINENUM FILENAME'
     LINENUM is the same as for the first form, and has the same
     effect.  In addition, FILENAME is a string constant.  The
     following line and all subsequent lines are reported to come from
     the file it specifies, until something else happens to change that.
     FILENAME is interpreted according to the normal rules for a string
     constant: backslash escapes are interpreted.  This is different
     from `#include'.

     Previous versions of CPP did not interpret escapes in `#line'; we
     have changed it because the standard requires they be interpreted,
     and most other compilers do.

`#line ANYTHING ELSE'
     ANYTHING ELSE is checked for macro calls, which are expanded.  The
     result should match one of the above two forms.

   `#line' directives alter the results of the `__FILE__' and
`__LINE__' predefined macros from that point on.  *Note Standard
Predefined Macros::.  They do not have any effect on `#include''s idea
of the directory containing the current file.  This is a change from
GCC 2.95.  Previously, a file reading

     #line 1 "../src/gram.y"
     #include "gram.h"

   would search for `gram.h' in `../src', then the `-I' chain; the
directory containing the physical source file would not be searched.
In GCC 3.0 and later, the `#include' is not affected by the presence of
a `#line' referring to a different directory.

   We made this change because the old behavior caused problems when
generated source files were transported between machines.  For instance,
it is common practice to ship generated parsers with a source release,
so that people building the distribution do not need to have yacc or
Bison installed.  These files frequently have `#line' directives
referring to the directory tree of the system where the distribution was
created.  If GCC tries to search for headers in those directories, the
build is likely to fail.

   The new behavior can cause failures too, if the generated file is not
in the same directory as its source and it attempts to include a header
which would be visible searching from the directory containing the
source file.  However, this problem is easily solved with an additional
`-I' switch on the command line.  The failures caused by the old
semantics could sometimes be corrected only by editing the generated
files, which is difficult and error-prone.


File: cpp.info,  Node: Pragmas,  Next: Other Directives,  Prev: Line Control,  Up: Top

Pragmas
*******

   The `#pragma' directive is the method specified by the C standard
for providing additional information to the compiler, beyond what is
conveyed in the language itself.  Three forms of this directive
(commonly known as "pragmas") are specified by the 1999 C standard.  A
C compiler is free to attach any meaning it likes to other pragmas.

   GCC has historically preferred to use extensions to the syntax of the
language, such as `__attribute__', for this purpose.  However, GCC does
define a few pragmas of its own.  These mostly have effects on the
entire translation unit or source file.

   In GCC version 3, all GNU-defined, supported pragmas have been given
a `GCC' prefix.  This is in line with the `STDC' prefix on all pragmas
defined by C99.  For backward compatibility, pragmas which were
recognized by previous versions are still recognized without the `GCC'
prefix, but that usage is deprecated.  Some older pragmas are
deprecated in their entirety.  They are not recognized with the `GCC'
prefix.  *Note Obsolete Features::.

   C99 introduces the `_Pragma' operator.  This feature addresses a
major problem with `#pragma': being a directive, it cannot be produced
as the result of macro expansion.  `_Pragma' is an operator, much like
`sizeof' or `defined', and can be embedded in a macro.

   Its syntax is `_Pragma (STRING-LITERAL)', where STRING-LITERAL can
be either a normal or wide-character string literal.  It is
destringized, by replacing all `\\' with a single `\' and all `\"' with
a `"'.  The result is then processed as if it had appeared as the right
hand side of a `#pragma' directive.  For example,

     _Pragma ("GCC dependency \"parse.y\"")

has the same effect as `#pragma GCC dependency "parse.y"'.  The same
effect could be achieved using macros, for example

     #define DO_PRAGMA(x) _Pragma (#x)
     DO_PRAGMA (GCC dependency "parse.y")

   The standard is unclear on where a `_Pragma' operator can appear.
The preprocessor does not accept it within a preprocessing conditional
directive like `#if'.  To be safe, you are probably best keeping it out
of directives other than `#define', and putting it on a line of its own.

   This manual documents the pragmas which are meaningful to the
preprocessor itself.  Other pragmas are meaningful to the C or C++
compilers.  They are documented in the GCC manual.

`#pragma GCC dependency'
     `#pragma GCC dependency' allows you to check the relative dates of
     the current file and another file.  If the other file is more
     recent than the current file, a warning is issued.  This is useful
     if the current file is derived from the other file, and should be
     regenerated.  The other file is searched for using the normal
     include search path.  Optional trailing text can be used to give
     more information in the warning message.

          #pragma GCC dependency "parse.y"
          #pragma GCC dependency "/usr/include/time.h" rerun fixincludes

`#pragma GCC poison'
     Sometimes, there is an identifier that you want to remove
     completely from your program, and make sure that it never creeps
     back in.  To enforce this, you can "poison" the identifier with
     this pragma.  `#pragma GCC poison' is followed by a list of
     identifiers to poison.  If any of those identifiers appears
     anywhere in the source after the directive, it is a hard error.
     For example,

          #pragma GCC poison printf sprintf fprintf
          sprintf(some_string, "hello");

     will produce an error.

     If a poisoned identifier appears as part of the expansion of a
     macro which was defined before the identifier was poisoned, it
     will _not_ cause an error.  This lets you poison an identifier
     without worrying about system headers defining macros that use it.

     For example,

          #define strrchr rindex
          #pragma GCC poison rindex
          strrchr(some_string, 'h');

     will not produce an error.

`#pragma GCC system_header'
     This pragma takes no arguments.  It causes the rest of the code in
     the current file to be treated as if it came from a system header.
     *Note System Headers::.


File: cpp.info,  Node: Other Directives,  Next: Preprocessor Output,  Prev: Pragmas,  Up: Top

Other Directives
****************

   The `#ident' directive takes one argument, a string constant.  On
some systems, that string constant is copied into a special segment of
the object file.  On other systems, the directive is ignored.

   This directive is not part of the C standard, but it is not an
official GNU extension either.  We believe it came from System V.

   The `#sccs' directive is recognized, because it appears in the
header files of some systems.  It is a very old, obscure, extension
which we did not invent, and we have been unable to find any
documentation of what it should do, so GCC simply ignores it.

   The "null directive" consists of a `#' followed by a newline, with
only whitespace (including comments) in between.  A null directive is
understood as a preprocessing directive but has no effect on the
preprocessor output.  The primary significance of the existence of the
null directive is that an input line consisting of just a `#' will
produce no output, rather than a line of output containing just a `#'.
Supposedly some old C programs contain such lines.


File: cpp.info,  Node: Preprocessor Output,  Next: Traditional Mode,  Prev: Other Directives,  Up: Top

Preprocessor Output
*******************

   When the C preprocessor is used with the C, C++, or Objective-C
compilers, it is integrated into the compiler and communicates a stream
of binary tokens directly to the compiler's parser.  However, it can
also be used in the more conventional standalone mode, where it produces
textual output.

   The output from the C preprocessor looks much like the input, except
that all preprocessing directive lines have been replaced with blank
lines and all comments with spaces.  Long runs of blank lines are
discarded.

   The ISO standard specifies that it is implementation defined whether
a preprocessor preserves whitespace between tokens, or replaces it with
e.g. a single space.  In GNU CPP, whitespace between tokens is collapsed
to become a single space, with the exception that the first token on a
non-directive line is preceded with sufficient spaces that it appears in
the same column in the preprocessed output that it appeared in the
original source file.  This is so the output is easy to read.  *Note
Differences from previous versions::.  CPP does not insert any
whitespace where there was none in the original source, except where
necessary to prevent an accidental token paste.

   Source file name and line number information is conveyed by lines of
the form

     # LINENUM FILENAME FLAGS

These are called "linemarkers".  They are inserted as needed into the
output (but never within a string or character constant).  They mean
that the following line originated in file FILENAME at line LINENUM.
FILENAME will never contain any non-printing characters; they are
replaced with octal escape sequences.

   After the file name comes zero or more flags, which are `1', `2',
`3', or `4'.  If there are multiple flags, spaces separate them.  Here
is what the flags mean:

`1'
     This indicates the start of a new file.

`2'
     This indicates returning to a file (after having included another
     file).

`3'
     This indicates that the following text comes from a system header
     file, so certain warnings should be suppressed.

`4'
     This indicates that the following text should be treated as being
     wrapped in an implicit `extern "C"' block.

   As an extension, the preprocessor accepts linemarkers in
non-assembler input files.  They are treated like the corresponding
`#line' directive, (*note Line Control::), except that trailing flags
are permitted, and are interpreted with the meanings described above.
If multiple flags are given, they must be in ascending order.

   Some directives may be duplicated in the output of the preprocessor.
These are `#ident' (always), `#pragma' (only if the preprocessor does
not handle the pragma itself), and `#define' and `#undef' (with certain
debugging options).  If this happens, the `#' of the directive will
always be in the first column, and there will be no space between the
`#' and the directive name.  If macro expansion happens to generate
tokens which might be mistaken for a duplicated directive, a space will
be inserted between the `#' and the directive name.


File: cpp.info,  Node: Traditional Mode,  Next: Implementation Details,  Prev: Preprocessor Output,  Up: Top

Traditional Mode
****************

   Traditional (pre-standard) C preprocessing is rather different from
the preprocessing specified by the standard.  When GCC is given the
`-traditional-cpp' option, it attempts to emulate a traditional
preprocessor.

   GCC versions 3.2 and later only support traditional mode semantics in
the preprocessor, and not in the compiler front ends.  This chapter
outlines the traditional preprocessor semantics we implemented.

   The implementation does not correspond precisely to the behavior of
earlier versions of GCC, nor to any true traditional preprocessor.
After all, inconsistencies among traditional implementations were a
major motivation for C standardization.  However, we intend that it
should be compatible with true traditional preprocessors in all ways
that actually matter.

* Menu:

* Traditional lexical analysis::
* Traditional macros::
* Traditional miscellany::
* Traditional warnings::


File: cpp.info,  Node: Traditional lexical analysis,  Next: Traditional macros,  Up: Traditional Mode

Traditional lexical analysis
============================

   The traditional preprocessor does not decompose its input into tokens
the same way a standards-conforming preprocessor does.  The input is
simply treated as a stream of text with minimal internal form.

   This implementation does not treat trigraphs (*note trigraphs::)
specially since they were an invention of the standards committee.  It
handles arbitrarily-positioned escaped newlines properly and splices
the lines as you would expect; many traditional preprocessors did not
do this.

   The form of horizontal whitespace in the input file is preserved in
the output.  In particular, hard tabs remain hard tabs.  This can be
useful if, for example, you are preprocessing a Makefile.

   Traditional CPP only recognizes C-style block comments, and treats
the `/*' sequence as introducing a comment only if it lies outside
quoted text.  Quoted text is introduced by the usual single and double
quotes, and also by an initial `<' in a `#include' directive.

   Traditionally, comments are completely removed and are not replaced
with a space.  Since a traditional compiler does its own tokenization
of the output of the preprocessor, this means that comments can
effectively be used as token paste operators.  However, comments behave
like separators for text handled by the preprocessor itself, since it
doesn't re-lex its input.  For example, in

     #if foo/**/bar

`foo' and `bar' are distinct identifiers and expanded separately if
they happen to be macros.  In other words, this directive is equivalent
to

     #if foo bar

rather than

     #if foobar

   Generally speaking, in traditional mode an opening quote need not
have a matching closing quote.  In particular, a macro may be defined
with replacement text that contains an unmatched quote.  Of course, if
you attempt to compile preprocessed output containing an unmatched quote
you will get a syntax error.

   However, all preprocessing directives other than `#define' require
matching quotes.  For example:

     #define m This macro's fine and has an unmatched quote
     "/* This is not a comment.  */
     /* This is a comment.  The following #include directive
        is ill-formed.  */
     #include <stdio.h

   Just as for the ISO preprocessor, what would be a closing quote can
be escaped with a backslash to prevent the quoted text from closing.


File: cpp.info,  Node: Traditional macros,  Next: Traditional miscellany,  Prev: Traditional lexical analysis,  Up: Traditional Mode

Traditional macros
==================

   The major difference between traditional and ISO macros is that the
former expand to text rather than to a token sequence.  CPP removes all
leading and trailing horizontal whitespace from a macro's replacement
text before storing it, but preserves the form of internal whitespace.

   One consequence is that it is legitimate for the replacement text to
contain an unmatched quote (*note Traditional lexical analysis::). An
unclosed string or character constant continues into the text following
the macro call.  Similarly, the text at the end of a macro's expansion
can run together with the text after the macro invocation to produce a
single token.

   Normally comments are removed from the replacement text after the
macro is expanded, but if the `-CC' option is passed on the command
line comments are preserved.  (In fact, the current implementation
removes comments even before saving the macro replacement text, but it
careful to do it in such a way that the observed effect is identical
even in the function-like macro case.)

   The ISO stringification operator `#' and token paste operator `##'
have no special meaning.  As explained later, an effect similar to
these operators can be obtained in a different way.  Macro names that
are embedded in quotes, either from the main file or after macro
replacement, do not expand.

   CPP replaces an unquoted object-like macro name with its replacement
text, and then rescans it for further macros to replace.  Unlike
standard macro expansion, traditional macro expansion has no provision
to prevent recursion.  If an object-like macro appears unquoted in its
replacement text, it will be replaced again during the rescan pass, and
so on _ad infinitum_.  GCC detects when it is expanding recursive
macros, emits an error message, and continues after the offending macro
invocation.

     #define PLUS +
     #define INC(x) PLUS+x
     INC(foo);
          ==> ++foo;

   Function-like macros are similar in form but quite different in
behavior to their ISO counterparts.  Their arguments are contained
within parentheses, are comma-separated, and can cross physical lines.
Commas within nested parentheses are not treated as argument
separators.  Similarly, a quote in an argument cannot be left unclosed;
a following comma or parenthesis that comes before the closing quote is
treated like any other character.  There is no facility for handling
variadic macros.

   This implementation removes all comments from macro arguments, unless
the `-C' option is given.  The form of all other horizontal whitespace
in arguments is preserved, including leading and trailing whitespace.
In particular

     f( )

is treated as an invocation of the macro `f' with a single argument
consisting of a single space.  If you want to invoke a function-like
macro that takes no arguments, you must not leave any whitespace
between the parentheses.

   If a macro argument crosses a new line, the new line is replaced with
a space when forming the argument.  If the previous line contained an
unterminated quote, the following line inherits the quoted state.

   Traditional preprocessors replace parameters in the replacement text
with their arguments regardless of whether the parameters are within
quotes or not.  This provides a way to stringize arguments.  For example

     #define str(x) "x"
     str(/* A comment */some text )
          ==> "some text "

Note that the comment is removed, but that the trailing space is
preserved.  Here is an example of using a comment to effect token
pasting.

     #define suffix(x) foo_/**/x
     suffix(bar)
          ==> foo_bar


File: cpp.info,  Node: Traditional miscellany,  Next: Traditional warnings,  Prev: Traditional macros,  Up: Traditional Mode

Traditional miscellany
======================

   Here are some things to be aware of when using the traditional
preprocessor.

   * Preprocessing directives are recognized only when their leading
     `#' appears in the first column.  There can be no whitespace
     between the beginning of the line and the `#', but whitespace can
     follow the `#'.

   * A true traditional C preprocessor does not recognize `#error' or
     `#pragma', and may not recognize `#elif'.  CPP supports all the
     directives in traditional mode that it supports in ISO mode,
     including extensions, with the exception that the effects of
     `#pragma GCC poison' are undefined.

   * __STDC__ is not defined.

   * If you use digraphs the behavior is undefined.

   * If a line that looks like a directive appears within macro
     arguments, the behavior is undefined.



File: cpp.info,  Node: Traditional warnings,  Prev: Traditional miscellany,  Up: Traditional Mode

Traditional warnings
====================

   You can request warnings about features that did not exist, or worked
differently, in traditional C with the `-Wtraditional' option.  GCC
does not warn about features of ISO C which you must use when you are
using a conforming compiler, such as the `#' and `##' operators.

   Presently `-Wtraditional' warns about:

   * Macro parameters that appear within string literals in the macro
     body.  In traditional C macro replacement takes place within
     string literals, but does not in ISO C.

   * In traditional C, some preprocessor directives did not exist.
     Traditional preprocessors would only consider a line to be a
     directive if the `#' appeared in column 1 on the line.  Therefore
     `-Wtraditional' warns about directives that traditional C
     understands but would ignore because the `#' does not appear as the
     first character on the line.  It also suggests you hide directives
     like `#pragma' not understood by traditional C by indenting them.
     Some traditional implementations would not recognize `#elif', so it
     suggests avoiding it altogether.

   * A function-like macro that appears without an argument list.  In
     some traditional preprocessors this was an error.  In ISO C it
     merely means that the macro is not expanded.

   * The unary plus operator.  This did not exist in traditional C.

   * The `U' and `LL' integer constant suffixes, which were not
     available in traditional C.  (Traditional C does support the `L'
     suffix for simple long integer constants.)  You are not warned
     about uses of these suffixes in macros defined in system headers.
     For instance, `UINT_MAX' may well be defined as `4294967295U', but
     you will not be warned if you use `UINT_MAX'.

     You can usually avoid the warning, and the related warning about
     constants which are so large that they are unsigned, by writing the
     integer constant in question in hexadecimal, with no U suffix.
     Take care, though, because this gives the wrong result in exotic
     cases.


File: cpp.info,  Node: Implementation Details,  Next: Invocation,  Prev: Traditional Mode,  Up: Top

Implementation Details
**********************

   Here we document details of how the preprocessor's implementation
affects its user-visible behavior.  You should try to avoid undue
reliance on behavior described here, as it is possible that it will
change subtly in future implementations.

   Also documented here are obsolete features and changes from previous
versions of CPP.

* Menu:

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


File: cpp.info,  Node: Implementation-defined behavior,  Next: Implementation limits,  Up: Implementation Details

Implementation-defined behavior
===============================

   This is how CPP behaves in all the cases which the C standard
describes as "implementation-defined".  This term means that the
implementation is free to do what it likes, but must document its choice
and stick to it.

   * The mapping of physical source file multi-byte characters to the
     execution character set.

     Currently, CPP requires its input to be ASCII or UTF-8.  The
     execution character set may be controlled by the user, with the
     `-ftarget-charset' and `-ftarget-wide-charset' options.

   * Identifier characters.

     The C and C++ standards allow identifiers to be composed of `_'
     and the alphanumeric characters.  C++ and C99 also allow universal
     character names (not implemented in GCC), and C99 further permits
     implementation-defined characters.

     GCC allows the `$' character in identifiers as an extension for
     most targets.  This is true regardless of the `std=' switch, since
     this extension cannot conflict with standards-conforming programs.
     When preprocessing assembler, however, dollars are not identifier
     characters by default.

     Currently the targets that by default do not permit `$' are AVR,
     IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX
     and BeOS operating systems.

     You can override the default with `-fdollars-in-identifiers' or
     `fno-dollars-in-identifiers'.  *Note fdollars-in-identifiers::.

   * Non-empty sequences of whitespace characters.

     In textual output, each whitespace sequence is collapsed to a
     single space.  For aesthetic reasons, the first token on each
     non-directive line of output is preceded with sufficient spaces
     that it appears in the same column as it did in the original
     source file.

   * The numeric value of character constants in preprocessor
     expressions.

     The preprocessor and compiler interpret character constants in the
     same way; i.e. escape sequences such as `\a' are given the values
     they would have on the target machine.

     The compiler values a multi-character character constant a
     character at a time, shifting the previous value left by the
     number of bits per target character, and then or-ing in the
     bit-pattern of the new character truncated to the width of a
     target character.  The final bit-pattern is given type `int', and
     is therefore signed, regardless of whether single characters are
     signed or not (a slight change from versions 3.1 and earlier of
     GCC).  If there are more characters in the constant than would fit
     in the target `int' the compiler issues a warning, and the excess
     leading characters are ignored.

     For example, 'ab' for a target with an 8-bit `char' would be
     interpreted as
     (int) ((unsigned char) 'a' * 256 + (unsigned char) 'b'), and
     '\234a' as
     (int) ((unsigned char) '\234' * 256 + (unsigned char) 'a').

   * Source file inclusion.

     For a discussion on how the preprocessor locates header files,
     *Note Include Operation::.

   * Interpretation of the filename resulting from a macro-expanded
     `#include' directive.

     *Note Computed Includes::.

   * Treatment of a `#pragma' directive that after macro-expansion
     results in a standard pragma.

     No macro expansion occurs on any `#pragma' directive line, so the
     question does not arise.

     Note that GCC does not yet implement any of the standard pragmas.



File: cpp.info,  Node: Implementation limits,  Next: Obsolete Features,  Prev: Implementation-defined behavior,  Up: Implementation Details

Implementation limits
=====================

   CPP has a small number of internal limits.  This section lists the
limits which the C standard requires to be no lower than some minimum,
and all the others we are aware of.  We intend there to be as few limits
as possible.  If you encounter an undocumented or inconvenient limit,
please report that to us as a bug.  (See the section on reporting bugs
in the GCC manual.)

   Where we say something is limited "only by available memory", that
means that internal data structures impose no intrinsic limit, and space
is allocated with `malloc' or equivalent.  The actual limit will
therefore depend on many things, such as the size of other things
allocated by the compiler at the same time, the amount of memory
consumed by other processes on the same computer, etc.

   * Nesting levels of `#include' files.

     We impose an arbitrary limit of 200 levels, to avoid runaway
     recursion.  The standard requires at least 15 levels.

   * Nesting levels of conditional inclusion.

     The C standard mandates this be at least 63.  CPP is limited only
     by available memory.

   * Levels of parenthesized expressions within a full expression.

     The C standard requires this to be at least 63.  In preprocessor
     conditional expressions, it is limited only by available memory.

   * Significant initial characters in an identifier or macro name.

     The preprocessor treats all characters as significant.  The C
     standard requires only that the first 63 be significant.

   * Number of macros simultaneously defined in a single translation
     unit.

     The standard requires at least 4095 be possible.  CPP is limited
     only by available memory.

   * Number of parameters in a macro definition and arguments in a
     macro call.

     We allow `USHRT_MAX', which is no smaller than 65,535.  The minimum
     required by the standard is 127.

   * Number of characters on a logical source line.

     The C standard requires a minimum of 4096 be permitted.  CPP places
     no limits on this, but you may get incorrect column numbers
     reported in diagnostics for lines longer than 65,535 characters.

   * Maximum size of a source file.

     The standard does not specify any lower limit on the maximum size
     of a source file.  GNU cpp maps files into memory, so it is
     limited by the available address space.  This is generally at
     least two gigabytes.  Depending on the operating system, the size
     of physical memory may or may not be a limitation.



File: cpp.info,  Node: Obsolete Features,  Next: Differences from previous versions,  Prev: Implementation limits,  Up: Implementation Details

Obsolete Features
=================

   CPP has a number of features which are present mainly for
compatibility with older programs.  We discourage their use in new code.
In some cases, we plan to remove the feature in a future version of GCC.

* Menu:

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


File: cpp.info,  Node: Assertions,  Next: Obsolete once-only headers,  Up: Obsolete Features

Assertions
----------

   "Assertions" are a deprecated alternative to macros in writing
conditionals to test what sort of computer or system the compiled
program will run on.  Assertions are usually predefined, but you can
define them with preprocessing directives or command-line options.

   Assertions were intended to provide a more systematic way to describe
the compiler's target system.  However, in practice they are just as
unpredictable as the system-specific predefined macros.  In addition,
they are not part of any standard, and only a few compilers support
them.  Therefore, the use of assertions is *less* portable than the use
of system-specific predefined macros.  We recommend you do not use them
at all.

   An assertion looks like this:

     #PREDICATE (ANSWER)

PREDICATE must be a single identifier.  ANSWER can be any sequence of
tokens; all characters are significant except for leading and trailing
whitespace, and differences in internal whitespace sequences are
ignored.  (This is similar to the rules governing macro redefinition.)
Thus, `(x + y)' is different from `(x+y)' but equivalent to
`( x + y )'.  Parentheses do not nest inside an answer.

   To test an assertion, you write it in an `#if'.  For example, this
conditional succeeds if either `vax' or `ns16000' has been asserted as
an answer for `machine'.

     #if #machine (vax) || #machine (ns16000)

You can test whether _any_ answer is asserted for a predicate by
omitting the answer in the conditional:

     #if #machine

   Assertions are made with the `#assert' directive.  Its sole argument
is the assertion to make, without the leading `#' that identifies
assertions in conditionals.

     #assert PREDICATE (ANSWER)

You may make several assertions with the same predicate and different
answers.  Subsequent assertions do not override previous ones for the
same predicate.  All the answers for any given predicate are
simultaneously true.

   Assertions can be canceled with the `#unassert' directive.  It has
the same syntax as `#assert'.  In that form it cancels only the answer
which was specified on the `#unassert' line; other answers for that
predicate remain true.  You can cancel an entire predicate by leaving
out the answer:

     #unassert PREDICATE

In either form, if no such assertion has been made, `#unassert' has no
effect.

   You can also make or cancel assertions using command line options.
*Note Invocation::.

