______________________________________________________________________

  16   Preprocessing directives                                    [cpp]

  ______________________________________________________________________

1 A preprocessing directive consists  of  a  sequence  of  preprocessing
  tokens.   The  first  token in the sequence is a # preprocessing token
  that is either the first character  in  the  source  file  (optionally
  after  white  space containing no new-line characters) or that follows
  white space containing at least  one  new-line  character.   The  last
  token in the sequence is the first new-line character that follows the
  first token in the sequence.1)
          preprocessing-file:
                  groupopt
          group:
                  group-part
                  group group-part
          group-part:
                  pp-tokensopt new-line
                  if-section
                  control-line
          if-section:
                  if-group elif-groupsopt else-groupopt endif-line
          if-group:
                  # if     constant-expression new-line groupopt
                  # ifdef  identifier new-line groupopt
                  # ifndef identifier new-line groupopt
          elif-groups:
                  elif-group
                  elif-groups elif-group
          elif-group:
                  # elif   constant-expression new-line groupopt
          else-group:
                  # else   new-line groupopt
          endif-line:
                  # endif  new-line

  _________________________
  1) Thus, preprocessing directives are commonly called "lines."   These
  "lines"  have  no  other syntactic significance, as all white space is
  equivalent except in certain situations during preprocessing (see  the
  #  character  string literal creation operator in _cpp.stringize_, for
  example).

          control-line:
                  # include pp-tokens new-line
                  # define  identifier replacement-list new-line
                  # define  identifier lparen identifier-listopt ) replacement-list new-line
                  # undef   identifier new-line
                  # line    pp-tokens new-line
                  # error   pp-tokensopt new-line
                  # pragma  pp-tokensopt new-line
                  #         new-line
          lparen:
                  the left-parenthesis character without preceding white-space
          replacement-list:
                  pp-tokensopt
          pp-tokens:
                  preprocessing-token
                  pp-tokens preprocessing-token
          new-line:
                  the new-line character

2 The only white-space characters that shall appear between  preprocess-
  ing  tokens  within  a  preprocessing  directive  (from just after the
  introducing # preprocessing token through just before the  terminating
  new-line  character)  are  space  and horizontal-tab (including spaces
  that have replaced comments or possibly other  white-space  characters
  in translation phase 3).

3 The  implementation can process and skip sections of source files con-
  ditionally, include other source files,  and  replace  macros.   These
  capabilities are called preprocessing, because conceptually they occur
  before translation of the resulting translation unit.

4 The preprocessing tokens within a preprocessing directive are not sub-
  ject to macro expansion unless otherwise stated.

  16.1  Conditional inclusion                                 [cpp.cond]

1 The  expression  that controls conditional inclusion shall be an inte-
  gral constant expression except that: it shall  not  contain  a  cast;
  identifiers  (including  those  lexically  identical  to keywords) are
  interpreted as described below;2) and it may  contain  unary  operator
  expressions of the form
          defined identifier
  or
          defined ( identifier )
  which  evaluate to 1 if the identifier is currently defined as a macro
  name (that is, if it is predefined or if it has been the subject of  a
  #define  preprocessing  directive without an intervening #undef direc-
  tive with the same subject identifier), zero if it is not.

  _________________________
  2) Because the controlling constant  expression  is  evaluated  during
  translation phase 4, all identifiers either are or are not macro names
  -- there simply are no keywords, enumeration constants, and so on.

2 Each preprocessing token that remains  after  all  macro  replacements
  have occurred shall be in the lexical form of a token (_lex.token_).

3 Preprocessing directives of the forms
          # if   constant-expression new-line groupopt
          # elif constant-expression new-line groupopt
  check   whether  the  controlling  constant  expression  evaluates  to
  nonzero.

