The C Preprocessor

Last revised July 2000

for GCC version 2

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 is intended only for macro processing of C, C++ and Objective C source files. For macro processing of other files, you are strongly encouraged to use alternatives like M4, which will likely give you better results and avoid many problems. For example, normally the C preprocessor does not preserve arbitrary whitespace verbatim, but instead replaces each sequence with a single space.

For use on C-like source files, 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, which provides a small superset of the features of ISO Standard C.

In its default mode, the GNU C preprocessor does not do a few things required by the standard. These are features which are rarely, if ever, used, and may cause surprising changes to the meaning of a program which does not expect them. To get strict ISO Standard C, you should use the `-std=c89' or `-std=c99' options, depending on which version of the standard you want. To get all the mandatory diagnostics, you must also use `-pedantic'. 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.
• Assertions: How and why to use assertions.
• Line Control: Use of line control when you combine source files.
• Other Directives: Miscellaneous preprocessing directives.
• Output: Format of output from the C preprocessor.
• Implementation: Implementation limits and behavior.
• Unreliable Features: Undefined behavior and deprecated features.
• Invocation: How to invoke the preprocessor; command options.
• Concept Index: Index of concepts and terms.
• Index: Index of directives, predefined macros and options.

This document was generated on 27 November 2000 using the texi2html translator version 1.54.