Whole document tree

1. 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 1.9 Invoking the C Preprocessor.

The C preprocessor is designed for C-like languages; you may run into problems if you apply it to other kinds of languages, because it assumes that it is dealing with C. For example, the C preprocessor sometimes outputs extra white space to avoid inadvertent C token concatenation, and this may cause problems with other languages.

1.1 Transformations Made Globally		Actions made uniformly on all input files.
1.2 Preprocessing Directives		General syntax of preprocessing directives.
1.3 Header Files		How and why to use header files.
1.4 Macros		How and why to use macros.
1.5 Conditionals		How and why to use conditionals.
1.6 Combining Source Files		Use of line control when you combine source files.
1.7 Miscellaneous Preprocessing Directives		Miscellaneous preprocessing directives.
1.8 C Preprocessor Output		Format of output from the C preprocessor.
1.9 Invoking the C Preprocessor		How to invoke the preprocessor; command options.
Concept Index		Index of concepts and terms.
Index of Directives, Macros and Options		Index of directives, predefined macros and options.