<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1987-2015 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.3 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. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>The C Preprocessor: The preprocessing language</title>

<meta name="description" content="The C Preprocessor: The preprocessing language">
<meta name="keywords" content="The C Preprocessor: The preprocessing language">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Overview.html#Overview" rel="up" title="Overview">
<link href="Header-Files.html#Header-Files" rel="next" title="Header Files">
<link href="Tokenization.html#Tokenization" rel="prev" title="Tokenization">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="The-preprocessing-language"></a>
<div class="header">
<p>
Previous: <a href="Tokenization.html#Tokenization" accesskey="p" rel="prev">Tokenization</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="The-preprocessing-language-1"></a>
<h3 class="section">1.4 The preprocessing language</h3>
<a name="index-directives"></a>
<a name="index-preprocessing-directives"></a>
<a name="index-directive-line"></a>
<a name="index-directive-name"></a>

<p>After tokenization, the stream of tokens may simply be passed straight
to the compiler&rsquo;s parser.  However, if it contains any operations in the
<em>preprocessing language</em>, it will be transformed first.  This stage
corresponds roughly to the standard&rsquo;s &ldquo;translation phase 4&rdquo; and is
what most people think of as the preprocessor&rsquo;s job.
</p>
<p>The preprocessing language consists of <em>directives</em> to be executed
and <em>macros</em> to be expanded.  Its primary capabilities are:
</p>
<ul>
<li> Inclusion of header files.  These are files of declarations that can be
substituted into your program.

</li><li> Macro expansion.  You can define <em>macros</em>, 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.

</li><li> Conditional compilation.  You can include or exclude parts of the
program according to various conditions.

</li><li> 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.

</li><li> Diagnostics.  You can detect problems at compile time and issue errors
or warnings.
</li></ul>

<p>There are a few more, less useful, features.
</p>
<p>Except for expansion of predefined macros, all these operations are
triggered with <em>preprocessing directives</em>.  Preprocessing directives
are lines in your program that start with &lsquo;<samp>#</samp>&rsquo;.  Whitespace is
allowed before and after the &lsquo;<samp>#</samp>&rsquo;.  The &lsquo;<samp>#</samp>&rsquo; is followed by an
identifier, the <em>directive name</em>.  It specifies the operation to
perform.  Directives are commonly referred to as &lsquo;<samp>#<var>name</var></samp>&rsquo;
where <var>name</var> is the directive name.  For example, &lsquo;<samp>#define</samp>&rsquo; is
the directive that defines a macro.
</p>
<p>The &lsquo;<samp>#</samp>&rsquo; which begins a directive cannot come from a macro
expansion.  Also, the directive name is not macro expanded.  Thus, if
<code>foo</code> is defined as a macro expanding to <code>define</code>, that does
not make &lsquo;<samp>#foo</samp>&rsquo; a valid preprocessing directive.
</p>
<p>The set of valid directive names is fixed.  Programs cannot define new
preprocessing directives.
</p>
<p>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, &lsquo;<samp>#define</samp>&rsquo; must be followed by a macro
name and the intended expansion of the macro.
</p>
<p>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.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Tokenization.html#Tokenization" accesskey="p" rel="prev">Tokenization</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>