4 Prior to evaluation, macro invocations in the  list  of  preprocessing
  tokens  that  will  become  the  controlling  constant  expression are
  replaced (except for those macro names modified by the  defined  unary
  operator),  just as in normal text.  If the token defined is generated
  as a result of this replacement process or use of  the  defined  unary
  operator  does not match one of the two specified forms prior to macro
  replacement, the behavior is undefined.  After all replacements due to
  macro  expansion  and  the defined unary operator have been performed,
  all remaining identifiers are replaced with the pp-number 0, and  then
  each  preprocessing  token  is  converted into a token.  The resulting
  tokens comprise the controlling constant expression which is evaluated
  according  to  the  rules of _expr.const_ using arithmetic that has at
  least the ranges specified in _lib.support.limits_,  except  that  int
  and  unsigned  int  act  as  if  they have the same representation as,
  respectively, long and  unsigned  long.   This  includes  interpreting
  character literals, which may involve converting escape sequences into
  execution character set members.  Whether the numeric value for  these
  character  literals matches the value obtained when an identical char-
  acter literal occurs in an expression (other  than  within  a  #if  or
  #elif  directive) is implementation-defined.3) Also, whether a single-
  character character literal may have a negative value  is  implementa-
  tion-defined.

5 Preprocessing directives of the forms
          # ifdef  identifier new-line groupopt
          # ifndef identifier new-line groupopt
  check whether the identifier is or is not currently defined as a macro
  name.  Their conditions are equivalent to #if defined  identifier  and
  #if !defined identifier respectively.

6 Each  directive's  condition  is checked in order.  If it evaluates to
  false (zero), the group that it controls is  skipped:  directives  are
  processed only through the name that determines the directive in order
  to keep track of the level of nested conditionals;  the  rest  of  the
  directives' preprocessing tokens are ignored, as are the other prepro-
  cessing tokens in the group.  Only the first group whose control  con-
  dition  evaluates to true (nonzero) is processed.  If none of the con-
  ditions evaluates to true, and there is a #else directive,  the  group
  _________________________
  3) Thus, the constant expression in the following #if directive and if
  statement is not guaranteed to evaluate to the same value in these two
  contexts.
          #if 'z' - 'a' == 25
          if ('z' - 'a' == 25)

  controlled  by  the #else is processed; lacking a #else directive, all
  the groups until the #endif are skipped.4)

  16.2  Source file inclusion                              [cpp.include]

1 A  #include  directive shall identify a header or source file that can
  be processed by the implementation.

2 A preprocessing directive of the form
          # include <h-char-sequence> new-line
  searches a sequence of  implementation-defined  places  for  a  header
  identified  uniquely  by  the  specified  sequence between the < and >
  delimiters, and causes the replacement of that directive by the entire
  contents  of  the  header.  How the places are specified or the header
  identified is implementation-defined.

3 A preprocessing directive of the form
          # include "q-char-sequence" new-line
  causes the replacement of that directive by the entire contents of the
  source  file identified by the specified sequence between the " delim-
  iters.  The named source file is searched for  in  an  implementation-
  defined  manner.   If  this  search is not supported, or if the search
  fails, the directive is reprocessed as if it read
          # include <h-char-sequence> new-line
  with the identical contained sequence (including > characters, if any)
  from the original directive.

4 A preprocessing directive of the form
          # include pp-tokens new-line
  (that does not match one of the two previous forms) is permitted.  The
  preprocessing tokens after include in the directive are processed just
  as in normal text.  (Each identifier currently defined as a macro name
  is replaced by its replacement list of  preprocessing  tokens.)If  the
  directive  resulting  after all replacements does not match one of the
  two previous forms, the behavior is undefined.5) The method by which a
  sequence of preprocessing tokens between a <  and  a  >  preprocessing
  token  pair or a pair of " characters is combined into a single header
  name preprocessing token is implementation-defined.

5 The mapping between the delimited sequence  and  the  external  source
  file  name  is  implementation-defined.   The  implementation provides
  unique mappings for sequences consisting  of  one  or  more  nondigits
  (_lex.name_)  followed  by  a  period  .)  and a single nondigit.  The
  implementation may ignore the distinctions of alphabetical case.
  _________________________
  4) As indicated by the syntax, a preprocessing token shall not  follow
  a #else or #endif directive before the terminating new-line character.
  However, comments may appear anywhere  in  a  source  file,  including
  within a preprocessing directive.
  5) Note that adjacent string literals are not concatenated into a sin-
  gle string literal (see the translation phases in _lex.phases_); thus,
  an expansion that results in two string literals is an invalid  direc-
  tive.

6 A #include preprocessing directive may appear in a  source  file  that
  has  been  read because of a #include directive in another file, up to
  an implementation-defined nesting limit.

7 [Example: The most common uses of  #include  preprocessing  directives
  are as in the following:
          #include <stdio.h>
          #include "myprog.h"
   --end example]

8 [Example: Here is a macro-replaced #include directive:
          #if VERSION == 1
                  #define INCFILE  "vers1.h"
          #elif VERSION == 2
                  #define INCFILE  "vers2.h"   /* and so on */
          #else
                  #define INCFILE  "versN.h"
          #endif
          #include INCFILE
   --end example]

  16.3  Macro replacement                                  [cpp.replace]

1 Two  replacement  lists are identical if and only if the preprocessing
  tokens in both have the same number, ordering,  spelling,  and  white-
  space  separation,  where  all  white-space separations are considered
  identical.

