C Reference Manual Reading Notes: 008 The C Preprocessor and Preprocessor Commands

1. The C preprocessor

    The C preprocessor is a simple macroprocessor that conceptually processes the source text of a C program before the compiler proper reads the source program. In some implementations of C(like as gcc), the preprocessor is actually a separate program that reads the original source file and writes out a new "preprocessored" source file that can then be used as input to the C compiler. In other implementations, a single program performs the preprocessing and compilation in a single pass over the source file.

 

2. Preprocessor Commands

    The preprocessor is controlled by special preprocessor command lines, which are lines of the source file beginning with the character #. Lines that do not contain preprocessor commands are called lines of source program text. The preprocessor commands as follows:

         #define          Define a preprocessor macro

         #undef           Remove a preprocessor macro definition

         #include         Insert text from another source file

         #if                  Conditionally include some text based on the value of a constant expression

         #ifdef             Conditionally include some text based on whether a macro name is defined

         #ifndef           Conditionally include some text with the sense of the test opposite to that of #ifdef

         #else             Alternatively include some text if the previous #if,#fdef,#ifndef or #elif test failed

         #endif            Terminate conditional test

         #line              Supply a line number for compiler messages

         #elif               Alternatively include some text based on the value of another constant expression if the previous #if,

                               #ifdef,#ifndef, or #elif test failed

         defined          Preprocessor function that yields 1 if a name is defined as a preprocessor macro and 0 otherwise;

                               used in #if and #elif

         # operator     Replace a macro parameter with a string constant containing the parameter's value

         ## operator  Create a single token out of two adjacent tokens

         #pragma       Specify implementation-dependment information to the compiler

         #error           Produce a compile-time error with a designated message.

    The preprocessor  typically removes all preprocessor command lines from the source file and makes additional transformations on the source file as directed by the commands, such as expanding macro calls that occur within the source program text. The resulting preprocessed source text must then be a valid C program.

    The syntax of preprocessor commands is completely independent of (although in some ways similar to)the syntax of the rest of the C language. For example, it is possible for a macro definition to expand into a syntactically incomplete fragment as long as the fragment makes sense(i.e., is preperly completed) in all contexts in which the macro is called.