gcc/doc/cpp/preprocessor-output.rst

   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
  86 the directive name.