2 An identifier currently defined as a macro without use of  lparen  (an
  object-like  macro)  may be redefined by another #define preprocessing
  directive provided that the second definition is an object-like  macro
  definition  and the two replacement lists are identical, otherwise the
  program is ill-formed.

3 An identifier currently defined as a macro using lparen  (a  function-
  like  macro)  may be redefined by another #define preprocessing direc-
  tive provided that the second definition is a function-like macro def-
  inition  that  has the same number and spelling of parameters, and the
  two replacement lists are identical, otherwise  the  program  is  ill-
  formed.

4 The  number  of  arguments  in  an invocation of a function-like macro
  shall agree with the number of parameters in the macro definition, and
  there  shall exist a ) preprocessing token that terminates the invoca-
  tion.

5 A parameter identifier in a  function-like  macro  shall  be  uniquely
  declared within its scope.

6 The  identifier  immediately  following the define is called the macro
  name.  There is one name space for macro names.  Any white-space char-
  acters  preceding  or  following the replacement list of preprocessing
  tokens are not considered part of the replacement list for either form
  of macro.

7 If  a  #  preprocessing token, followed by an identifier, occurs lexi-
  cally at the point at which a preprocessing directive could begin, the
  identifier is not subject to macro replacement.

8 A preprocessing directive of the form
          # define identifier replacement-list new-line
  defines  an  object-like macro that causes each subsequent instance of
  the macro name6) to be replaced by the replacement list of preprocess-
  ing tokens that  constitute  the  remainder  of  the  directive.   The
  replacement  list  is then rescanned for more macro names as specified
  below.

9 A preprocessing directive of the form
          # define identifier lparen identifier-listopt ) replacement-list new-line
  defines a function-like macro with parameters,  similar  syntactically
  to a function call.  The parameters are specified by the optional list
  of identifiers, whose scope extends  from  their  declaration  in  the
  identifier  list  until  the  new-line  character  that terminates the
  #define preprocessing directive.   Each  subsequent  instance  of  the
  function-like  macro  name  followed  by a ( as the next preprocessing
  token introduces the sequence of preprocessing tokens that is replaced
  by  the  replacement  list  in  the  definition  (an invocation of the
  macro).  The replaced sequence of preprocessing tokens  is  terminated
  by  the  matching  ) preprocessing token, skipping intervening matched
  pairs of left and right parenthesis preprocessing tokens.  Within  the
  sequence  of  preprocessing  tokens making up an invocation of a func-
  tion-like macro, new-line is considered a normal  white-space  charac-
  ter.

10The  sequence  of  preprocessing  tokens  bounded  by the outside-most
  matching parentheses forms the list of arguments for the function-like
  macro.   The  individual  arguments  within  the list are separated by
  comma preprocessing tokens, but  comma  preprocessing  tokens  between
  matching  inner  parentheses  do  not  separate arguments.  If (before
  argument substitution)  any  argument  consists  of  no  preprocessing
  tokens,  the behavior is undefined.  If there are sequences of prepro-
  cessing tokens within the list of arguments that would  otherwise  act
  as preprocessing directives, the behavior is undefined.

  16.3.1  Argument substitution                              [cpp.subst]

1 After  the  arguments for the invocation of a function-like macro have
  been identified, argument substitution takes place.   A  parameter  in
  the replacement list, unless preceded by a # or ## preprocessing token
  or followed by a ## preprocessing token (see below),  is  replaced  by
  the  corresponding  argument  after  all macros contained therein have
  been expanded.  Before being substituted, each argument's  preprocess-
  ing tokens are completely macro replaced as if they formed the rest of
  _________________________
  6) Since, by macro-replacement time, all character literals and string
  literals  are  preprocessing tokens, not sequences possibly containing
  identifier-like subsequences (see 2.1.1.2, translation  phases),  they
  are never scanned for macro names or parameters.

  the translation unit; no other preprocessing tokens are available.

  16.3.2  The # operator                                 [cpp.stringize]

1 Each # preprocessing token in the replacement list for a function-like
  macro shall be followed by a parameter as the next preprocessing token
  in the replacement list.

