cpp : The preprocessing language

table of contents

  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
  Initial processing
  Tokenization
  The preprocessing language
  Include Syntax
  Include Operation
  Search Path
  Once-Only Headers
  Computed Includes
  Wrapper Headers
  System Headers
  Object-like Macros
  Function-like Macros
  Macro Arguments
  Stringification
  Concatenation
  Variadic Macros
  Predefined Macros
  Undefining and Redefining Macros
  Directives Within Macro Arguments
  Macro Pitfalls
  Standard Predefined Macros
  Common Predefined Macros
  System-specific Predefined Macros
  C++ Named Operators
  Misnesting
  Operator Precedence Problems
  Swallowing the Semicolon
  Duplication of Side Effects
  Self-Referential Macros
  Argument Prescan
  Newlines in Arguments
  Conditional Uses
  Conditional Syntax
  Deleted Code
  Ifdef
  If
  Defined
  Else
  Elif
  Implementation-defined behavior
  Implementation limits
  Obsolete Features
  Differences from previous versions
  Assertions
  Obsolete once-only headers

The preprocessing language
==========================

   After tokenization, the stream of tokens may simply be passed
straight to the compiler's parser.  However, if it contains any
operations in the "preprocessing language", it will be transformed
first.  This stage corresponds roughly to the standard's "translation
phase 4" and is what most people think of as the preprocessor's job.

   The preprocessing language consists of "directives" to be executed
and "macros" to be expanded.  Its primary capabilities are:

   * Inclusion of header files.  These are files of declarations that
     can be substituted into your program.

   * Macro expansion.  You can define "macros", which are abbreviations
     for arbitrary fragments of C code.  The preprocessor will replace
     the macros with their definitions throughout the program.  Some
     macros are automatically defined for you.

   * Conditional compilation.  You can include or exclude parts of the
     program according to various conditions.

   * 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 where each source line
     originally came from.

   * Diagnostics.  You can detect problems at compile time and issue
     errors or warnings.

   There are a few more, less useful, features.

   Except for expansion of predefined macros, all these operations are
triggered with "preprocessing directives".  Preprocessing directives
are lines in your program that start with `#'.  Whitespace is allowed
before and after the `#'.  The `#' is followed by an identifier, the
"directive name".  It specifies the operation to perform.  Directives
are commonly referred to as `#NAME' where NAME is the directive name.
For example, `#define' is the directive that defines a macro.

   The `#' which begins a directive cannot come from a macro expansion.
Also, the directive name is not macro expanded.  Thus, if `foo' is
defined as a macro expanding to `define', that does not make `#foo' a
valid preprocessing directive.

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

   Some directives require arguments; these make up the rest of the
directive line and must be separated from the directive name by
whitespace.  For example, `#define' must be followed by a macro name
and the intended expansion of the macro.

   A preprocessing directive cannot cover more than one line.  The line
may, however, be continued with backslash-newline, or by a block comment
which extends past the end of the line.  In either case, when the
directive is processed, the continuations have already been merged with
the first line to make one long line.

back to top
cpp : The preprocessing language

table of contents

  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
  Initial processing
  Tokenization
  The preprocessing language
  Include Syntax
  Include Operation
  Search Path
  Once-Only Headers
  Computed Includes
  Wrapper Headers
  System Headers
  Object-like Macros
  Function-like Macros
  Macro Arguments
  Stringification
  Concatenation
  Variadic Macros
  Predefined Macros
  Undefining and Redefining Macros
  Directives Within Macro Arguments
  Macro Pitfalls
  Standard Predefined Macros
  Common Predefined Macros
  System-specific Predefined Macros
  C++ Named Operators
  Misnesting
  Operator Precedence Problems
  Swallowing the Semicolon
  Duplication of Side Effects
  Self-Referential Macros
  Argument Prescan
  Newlines in Arguments
  Conditional Uses
  Conditional Syntax
  Deleted Code
  Ifdef
  If
  Defined
  Else
  Elif
  Implementation-defined behavior
  Implementation limits
  Obsolete Features
  Differences from previous versions
  Assertions
  Obsolete once-only headers