gcc/doc/cppinternals/representation-of-line-numbers.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 Representation of line numbers
   7 ******************************
   8
   9 As mentioned above, cpplib stores with each token the line number that
  10 it was lexed on.  In fact, this number is not the number of the line in
  11 the source file, but instead bears more resemblance to the number of the
  12 line in the translation unit.
  13
  14 The preprocessor maintains a monotonic increasing line count, which is
  15 incremented at every new line character (and also at the end of any
  16 buffer that does not end in a new line).  Since a line number of zero is
  17 useful to indicate certain special states and conditions, this variable
  18 starts counting from one.
  19
  20 This variable therefore uniquely enumerates each line in the translation
  21 unit.  With some simple infrastructure, it is straight forward to map
  22 from this to the original source file and line number pair, saving space
  23 whenever line number information needs to be saved.  The code the
  24 implements this mapping lies in the files :samp:`line-map.cc` and
  25 :samp:`line-map.h`.
  26
  27 Command-line macros and assertions are implemented by pushing a buffer
  28 containing the right hand side of an equivalent ``#define`` or
  29 ``#assert`` directive.  Some built-in macros are handled similarly.
  30 Since these are all processed before the first line of the main input
  31 file, it will typically have an assigned line closer to twenty than to
  32 one.