How to interpret #-prefixed lines in C preprocessor output?

Question

The following is the code of hello.c :

#include <stdio.h>

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

I used the command gcc -E hello.c to preprocess it, and got the following output:

# 1 "hello.c"
# 1 "<built-in>"
# 1 "<command-line>"
# 1 "/usr/include/stdc-predef.h" 1 3 4
# 1 "<command-line>" 2
# 1 "hello.c"
# 1 "/usr/include/stdio.h" 1 3 4
# 27 "/usr/include/stdio.h" 3 4
# 1 "/usr/include/features.h" 1 3 4
# 375 "/usr/include/features.h" 3 4
# 1 "/usr/include/sys/cdefs.h" 1 3 4
# 392 "/usr/include/sys/cdefs.h" 3 4
# 1 "/usr/include/bits/wordsize.h" 1 3 4
# 393 "/usr/include/sys/cdefs.h" 2 3 4
# 376 "/usr/include/features.h" 2 3 4
# 399 "/usr/include/features.h" 3 4
# 1 "/usr/include/gnu/stubs.h" 1 3 4
# 10 "/usr/include/gnu/stubs.h" 3 4
# 1 "/usr/include/gnu/stubs-64.h" 1 3 4
# 11 "/usr/include/gnu/stubs.h" 2 3 4
# 400 "/usr/include/features.h" 2 3 4
# 28 "/usr/include/stdio.h" 2 3 4





# 1 "/usr/lib/gcc/x86_64-redhat-linux/4.8.5/include/stddef.h" 1 3 4
# 212 "/usr/lib/gcc/x86_64-redhat-linux/4.8.5/include/stddef.h" 3 4
typedef long unsigned int size_t;
# 34 "/usr/include/stdio.h" 2 3 4

# 1 "/usr/include/bits/types.h" 1 3 4
# 27 "/usr/include/bits/types.h" 3 4
# 1 "/usr/include/bits/wordsize.h" 1 3 4
# 28 "/usr/include/bits/types.h" 2 3 4


typedef unsigned char __u_char;
typedef unsigned short int __u_short;
typedef unsigned int __u_int;
typedef unsigned long int __u_long;


typedef signed char __int8_t;
typedef unsigned char __uint8_t;
typedef signed short int __int16_t;
typedef unsigned short int __uint16_t;
typedef signed int __int32_t;
typedef unsigned int __uint32_t;

typedef signed long int __int64_t;
typedef unsigned long int __uint64_t;
////I omitted a lot in the following.

I know these information can be used for debugging symbols. But I want to know the meaning of each FIELD. However, if you are able to answer the following ones, your answer will also be accepted.

1. What does # 1 "<built-in>" and # 1 "<command-line>"mean? Why it gave me message of built-in and command-line, which are totally not relevant?
2. What does #1 "/usr/include/stdc-predef.h" 1 3 4 mean? What is the meaning of 1 3 4?

Thanks. Please note that I know preprocessor will include the header files. I want to know the meaning of each FIELD of the preprocessed output.

Answer 1

The fields of the preprocessor output are documented in 9 Preprocessor Output of the GNU cpp manual.

The fields are:

# linenum filename [flags]
...

Such a line means that what follows it (...) originated at line number linenum in file filename. The optional flags are:-

‘1’

This indicates the start of a new file.

‘2’

This indicates returning to a file (after having included another file).

‘3’

This indicates that the following text comes from a system header file, so certain warnings should be suppressed.

‘4’

This indicates that the following text should be treated as being wrapped in an implicit extern "C" block.

You see that nesting arises from #include directives, e.g.

# 1 "hello.c"
# 1 "/usr/include/stdio.h" 1 3 4
# 27 "/usr/include/stdio.h" 3 4
# 1 "/usr/include/features.h" 1 3 4
# 375 "/usr/include/features.h" 3 4
# 1 "/usr/include/sys/cdefs.h" 1 3 4
...

tells us:

• At line #1 of "hello.c" start a new file "/usr/include/stdio.h",
• at line #27 of which start another new file "/usr/include/features.h"
• at line #375 of which start another new file "/usr/include/sys/cdefs.h"
• ...

It's not easy reading.

The special "filenames" <built-in> and <command-line> will always crop up in a context resembling:-

# 1 "hello.c"
# 1 "<built-in>"
# 1 "<command-line>"
# 1 "/usr/include/stdc-predef.h" 1 3 4
# 1 "<command-line>" 2
# 1 "hello.c"

at the top of the preprocessed output for any file. Details may vary with GCC version.

As you'd guess, <built-in> and <command-line> are not real files. They are non-file sources of preprocessor tokens that need to be represented somehow in the output format, so they are treated as if they were files. Call them pseudo-files.

<built-in> is the pseudo-file that contains the compiler's built-in macro definitions. For the way to see the contents of this pseudo-file, browse to GCC dump preprocessor defines.

<command-line> is of course the preprocessor (usually GCC) commandline, considered as a source of macro definitions (and possibly un-definitions), e.g.

gcc ... -DFOO=1 -UBAR ...

So your example:

# 1 "hello.c"
# 1 "<built-in>"
# 1 "<command-line>"
# 1 "/usr/include/stdc-predef.h" 1 3 4
# 1 "<command-line>" 2
# 1 "hello.c"
# 1 "/usr/include/stdio.h" 1 3 4
...

represents this process:

• Start reading hello.c, and then
• immediately read the built-in macros pseudo-file, and then
• immediately read the commandline pseudo-file, and then
• immediately read the pre-defined macros file /usr/include/stdc-predef.h as if it was pre-included on the commandline by -include /usr/include/stdc-predef.h, and then
• resume and finish reading the commandline pseudo-file, and then
• resume reading hello.c, and then
• start reading /usr/include/stdio.h
  ...