2 If, in the replacement list, a parameter is immediately preceded by  a
  #  preprocessing token, both are replaced by a single character string
  literal preprocessing token that contains the spelling of the  prepro-
  cessing  token  sequence  for the corresponding argument.  Each occur-
  rence of white  space  between  the  argument's  preprocessing  tokens
  becomes  a  single  space  character  in the character string literal.
  White space before the first preprocessing token and  after  the  last
  preprocessing  token  comprising  the argument is deleted.  Otherwise,
  the original spelling of each preprocessing token in the  argument  is
  retained  in the character string literal, except for special handling
  for producing the spelling of string literals and character  literals:
  a \ character is inserted before each " and \ character of a character
  literal or string literal (including the delimiting " characters).  If
  the  replacement that results is not a valid character string literal,
  the behavior is undefined.  The order of evaluation of # and ## opera-
  tors is unspecified.

  16.3.3  The ## operator                                   [cpp.concat]

1 A  ##  preprocessing  token shall not occur at the beginning or at the
  end of a replacement list for either form of macro definition.

2 If, in the replacement list, a parameter is  immediately  preceded  or
  followed by a ## preprocessing token, the parameter is replaced by the
  corresponding argument's preprocessing token sequence.

3 For both object-like and function-like macro invocations,  before  the
  replacement  list  is reexamined for more macro names to replace, each
  instance of a ## preprocessing token in the replacement list (not from
  an  argument) is deleted and the preceding preprocessing token is con-
  catenated with the following preprocessing token.  If  the  result  is
  not  a  valid  preprocessing  token,  the  behavior is undefined.  The
  resulting token is available for further macro replacement.  The order
  of evaluation of ## operators is unspecified.

  16.3.4  Rescanning and further replacement                [cpp.rescan]

1 After  all  parameters  in the replacement list have been substituted,
  the resulting preprocessing token sequence is rescanned with all  sub-
  sequent  preprocessing  tokens of the source file for more macro names
  to replace.

2 If the name of the macro being replaced is found during this  scan  of
  the replacement list (not including the rest of the source file's pre-
  processing tokens), it  is  not  replaced.   Further,  if  any  nested
  replacements encounter the name of the macro being replaced, it is not

  replaced.  These nonreplaced macro name preprocessing  tokens  are  no
  longer  available  for  further  replacement  even  if  they are later
  (re)examined in contexts in which that macro name preprocessing  token
  would otherwise have been replaced.

3 The  resulting  completely macro-replaced preprocessing token sequence
  is not processed as a preprocessing directive  even  if  it  resembles
  one.

  16.3.5  Scope of macro definitions                         [cpp.scope]

1 A macro definition lasts (independent of block structure) until a cor-
  responding #undef directive is encountered or (if none is encountered)
  until the end of the translation unit.

2 A preprocessing directive of the form
          # undef identifier new-line
  causes  the  specified  identifier  no longer to be defined as a macro
  name.  It is ignored if the  specified  identifier  is  not  currently
  defined as a macro name.

3 [Note: The simplest use of this facility is to define a "manifest con-
  stant," as in
          #define TABSIZE 100
          int table[TABSIZE];

4 The following defines a function-like macro whose value is the maximum
  of its arguments.  It has the advantages of working for any compatible
  types of the arguments and of  generating  in-line  code  without  the
  overhead  of function calling.  It has the disadvantages of evaluating
  one or the other of  its  arguments  a  second  time  (including  side
  effects)  and  generating more code than a function if invoked several
  times.  It also cannot have its address taken, as it has none.
          #define max(a, b) ((a) > (b) ? (a) : (b))
  The parentheses ensure that the arguments and the resulting expression
  are bound properly.

5 To  illustrate  the  rules  for  redefinition  and  reexamination, the
  sequence
          #define x    3
          #define f(a) f(x * (a))
          #undef  x
          #define x    2
          #define g    f
          #define z    z[0]
          #define h    g(~
          #define m(a) a(w)
          #define w    0,1
          #define t(a) a
          f(y+1) + f(f(z)) % t(t(g)(0) + t)(1);
          g(x+(3,4)-w) | h 5) & m
                  (f)^m(m);
  results in

          f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1);
          f(2 * (2+(3,4)-0,1)) | f(2 * (~5)) & f(2 * (0,1))^m(0,1);

6 To illustrate the rules for creating  character  string  literals  and
  concatenating tokens, the sequence
          #define str(s)      # s
          #define xstr(s)     str(s)
          #define debug(s, t) printf("x" # s "= %d, x" # t "= %s", \
                                          x ## s, x ## t)
          #define INCFILE(n)  vers ## n  /* from previous #include example */
          #define glue(a, b)  a ## b
          #define xglue(a, b) glue(a, b)
          #define HIGHLOW     "hello"
          #define LOW         LOW ", world"
          debug(1, 2);
          fputs(str(strncmp("abc\0d", "abc", '\4')  /* this goes away */
                  == 0) str(: @\n), s);
          #include xstr(INCFILE(2).h)
          glue(HIGH, LOW);
          xglue(HIGH, LOW)
  results in
          printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
          fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": @\n", s);
          #include "vers2.h"    (after macro replacement, before file access)
          "hello";
          "hello" ", world"
  or, after concatenation of the character string literals,
          printf("x1= %d, x2= %s", x1, x2);
          fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: @\n", s);
          #include "vers2.h"    (after macro replacement, before file access)
          "hello";
          "hello, world"
  Space  around the # and ## tokens in the macro definition is optional.

