4.3 Preprocessing source files

It is possible to see the effect of the preprocessor on source files directly, using the -E option of gcc. For example, the file below defines and uses a macro TEST:

#define TEST "Hello, World!"
const char str[] = TEST;

If this file is called 'test.c' the effect of the preprocessor can be seen with the following command line:

$ gcc -E test.c
# 1 "test.c"

const char str[] = "Hello, World!" ;

The -E option causes gcc to run the preprocessor, display the expanded output, and then exit without compiling the resulting source code. The value of the macro TEST is substituted directly into the output, producing the sequence of characters const char str[] = "Hello, World!" ;.

The preprocessor also inserts lines recording the source file and line numbers in the form # line-number "source-file", to aid in debugging and allow the compiler to issue error messages referring to this information. These lines do not affect the program itself.

The ability to see the preprocessed source files can be useful for examining the effect of system header files, and finding declarations of system functions. The following program includes the header file 'stdio.h' to obtain the declaration of the function printf:

#include <stdio.h>

int
main (void)
{
  printf ("Hello, world!\n");
  return 0;
}

It is possible to see the declarations from the included header file by preprocessing the file with gcc -E:

$ gcc -E hello.c

On a GNU system, this produces output similar to the following:

# 1 "hello.c"
# 1 "/usr/include/stdio.h" 1 3
 
extern FILE *stdin;		 
extern FILE *stdout;		 
extern FILE *stderr;		 
 
extern int fprintf (FILE * __stream, 
                    const char * __format, ...)  ;
extern int printf (const char * __format, ...)  ;

 [ ... additional declarations ... ]

# 1 "hello.c" 2

int
main (void)
{
  printf ("Hello, world!\n");
  return 0;
}

The preprocessed system header files usually generate a lot of output. This can be redirected to a file, or saved more conveniently using the gcc -save-temps option:

$ gcc -c -save-temps hello.c

After running this command, the preprocessed output will be available in the file 'hello.i'. The -save-temps option also saves '.s' assembly files and '.o' object files in addition to preprocessed '.i' files.