]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. _preprocessor-output: | |
7 | ||
8 | Preprocessor Output | |
9 | ------------------- | |
10 | ||
11 | When the C preprocessor is used with the C, C++, or Objective-C | |
12 | compilers, it is integrated into the compiler and communicates a stream | |
13 | of binary tokens directly to the compiler's parser. However, it can | |
14 | also be used in the more conventional standalone mode, where it produces | |
15 | textual output. | |
16 | ||
17 | .. todo:: Document the library interface. | |
18 | ||
19 | .. index:: output format | |
20 | ||
21 | The output from the C preprocessor looks much like the input, except | |
22 | that all preprocessing directive lines have been replaced with blank | |
23 | lines and all comments with spaces. Long runs of blank lines are | |
24 | discarded. | |
25 | ||
26 | The ISO standard specifies that it is implementation defined whether a | |
27 | preprocessor preserves whitespace between tokens, or replaces it with | |
28 | e.g. a single space. In GNU CPP, whitespace between tokens is collapsed | |
29 | to become a single space, with the exception that the first token on a | |
30 | non-directive line is preceded with sufficient spaces that it appears in | |
31 | the same column in the preprocessed output that it appeared in the | |
32 | original source file. This is so the output is easy to read. | |
33 | CPP does not insert any | |
34 | whitespace where there was none in the original source, except where | |
35 | necessary to prevent an accidental token paste. | |
36 | ||
37 | .. index:: linemarkers | |
38 | ||
39 | Source file name and line number information is conveyed by lines | |
40 | of the form | |
41 | ||
42 | .. code-block:: c++ | |
43 | ||
44 | # linenum filename flags | |
45 | ||
46 | These are called :dfn:`linemarkers`. They are inserted as needed into | |
47 | the output (but never within a string or character constant). They mean | |
48 | that the following line originated in file :samp:`{filename}` at line | |
49 | :samp:`{linenum}`. :samp:`{filename}` will never contain any non-printing | |
50 | characters; they are replaced with octal escape sequences. | |
51 | ||
52 | After the file name comes zero or more flags, which are :samp:`1`, | |
53 | :samp:`2`, :samp:`3`, or :samp:`4`. If there are multiple flags, spaces | |
54 | separate them. Here is what the flags mean: | |
55 | ||
56 | :samp:`1` | |
57 | This indicates the start of a new file. | |
58 | ||
59 | :samp:`2` | |
60 | This indicates returning to a file (after having included another file). | |
61 | ||
62 | :samp:`3` | |
63 | This indicates that the following text comes from a system header file, | |
64 | so certain warnings should be suppressed. | |
65 | ||
66 | :samp:`4` | |
67 | This indicates that the following text should be treated as being | |
68 | wrapped in an implicit ``extern "C"`` block. | |
69 | ||
70 | .. maybe cross reference SYSTEM_IMPLICIT_EXTERN_C | |
71 | ||
72 | As an extension, the preprocessor accepts linemarkers in non-assembler | |
73 | input files. They are treated like the corresponding :samp:`#line` | |
74 | directive, (see :ref:`line-control`), except that trailing flags are | |
75 | permitted, and are interpreted with the meanings described above. If | |
76 | multiple flags are given, they must be in ascending order. | |
77 | ||
78 | Some directives may be duplicated in the output of the preprocessor. | |
79 | These are :samp:`#ident` (always), :samp:`#pragma` (only if the | |
80 | preprocessor does not handle the pragma itself), and :samp:`#define` and | |
81 | :samp:`#undef` (with certain debugging options). If this happens, the | |
82 | :samp:`#` of the directive will always be in the first column, and there | |
83 | will be no space between the :samp:`#` and the directive name. If macro | |
84 | expansion happens to generate tokens which might be mistaken for a | |
85 | duplicated directive, a space will be inserted between the :samp:`#` and | |
3ed1b4ce | 86 | the directive name. |