The C Preprocessor

The C preprocessor is a macro processor that is used automatically by the C compiler to transform your program before actual compilation. It is called a macro processor because it allows you to define macros, which are brief abbreviations for longer constructs.

The C preprocessor provides four separate facilities that you can use as you see fit:

• 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, and then the C preprocessor will replace the macros with their definitions throughout the program.
• Conditional compilation. Using special preprocessing directives, 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 of where each source line originally came from.

C preprocessors vary in some details. This manual discusses the GNU C preprocessor, the C Compatible Compiler Preprocessor. The GNU C preprocessor provides a superset of the features of ANSI Standard C.

ANSI Standard C requires the rejection of many harmless constructs commonly used by today's C programs. Such incompatibility would be inconvenient for users, so the GNU C preprocessor is configured to accept these constructs by default. Strictly speaking, to get ANSI Standard C, you must use the options `-trigraphs', `-undef' and `-pedantic', but in practice the consequences of having strict ANSI Standard C make it undesirable to do this. See section Invoking the C Preprocessor.

• Global Actions: Actions made uniformly on all input files.
• Directives: General syntax of preprocessing directives.
• Header Files: How and why to use header files.
• Macros: How and why to use macros.
• Conditionals: How and why to use conditionals.
• Combining Sources: Use of line control when you combine source files.
• Other Directives: Miscellaneous preprocessing directives.
• Output: Format of output from the C preprocessor.
• Invocation: How to invoke the preprocessor; command options.
• Concept Index: Index of concepts and terms.
• Index: Index of directives, predefined macros and options.

Transformations Made Globally

Most C preprocessor features are inactive unless you give specific directives to request their use. (Preprocessing directives are lines starting with `#'; see section Preprocessing Directives). But there are three transformations that the preprocessor always makes on all the input it receives, even in the absence of directives.

• All C comments are replaced with single spaces.
• Backslash-Newline sequences are deleted, no matter where. This feature allows you to break long lines for cosmetic purposes without changing their meaning.
• Predefined macro names are replaced with their expansions (see section Predefined Macros).

The first two transformations are done before nearly all other parsing and before preprocessing directives are recognized. Thus, for example, you can split a line cosmetically with Backslash-Newline anywhere (except when trigraphs are in use; see below).

/*
*/ # /*
*/ defi\
ne FO\
O 10\
20

is equivalent into `#define FOO 1020'. You can split even an escape sequence with Backslash-Newline. For example, you can split "foo\bar" between the `\' and the `b' to get

"foo\\
bar"

This behavior is unclean: in all other contexts, a Backslash can be inserted in a string constant as an ordinary character by writing a double Backslash, and this creates an exception. But the ANSI C standard requires it. (Strict ANSI C does not allow Newlines in string constants, so they do not consider this a problem.)

But there are a few exceptions to all three transformations.

• C comments and predefined macro names are not recognized inside a `#include' directive in which the file name is delimited with `<' and `>'.
• C comments and predefined macro names are never recognized within a character or string constant. (Strictly speaking, this is the rule, not an exception, but it is worth noting here anyway.)
• Backslash-Newline may not safely be used within an ANSI "trigraph". Trigraphs are converted before Backslash-Newline is deleted. If you write what looks like a trigraph with a Backslash-Newline inside, the Backslash-Newline is deleted as usual, but it is then too late to recognize the trigraph. This exception is relevant only if you use the `-trigraphs' option to enable trigraph processing. See section Invoking the C Preprocessor.