7 And finally, to demonstrate  the  redefinition  rules,  the  following
  sequence is valid.
          #define OBJ_LIKE      (1-1)
          #define OBJ_LIKE      /* white space */ (1-1) /* other */
          #define FTN_LIKE(a)   ( a )
          #define FTN_LIKE( a )(          /* note the white space */ \
                                          a /* other stuff on this line
                                            */ )
  But the following redefinitions are invalid:
          #define OBJ_LIKE    (0)     /* different token sequence */
          #define OBJ_LIKE    (1 - 1) /* different white space */
          #define FTN_LIKE(b) ( a )   /* different parameter usage */
          #define FTN_LIKE(b) ( b )   /* different parameter spelling */
   --end note]

  16.4  Line control                                          [cpp.line]

1 The  string literal of a #line directive, if present, shall be a char-
  acter string literal.

2 The line number of the current source line is  one  greater  than  the
  number  of new-line characters read or introduced in translation phase
  1 (_lex.phases_) while processing  the  source  file  to  the  current
  token.

3 A preprocessing directive of the form
          # line digit-sequence new-line
  causes  the  implementation  to behave as if the following sequence of
  source lines begins with a source line that has a line number as spec-
  ified  by  the  digit sequence (interpreted as a decimal integer).  If
  the digit sequence specifies zero or a number greater than 32767,  the
  behavior is undefined.

4 A preprocessing directive of the form
          # line digit-sequence "s-char-sequenceopt" new-line
  sets  the  line  number similarly and changes the presumed name of the
  source file to be the contents of the character string literal.

5 A preprocessing directive of the form
          # line pp-tokens new-line
  (that does not match one of the two previous forms) is permitted.  The
  preprocessing tokens after line on the directive are processed just as
  in normal text (each identifier currently defined as a macro  name  is
  replaced  by  its  replacement  list of preprocessing tokens).  If the
  directive resulting after all replacements does not match one  of  the
  two  previous  forms, the behavior is undefined; otherwise, the result
  is processed as appropriate.

  16.5  Error directive                                      [cpp.error]

1 A preprocessing directive of the form
          # error pp-tokensopt new-line
  causes  the  implementation  to  produce  a  diagnostic  message  that
  includes  the  specified sequence of preprocessing tokens, and renders
  the program ill-formed.

  16.6  Pragma directive                                    [cpp.pragma]

1 A preprocessing directive of the form
          # pragma pp-tokensopt new-line
  causes the implementation to behave in an implementation-defined  man-
  ner.   Any  pragma  that  is  not  recognized by the implementation is
  ignored.

  16.7  Null directive                                        [cpp.null]

1 A preprocessing directive of the form
          # new-line
  has no effect.

  16.8  Predefined macro names                          [cpp.predefined]

1 The following macro names shall be defined by the implementation:

  __LINE__
    The line number of the current source line (a decimal constant).

  __FILE__
    The presumed name of the source file (a character string literal).

  __DATE__
    The date of translation of the source file (a character string  lit-
    eral  of  the  form "Mmm dd yyyy", where the names of the months are
    the same as those generated by the asctime function, and  the  first
    character  of dd is a space character if the value is less than 10).
    If the date of translation  is  not  available,  an  implementation-
    defined valid date is supplied.

  __TIME__
    The  time of translation of the source file (a character string lit-
    eral of the form "hh:mm:ss" as in the time generated by the  asctime
    function).   If  the time of translation is not available, an imple-
    mentation-defined valid time is supplied.

  __STDC__
    Whether __STDC__  is predefined and if so, what its  value  is,  are
    implementation-defined.

  __cplusplus
    The  name __cplusplus is defined to the value 199711L when compiling
    a C++ translation unit.7)

2 The values of the predefined macros (except for __LINE__ and __FILE__)
  remain constant throughout the translation unit.

3 If  any of the pre-defined macro names in this subclause, or the iden-
  tifier defined, is the subject of a #define or a #undef  preprocessing
  directive, the behavior is undefined.

  _________________________
  7) It is intended that future versions of this standard  will  replace
  the  value of this macro with a greater value.  Non-conforming compil-
  ers should use a value with at most five decimal digits.