Return to cpp.info-2 CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/cpp.info-2, revision 1.1

1.1     ! root        1: This is Info file cpp.info, produced by Makeinfo-1.54 from the input
        !             2: file cpp.texi.
        !             3: 
        !             4:    This file documents the GNU C Preprocessor.
        !             5: 
        !             6:    Copyright 1987, 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
        !             7: 
        !             8:    Permission is granted to make and distribute verbatim copies of this
        !             9: manual provided the copyright notice and this permission notice are
        !            10: preserved on all copies.
        !            11: 
        !            12:    Permission is granted to copy and distribute modified versions of
        !            13: this manual under the conditions for verbatim copying, provided also
        !            14: that the entire resulting derived work is distributed under the terms
        !            15: of a permission notice identical to this one.
        !            16: 
        !            17:    Permission is granted to copy and distribute translations of this
        !            18: manual into another language, under the above conditions for modified
        !            19: versions.
        !            20: 
        !            21: 
        !            22: File: cpp.info,  Node: Swallow Semicolon,  Next: Side Effects,  Prev: Macro Parentheses,  Up: Macro Pitfalls
        !            23: 
        !            24: Swallowing the Semicolon
        !            25: ........................
        !            26: 
        !            27:    Often it is desirable to define a macro that expands into a compound
        !            28: statement.  Consider, for example, the following macro, that advances a
        !            29: pointer (the argument `p' says where to find it) across whitespace
        !            30: characters:
        !            31: 
        !            32:      #define SKIP_SPACES (p, limit)  \
        !            33:      { register char *lim = (limit); \
        !            34:        while (p != lim) {            \
        !            35:          if (*p++ != ' ') {          \
        !            36:            p--; break; }}}
        !            37: 
        !            38: Here Backslash-Newline is used to split the macro definition, which must
        !            39: be a single line, so that it resembles the way such C code would be
        !            40: laid out if not part of a macro definition.
        !            41: 
        !            42:    A call to this macro might be `SKIP_SPACES (p, lim)'.  Strictly
        !            43: speaking, the call expands to a compound statement, which is a complete
        !            44: statement with no need for a semicolon to end it.  But it looks like a
        !            45: function call.  So it minimizes confusion if you can use it like a
        !            46: function call, writing a semicolon afterward, as in `SKIP_SPACES (p,
        !            47: lim);'
        !            48: 
        !            49:    But this can cause trouble before `else' statements, because the
        !            50: semicolon is actually a null statement.  Suppose you write
        !            51: 
        !            52:      if (*p != 0)
        !            53:        SKIP_SPACES (p, lim);
        !            54:      else ...
        !            55: 
        !            56: The presence of two statements--the compound statement and a null
        !            57: statement--in between the `if' condition and the `else' makes invalid C
        !            58: code.
        !            59: 
        !            60:    The definition of the macro `SKIP_SPACES' can be altered to solve
        !            61: this problem, using a `do ... while' statement.  Here is how:
        !            62: 
        !            63:      #define SKIP_SPACES (p, limit)     \
        !            64:      do { register char *lim = (limit); \
        !            65:           while (p != lim) {            \
        !            66:             if (*p++ != ' ') {          \
        !            67:               p--; break; }}}           \
        !            68:      while (0)
        !            69: 
        !            70:    Now `SKIP_SPACES (p, lim);' expands into
        !            71: 
        !            72:      do {...} while (0);
        !            73: 
        !            74: which is one statement.
        !            75: 
        !            76: 
        !            77: File: cpp.info,  Node: Side Effects,  Next: Self-Reference,  Prev: Swallow Semicolon,  Up: Macro Pitfalls
        !            78: 
        !            79: Duplication of Side Effects
        !            80: ...........................
        !            81: 
        !            82:    Many C programs define a macro `min', for "minimum", like this:
        !            83: 
        !            84:      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
        !            85: 
        !            86:    When you use this macro with an argument containing a side effect,
        !            87: as shown here,
        !            88: 
        !            89:      next = min (x + y, foo (z));
        !            90: 
        !            91: it expands as follows:
        !            92: 
        !            93:      next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
        !            94: 
        !            95: where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
        !            96: 
        !            97:    The function `foo' is used only once in the statement as it appears
        !            98: in the program, but the expression `foo (z)' has been substituted twice
        !            99: into the macro expansion.  As a result, `foo' might be called two times
        !           100: when the statement is executed.  If it has side effects or if it takes
        !           101: a long time to compute, the results might not be what you intended.  We
        !           102: say that `min' is an "unsafe" macro.
        !           103: 
        !           104:    The best solution to this problem is to define `min' in a way that
        !           105: computes the value of `foo (z)' only once.  The C language offers no
        !           106: standard way to do this, but it can be done with GNU C extensions as
        !           107: follows:
        !           108: 
        !           109:      #define min(X, Y)                     \
        !           110:      ({ typeof (X) __x = (X), __y = (Y);   \
        !           111:         (__x < __y) ? __x : __y; })
        !           112: 
        !           113:    If you do not wish to use GNU C extensions, the only solution is to
        !           114: be careful when *using* the macro `min'.  For example, you can
        !           115: calculate the value of `foo (z)', save it in a variable, and use that
        !           116: variable in `min':
        !           117: 
        !           118:      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
        !           119:      ...
        !           120:      {
        !           121:        int tem = foo (z);
        !           122:        next = min (x + y, tem);
        !           123:      }
        !           124: 
        !           125: (where we assume that `foo' returns type `int').
        !           126: 
        !           127: 
        !           128: File: cpp.info,  Node: Self-Reference,  Next: Argument Prescan,  Prev: Side Effects,  Up: Macro Pitfalls
        !           129: 
        !           130: Self-Referential Macros
        !           131: .......................
        !           132: 
        !           133:    A "self-referential" macro is one whose name appears in its
        !           134: definition.  A special feature of ANSI Standard C is that the
        !           135: self-reference is not considered a macro call.  It is passed into the
        !           136: preprocessor output unchanged.
        !           137: 
        !           138:    Let's consider an example:
        !           139: 
        !           140:      #define foo (4 + foo)
        !           141: 
        !           142: where `foo' is also a variable in your program.
        !           143: 
        !           144:    Following the ordinary rules, each reference to `foo' will expand
        !           145: into `(4 + foo)'; then this will be rescanned and will expand into `(4
        !           146: + (4 + foo))'; and so on until it causes a fatal error (memory full) in
        !           147: the preprocessor.
        !           148: 
        !           149:    However, the special rule about self-reference cuts this process
        !           150: short after one step, at `(4 + foo)'.  Therefore, this macro definition
        !           151: has the possibly useful effect of causing the program to add 4 to the
        !           152: value of `foo' wherever `foo' is referred to.
        !           153: 
        !           154:    In most cases, it is a bad idea to take advantage of this feature.  A
        !           155: person reading the program who sees that `foo' is a variable will not
        !           156: expect that it is a macro as well.  The reader will come across the
        !           157: identifier `foo' in the program and think its value should be that of
        !           158: the variable `foo', whereas in fact the value is four greater.
        !           159: 
        !           160:    The special rule for self-reference applies also to "indirect"
        !           161: self-reference.  This is the case where a macro X expands to use a
        !           162: macro `y', and the expansion of `y' refers to the macro `x'.  The
        !           163: resulting reference to `x' comes indirectly from the expansion of `x',
        !           164: so it is a self-reference and is not further expanded.  Thus, after
        !           165: 
        !           166:      #define x (4 + y)
        !           167:      #define y (2 * x)
        !           168: 
        !           169: `x' would expand into `(4 + (2 * x))'.  Clear?
        !           170: 
        !           171:    But suppose `y' is used elsewhere, not from the definition of `x'.
        !           172: Then the use of `x' in the expansion of `y' is not a self-reference
        !           173: because `x' is not "in progress".  So it does expand.  However, the
        !           174: expansion of `x' contains a reference to `y', and that is an indirect
        !           175: self-reference now because `y' is "in progress".  The result is that
        !           176: `y' expands to `(2 * (4 + y))'.
        !           177: 
        !           178:    It is not clear that this behavior would ever be useful, but it is
        !           179: specified by the ANSI C standard, so you may need to understand it.
        !           180: 
        !           181: 
        !           182: File: cpp.info,  Node: Argument Prescan,  Next: Cascaded Macros,  Prev: Self-Reference,  Up: Macro Pitfalls
        !           183: 
        !           184: Separate Expansion of Macro Arguments
        !           185: .....................................
        !           186: 
        !           187:    We have explained that the expansion of a macro, including the
        !           188: substituted actual arguments, is scanned over again for macro calls to
        !           189: be expanded.
        !           190: 
        !           191:    What really happens is more subtle: first each actual argument text
        !           192: is scanned separately for macro calls.  Then the results of this are
        !           193: substituted into the macro body to produce the macro expansion, and the
        !           194: macro expansion is scanned again for macros to expand.
        !           195: 
        !           196:    The result is that the actual arguments are scanned *twice* to expand
        !           197: macro calls in them.
        !           198: 
        !           199:    Most of the time, this has no effect.  If the actual argument
        !           200: contained any macro calls, they are expanded during the first scan.
        !           201: The result therefore contains no macro calls, so the second scan does
        !           202: not change it.  If the actual argument were substituted as given, with
        !           203: no prescan, the single remaining scan would find the same macro calls
        !           204: and produce the same results.
        !           205: 
        !           206:    You might expect the double scan to change the results when a
        !           207: self-referential macro is used in an actual argument of another macro
        !           208: (*note Self-Reference::.): the self-referential macro would be expanded
        !           209: once in the first scan, and a second time in the second scan.  But this
        !           210: is not what happens.  The self-references that do not expand in the
        !           211: first scan are marked so that they will not expand in the second scan
        !           212: either.
        !           213: 
        !           214:    The prescan is not done when an argument is stringified or
        !           215: concatenated.  Thus,
        !           216: 
        !           217:      #define str(s) #s
        !           218:      #define foo 4
        !           219:      str (foo)
        !           220: 
        !           221: expands to `"foo"'.  Once more, prescan has been prevented from having
        !           222: any noticeable effect.
        !           223: 
        !           224:    More precisely, stringification and concatenation use the argument as
        !           225: written, in un-prescanned form.  The same actual argument would be used
        !           226: in prescanned form if it is substituted elsewhere without
        !           227: stringification or concatenation.
        !           228: 
        !           229:      #define str(s) #s lose(s)
        !           230:      #define foo 4
        !           231:      str (foo)
        !           232: 
        !           233:    expands to `"foo" lose(4)'.
        !           234: 
        !           235:    You might now ask, "Why mention the prescan, if it makes no
        !           236: difference?  And why not skip it and make the preprocessor faster?"
        !           237: The answer is that the prescan does make a difference in three special
        !           238: cases:
        !           239: 
        !           240:    * Nested calls to a macro.
        !           241: 
        !           242:    * Macros that call other macros that stringify or concatenate.
        !           243: 
        !           244:    * Macros whose expansions contain unshielded commas.
        !           245: 
        !           246:    We say that "nested" calls to a macro occur when a macro's actual
        !           247: argument contains a call to that very macro.  For example, if `f' is a
        !           248: macro that expects one argument, `f (f (1))' is a nested pair of calls
        !           249: to `f'.  The desired expansion is made by expanding `f (1)' and
        !           250: substituting that into the definition of `f'.  The prescan causes the
        !           251: expected result to happen.  Without the prescan, `f (1)' itself would
        !           252: be substituted as an actual argument, and the inner use of `f' would
        !           253: appear during the main scan as an indirect self-reference and would not
        !           254: be expanded.  Here, the prescan cancels an undesirable side effect (in
        !           255: the medical, not computational, sense of the term) of the special rule
        !           256: for self-referential macros.
        !           257: 
        !           258:    But prescan causes trouble in certain other cases of nested macro
        !           259: calls.  Here is an example:
        !           260: 
        !           261:      #define foo  a,b
        !           262:      #define bar(x) lose(x)
        !           263:      #define lose(x) (1 + (x))
        !           264:      
        !           265:      bar(foo)
        !           266: 
        !           267: We would like `bar(foo)' to turn into `(1 + (foo))', which would then
        !           268: turn into `(1 + (a,b))'.  But instead, `bar(foo)' expands into
        !           269: `lose(a,b)', and you get an error because `lose' requires a single
        !           270: argument.  In this case, the problem is easily solved by the same
        !           271: parentheses that ought to be used to prevent misnesting of arithmetic
        !           272: operations:
        !           273: 
        !           274:      #define foo (a,b)
        !           275:      #define bar(x) lose((x))
        !           276: 
        !           277:    The problem is more serious when the operands of the macro are not
        !           278: expressions; for example, when they are statements.  Then parentheses
        !           279: are unacceptable because they would make for invalid C code:
        !           280: 
        !           281:      #define foo { int a, b; ... }
        !           282: 
        !           283: In GNU C you can shield the commas using the `({...})' construct which
        !           284: turns a compound statement into an expression:
        !           285: 
        !           286:      #define foo ({ int a, b; ... })
        !           287: 
        !           288:    Or you can rewrite the macro definition to avoid such commas:
        !           289: 
        !           290:      #define foo { int a; int b; ... }
        !           291: 
        !           292:    There is also one case where prescan is useful.  It is possible to
        !           293: use prescan to expand an argument and then stringify it--if you use two
        !           294: levels of macros.  Let's add a new macro `xstr' to the example shown
        !           295: above:
        !           296: 
        !           297:      #define xstr(s) str(s)
        !           298:      #define str(s) #s
        !           299:      #define foo 4
        !           300:      xstr (foo)
        !           301: 
        !           302:    This expands into `"4"', not `"foo"'.  The reason for the difference
        !           303: is that the argument of `xstr' is expanded at prescan (because `xstr'
        !           304: does not specify stringification or concatenation of the argument).
        !           305: The result of prescan then forms the actual argument for `str'.  `str'
        !           306: uses its argument without prescan because it performs stringification;
        !           307: but it cannot prevent or undo the prescanning already done by `xstr'.
        !           308: 
        !           309: 
        !           310: File: cpp.info,  Node: Cascaded Macros,  Next: Newlines in Args,  Prev: Argument Prescan,  Up: Macro Pitfalls
        !           311: 
        !           312: Cascaded Use of Macros
        !           313: ......................
        !           314: 
        !           315:    A "cascade" of macros is when one macro's body contains a reference
        !           316: to another macro.  This is very common practice.  For example,
        !           317: 
        !           318:      #define BUFSIZE 1020
        !           319:      #define TABLESIZE BUFSIZE
        !           320: 
        !           321:    This is not at all the same as defining `TABLESIZE' to be `1020'.
        !           322: The `#define' for `TABLESIZE' uses exactly the body you specify--in
        !           323: this case, `BUFSIZE'--and does not check to see whether it too is the
        !           324: name of a macro.
        !           325: 
        !           326:    It's only when you *use* `TABLESIZE' that the result of its expansion
        !           327: is checked for more macro names.
        !           328: 
        !           329:    This makes a difference if you change the definition of `BUFSIZE' at
        !           330: some point in the source file.  `TABLESIZE', defined as shown, will
        !           331: always expand using the definition of `BUFSIZE' that is currently in
        !           332: effect:
        !           333: 
        !           334:      #define BUFSIZE 1020
        !           335:      #define TABLESIZE BUFSIZE
        !           336:      #undef BUFSIZE
        !           337:      #define BUFSIZE 37
        !           338: 
        !           339: Now `TABLESIZE' expands (in two stages) to `37'.
        !           340: 
        !           341: 
        !           342: File: cpp.info,  Node: Newlines in Args,  Prev: Cascaded Macros,  Up: Macro Pitfalls
        !           343: 
        !           344: Newlines in Macro Arguments
        !           345: ---------------------------
        !           346: 
        !           347:    Traditional macro processing carries forward all newlines in macro
        !           348: arguments into the expansion of the macro.  This means that, if some of
        !           349: the arguments are substituted more than once, or not at all, or out of
        !           350: order, newlines can be duplicated, lost, or moved around within the
        !           351: expansion.  If the expansion consists of multiple statements, then the
        !           352: effect is to distort the line numbers of some of these statements.  The
        !           353: result can be incorrect line numbers, in error messages or displayed in
        !           354: a debugger.
        !           355: 
        !           356:    The GNU C preprocessor operating in ANSI C mode adjusts appropriately
        !           357: for multiple use of an argument--the first use expands all the
        !           358: newlines, and subsequent uses of the same argument produce no newlines.
        !           359: But even in this mode, it can produce incorrect line numbering if
        !           360: arguments are used out of order, or not used at all.
        !           361: 
        !           362:    Here is an example illustrating this problem:
        !           363: 
        !           364:      #define ignore_second_arg(a,b,c) a; c
        !           365:      
        !           366:      ignore_second_arg (foo (),
        !           367:                         ignored (),
        !           368:                         syntax error);
        !           369: 
        !           370: The syntax error triggered by the tokens `syntax error' results in an
        !           371: error message citing line four, even though the statement text comes
        !           372: from line five.
        !           373: 
        !           374: 
        !           375: File: cpp.info,  Node: Conditionals,  Next: Combining Sources,  Prev: Macros,  Up: Top
        !           376: 
        !           377: Conditionals
        !           378: ============
        !           379: 
        !           380:    In a macro processor, a "conditional" is a command that allows a part
        !           381: of the program to be ignored during compilation, on some conditions.
        !           382: In the C preprocessor, a conditional can test either an arithmetic
        !           383: expression or whether a name is defined as a macro.
        !           384: 
        !           385:    A conditional in the C preprocessor resembles in some ways an `if'
        !           386: statement in C, but it is important to understand the difference between
        !           387: them.  The condition in an `if' statement is tested during the execution
        !           388: of your program.  Its purpose is to allow your program to behave
        !           389: differently from run to run, depending on the data it is operating on.
        !           390: The condition in a preprocessor conditional command is tested when your
        !           391: program is compiled.  Its purpose is to allow different code to be
        !           392: included in the program depending on the situation at the time of
        !           393: compilation.
        !           394: 
        !           395: * Menu:
        !           396: 
        !           397: * Uses: Conditional Uses.       What conditionals are for.
        !           398: * Syntax: Conditional Syntax.   How conditionals are written.
        !           399: * Deletion: Deleted Code.       Making code into a comment.
        !           400: * Macros: Conditionals-Macros.  Why conditionals are used with macros.
        !           401: * Assertions::                 How and why to use assertions.
        !           402: * Errors: #error Command.       Detecting inconsistent compilation parameters.
        !           403: 
        !           404: 
        !           405: File: cpp.info,  Node: Conditional Uses,  Next: Conditional Syntax,  Up: Conditionals
        !           406: 
        !           407: Why Conditionals are Used
        !           408: -------------------------
        !           409: 
        !           410:    Generally there are three kinds of reason to use a conditional.
        !           411: 
        !           412:    * A program may need to use different code depending on the machine
        !           413:      or operating system it is to run on.  In some cases the code for
        !           414:      one operating system may be erroneous on another operating system;
        !           415:      for example, it might refer to library routines that do not exist
        !           416:      on the other system.  When this happens, it is not enough to avoid
        !           417:      executing the invalid code: merely having it in the program makes
        !           418:      it impossible to link the program and run it.  With a preprocessor
        !           419:      conditional, the offending code can be effectively excised from
        !           420:      the program when it is not valid.
        !           421: 
        !           422:    * You may want to be able to compile the same source file into two
        !           423:      different programs.  Sometimes the difference between the programs
        !           424:      is that one makes frequent time-consuming consistency checks on its
        !           425:      intermediate data while the other does not.
        !           426: 
        !           427:    * A conditional whose condition is always false is a good way to
        !           428:      exclude code from the program but keep it as a sort of comment for
        !           429:      future reference.
        !           430: 
        !           431:    Most simple programs that are intended to run on only one machine
        !           432: will not need to use preprocessor conditionals.
        !           433: 
        !           434: 
        !           435: File: cpp.info,  Node: Conditional Syntax,  Next: Deleted Code,  Prev: Conditional Uses,  Up: Conditionals
        !           436: 
        !           437: Syntax of Conditionals
        !           438: ----------------------
        !           439: 
        !           440:    A conditional in the C preprocessor begins with a "conditional
        !           441: command": `#if', `#ifdef' or `#ifndef'.  *Note Conditionals-Macros::,
        !           442: for information on `#ifdef' and `#ifndef'; only `#if' is explained here.
        !           443: 
        !           444: * Menu:
        !           445: 
        !           446: * If: #if Command.     Basic conditionals using `#if' and `#endif'.
        !           447: * Else: #else Command. Including some text if the condition fails.
        !           448: * Elif: #elif Command. Testing several alternative possibilities.
        !           449: 
        !           450: 
        !           451: File: cpp.info,  Node: #if Command,  Next: #else Command,  Up: Conditional Syntax
        !           452: 
        !           453: The `#if' Command
        !           454: .................
        !           455: 
        !           456:    The `#if' command in its simplest form consists of
        !           457: 
        !           458:      #if EXPRESSION
        !           459:      CONTROLLED TEXT
        !           460:      #endif /* EXPRESSION */
        !           461: 
        !           462:    The comment following the `#endif' is not required, but it is a good
        !           463: practice because it helps people match the `#endif' to the
        !           464: corresponding `#if'.  Such comments should always be used, except in
        !           465: short conditionals that are not nested.  In fact, you can put anything
        !           466: at all after the `#endif' and it will be ignored by the GNU C
        !           467: preprocessor, but only comments are acceptable in ANSI Standard C.
        !           468: 
        !           469:    EXPRESSION is a C expression of integer type, subject to stringent
        !           470: restrictions.  It may contain
        !           471: 
        !           472:    * Integer constants, which are all regarded as `long' or `unsigned
        !           473:      long'.
        !           474: 
        !           475:    * Character constants, which are interpreted according to the
        !           476:      character set and conventions of the machine and operating system
        !           477:      on which the preprocessor is running.  The GNU C preprocessor uses
        !           478:      the C data type `char' for these character constants; therefore,
        !           479:      whether some character codes are negative is determined by the C
        !           480:      compiler used to compile the preprocessor.  If it treats `char' as
        !           481:      signed, then character codes large enough to set the sign bit will
        !           482:      be considered negative; otherwise, no character code is considered
        !           483:      negative.
        !           484: 
        !           485:    * Arithmetic operators for addition, subtraction, multiplication,
        !           486:      division, bitwise operations, shifts, comparisons, and `&&' and
        !           487:      `||'.
        !           488: 
        !           489:    * Identifiers that are not macros, which are all treated as zero(!).
        !           490: 
        !           491:    * Macro calls.  All macro calls in the expression are expanded before
        !           492:      actual computation of the expression's value begins.
        !           493: 
        !           494:    Note that `sizeof' operators and `enum'-type values are not allowed.
        !           495: `enum'-type values, like all other identifiers that are not taken as
        !           496: macro calls and expanded, are treated as zero.
        !           497: 
        !           498:    The CONTROLLED TEXT inside of a conditional can include preprocessor
        !           499: commands.  Then the commands inside the conditional are obeyed only if
        !           500: that branch of the conditional succeeds.  The text can also contain
        !           501: other conditional groups.  However, the `#if' and `#endif' commands
        !           502: must balance.
        !           503: 
        !           504: 
        !           505: File: cpp.info,  Node: #else Command,  Next: #elif Command,  Prev: #if Command,  Up: Conditional Syntax
        !           506: 
        !           507: The `#else' Command
        !           508: ...................
        !           509: 
        !           510:    The `#else' command can be added to a conditional to provide
        !           511: alternative text to be used if the condition is false.  This is what it
        !           512: looks like:
        !           513: 
        !           514:      #if EXPRESSION
        !           515:      TEXT-IF-TRUE
        !           516:      #else /* Not EXPRESSION */
        !           517:      TEXT-IF-FALSE
        !           518:      #endif /* Not EXPRESSION */
        !           519: 
        !           520:    If EXPRESSION is nonzero, and thus the TEXT-IF-TRUE is active, then
        !           521: `#else' acts like a failing conditional and the TEXT-IF-FALSE is
        !           522: ignored.  Contrariwise, if the `#if' conditional fails, the
        !           523: TEXT-IF-FALSE is considered included.
        !           524: 
        !           525: 
        !           526: File: cpp.info,  Node: #elif Command,  Prev: #else Command,  Up: Conditional Syntax
        !           527: 
        !           528: The `#elif' Command
        !           529: ...................
        !           530: 
        !           531:    One common case of nested conditionals is used to check for more
        !           532: than two possible alternatives.  For example, you might have
        !           533: 
        !           534:      #if X == 1
        !           535:      ...
        !           536:      #else /* X != 1 */
        !           537:      #if X == 2
        !           538:      ...
        !           539:      #else /* X != 2 */
        !           540:      ...
        !           541:      #endif /* X != 2 */
        !           542:      #endif /* X != 1 */
        !           543: 
        !           544:    Another conditional command, `#elif', allows this to be abbreviated
        !           545: as follows:
        !           546: 
        !           547:      #if X == 1
        !           548:      ...
        !           549:      #elif X == 2
        !           550:      ...
        !           551:      #else /* X != 2 and X != 1*/
        !           552:      ...
        !           553:      #endif /* X != 2 and X != 1*/
        !           554: 
        !           555:    `#elif' stands for "else if".  Like `#else', it goes in the middle
        !           556: of a `#if'-`#endif' pair and subdivides it; it does not require a
        !           557: matching `#endif' of its own.  Like `#if', the `#elif' command includes
        !           558: an expression to be tested.
        !           559: 
        !           560:    The text following the `#elif' is processed only if the original
        !           561: `#if'-condition failed and the `#elif' condition succeeds.  More than
        !           562: one `#elif' can go in the same `#if'-`#endif' group.  Then the text
        !           563: after each `#elif' is processed only if the `#elif' condition succeeds
        !           564: after the original `#if' and any previous `#elif' commands within it
        !           565: have failed.  `#else' is equivalent to `#elif 1', and `#else' is
        !           566: allowed after any number of `#elif' commands, but `#elif' may not follow
        !           567: `#else'.
        !           568: 
        !           569: 
        !           570: File: cpp.info,  Node: Deleted Code,  Next: Conditionals-Macros,  Prev: Conditional Syntax,  Up: Conditionals
        !           571: 
        !           572: Keeping Deleted Code for Future Reference
        !           573: -----------------------------------------
        !           574: 
        !           575:    If you replace or delete a part of the program but want to keep the
        !           576: old code around as a comment for future reference, the easy way to do
        !           577: this is to put `#if 0' before it and `#endif' after it.
        !           578: 
        !           579:    This works even if the code being turned off contains conditionals,
        !           580: but they must be entire conditionals (balanced `#if' and `#endif').
        !           581: 
        !           582: 
        !           583: File: cpp.info,  Node: Conditionals-Macros,  Next: Assertions,  Prev: Deleted Code,  Up: Conditionals
        !           584: 
        !           585: Conditionals and Macros
        !           586: -----------------------
        !           587: 
        !           588:    Conditionals are useful in connection with macros or assertions,
        !           589: because those are the only ways that an expression's value can vary
        !           590: from one compilation to another.  A `#if' command whose expression uses
        !           591: no macros or assertions is equivalent to `#if 1' or `#if 0'; you might
        !           592: as well determine which one, by computing the value of the expression
        !           593: yourself, and then simplify the program.
        !           594: 
        !           595:    For example, here is a conditional that tests the expression
        !           596: `BUFSIZE == 1020', where `BUFSIZE' must be a macro.
        !           597: 
        !           598:      #if BUFSIZE == 1020
        !           599:        printf ("Large buffers!\n");
        !           600:      #endif /* BUFSIZE is large */
        !           601: 
        !           602:    (Programmers often wish they could test the size of a variable or
        !           603: data type in `#if', but this does not work.  The preprocessor does not
        !           604: understand `sizeof', or typedef names, or even the type keywords such
        !           605: as `int'.)
        !           606: 
        !           607:    The special operator `defined' is used in `#if' expressions to test
        !           608: whether a certain name is defined as a macro.  Either `defined NAME' or
        !           609: `defined (NAME)' is an expression whose value is 1 if NAME is defined
        !           610: as macro at the current point in the program, and 0 otherwise.  For the
        !           611: `defined' operator it makes no difference what the definition of the
        !           612: macro is; all that matters is whether there is a definition.  Thus, for
        !           613: example,
        !           614: 
        !           615:      #if defined (vax) || defined (ns16000)
        !           616: 
        !           617: would include the following code if either of the names `vax' and
        !           618: `ns16000' is defined as a macro.  You can test the same condition using
        !           619: assertions (*note Assertions::.), like this:
        !           620: 
        !           621:      #if #cpu (vax) || #cpu (ns16000)
        !           622: 
        !           623:    If a macro is defined and later undefined with `#undef', subsequent
        !           624: use of the `defined' operator returns 0, because the name is no longer
        !           625: defined.  If the macro is defined again with another `#define',
        !           626: `defined' will recommence returning 1.
        !           627: 
        !           628:    Conditionals that test just the definedness of one name are very
        !           629: common, so there are two special short conditional commands for this
        !           630: case.
        !           631: 
        !           632: `#ifdef NAME'
        !           633:      is equivalent to `#if defined (NAME)'.
        !           634: 
        !           635: `#ifndef NAME'
        !           636:      is equivalent to `#if ! defined (NAME)'.
        !           637: 
        !           638:    Macro definitions can vary between compilations for several reasons.
        !           639: 
        !           640:    * Some macros are predefined on each kind of machine.  For example,
        !           641:      on a Vax, the name `vax' is a predefined macro.  On other
        !           642:      machines, it would not be defined.
        !           643: 
        !           644:    * Many more macros are defined by system header files.  Different
        !           645:      systems and machines define different macros, or give them
        !           646:      different values.  It is useful to test these macros with
        !           647:      conditionals to avoid using a system feature on a machine where it
        !           648:      is not implemented.
        !           649: 
        !           650:    * Macros are a common way of allowing users to customize a program
        !           651:      for different machines or applications.  For example, the macro
        !           652:      `BUFSIZE' might be defined in a configuration file for your
        !           653:      program that is included as a header file in each source file.  You
        !           654:      would use `BUFSIZE' in a preprocessor conditional in order to
        !           655:      generate different code depending on the chosen configuration.
        !           656: 
        !           657:    * Macros can be defined or undefined with `-D' and `-U' command
        !           658:      options when you compile the program.  You can arrange to compile
        !           659:      the same source file into two different programs by choosing a
        !           660:      macro name to specify which program you want, writing conditionals
        !           661:      to test whether or how this macro is defined, and then controlling
        !           662:      the state of the macro with compiler command options.  *Note
        !           663:      Invocation::.
        !           664: 
        !           665:    Assertions are usually predefined, but can be defined with
        !           666: preprocessor commands or command-line options.
        !           667: 
        !           668: 
        !           669: File: cpp.info,  Node: Assertions,  Next: #error Command,  Prev: Conditionals-Macros,  Up: Conditionals
        !           670: 
        !           671: Assertions
        !           672: ----------
        !           673: 
        !           674:    "Assertions" are a more systematic alternative to macros in writing
        !           675: conditionals to test what sort of computer or system the compiled
        !           676: program will run on.  Assertions are usually predefined, but you can
        !           677: define them with preprocessor commands or command-line options.
        !           678: 
        !           679:    The macros traditionally used to describe the type of target are not
        !           680: classified in any way according to which question they answer; they may
        !           681: indicate a hardware architecture, a particular hardware model, an
        !           682: operating system, a particular version of an operating system, or
        !           683: specific configuration options.  These are jumbled together in a single
        !           684: namespace.  In contrast, each assertion consists of a named question and
        !           685: an answer.  The question is usually called the "predicate".  An
        !           686: assertion looks like this:
        !           687: 
        !           688:      #PREDICATE (ANSWER)
        !           689: 
        !           690: You must use a properly formed identifier for PREDICATE.  The value of
        !           691: ANSWER can be any sequence of words; all characters are significant
        !           692: except for leading and trailing whitespace, and differences in internal
        !           693: whitespace sequences are ignored.  Thus, `x + y' is different from
        !           694: `x+y' but equivalent to `x + y'.  `)' is not allowed in an answer.
        !           695: 
        !           696:    Here is a conditional to test whether the answer ANSWER is asserted
        !           697: for the predicate PREDICATE:
        !           698: 
        !           699:      #if #PREDICATE (ANSWER)
        !           700: 
        !           701: There may be more than one answer asserted for a given predicate.  If
        !           702: you omit the answer, you can test whether *any* answer is asserted for
        !           703: PREDICATE:
        !           704: 
        !           705:      #if #PREDICATE
        !           706: 
        !           707:    Most of the time, the assertions you test will be predefined
        !           708: assertions.  GNU C provides three predefined predicates: `system',
        !           709: `cpu', and `machine'.  `system' is for assertions about the type of
        !           710: software, `cpu' describes the type of computer architecture, and
        !           711: `machine' gives more information about the computer.  For example, on a
        !           712: GNU system, the following assertions would be true:
        !           713: 
        !           714:      #system (gnu)
        !           715:      #system (mach)
        !           716:      #system (mach 3)
        !           717:      #system (mach 3.SUBVERSION)
        !           718:      #system (hurd)
        !           719:      #system (hurd VERSION)
        !           720: 
        !           721: and perhaps others.  The alternatives with more or less version
        !           722: information let you ask more or less detailed questions about the type
        !           723: of system software.
        !           724: 
        !           725:    On a Unix system, you would find `#system (unix)' and perhaps one of:
        !           726: `#system (aix)', `#system (bsd)', `#system (hpux)', `#system (lynx)',
        !           727: `#system (mach)', `#system (posix)', `#system (svr3)', `#system
        !           728: (svr4)', or `#system (xpg4)' with possible version numbers following.
        !           729: 
        !           730:    Other values for `system' are `#system (mvs)' and `#system (vms)'.
        !           731: 
        !           732:    *Portability note:* Many Unix C compilers provide only one answer
        !           733: for the `system' assertion: `#system (unix)', if they support
        !           734: assertions at all.  This is less than useful.
        !           735: 
        !           736:    An assertion with a multi-word answer is completely different from
        !           737: several assertions with individual single-word answers.  For example,
        !           738: the presence of `system (mach 3.0)' does not mean that `system (3.0)'
        !           739: is true.  It also does not directly imply `system (mach)', but in GNU
        !           740: C, that last will normally be asserted as well.
        !           741: 
        !           742:    The current list of possible assertion values for `cpu' is: `#cpu
        !           743: (a29k)', `#cpu (alpha)', `#cpu (arm)', `#cpu (clipper)', `#cpu
        !           744: (convex)', `#cpu (elxsi)', `#cpu (tron)', `#cpu (h8300)', `#cpu
        !           745: (i370)', `#cpu (i386)', `#cpu (i860)', `#cpu (i960)', `#cpu (m68k)',
        !           746: `#cpu (m88k)', `#cpu (mips)', `#cpu (ns32k)', `#cpu (hppa)', `#cpu
        !           747: (pyr)', `#cpu (ibm032)', `#cpu (rs6000)', `#cpu (sh)', `#cpu (sparc)',
        !           748: `#cpu (spur)', `#cpu (tahoe)', `#cpu (vax)', `#cpu (we32000)'.
        !           749: 
        !           750:    You can create assertions within a C program using `#assert', like
        !           751: this:
        !           752: 
        !           753:      #assert PREDICATE (ANSWER)
        !           754: 
        !           755: (Note the absence of a `#' before PREDICATE.)
        !           756: 
        !           757:    Each time you do this, you assert a new true answer for PREDICATE.
        !           758: Asserting one answer does not invalidate previously asserted answers;
        !           759: they all remain true.  The only way to remove an assertion is with
        !           760: `#unassert'.  `#unassert' has the same syntax as `#assert'.  You can
        !           761: also remove all assertions about PREDICATE like this:
        !           762: 
        !           763:      #unassert PREDICATE
        !           764: 
        !           765:    You can also add or cancel assertions using command options when you
        !           766: run `gcc' or `cpp'.  *Note Invocation::.
        !           767: 
        !           768: 
        !           769: File: cpp.info,  Node: #error Command,  Prev: Assertions,  Up: Conditionals
        !           770: 
        !           771: The `#error' and `#warning' Commands
        !           772: ------------------------------------
        !           773: 
        !           774:    The command `#error' causes the preprocessor to report a fatal
        !           775: error.  The rest of the line that follows `#error' is used as the error
        !           776: message.
        !           777: 
        !           778:    You would use `#error' inside of a conditional that detects a
        !           779: combination of parameters which you know the program does not properly
        !           780: support.  For example, if you know that the program will not run
        !           781: properly on a Vax, you might write
        !           782: 
        !           783:      #ifdef vax
        !           784:      #error Won't work on Vaxen.  See comments at get_last_object.
        !           785:      #endif
        !           786: 
        !           787: *Note Nonstandard Predefined::, for why this works.
        !           788: 
        !           789:    If you have several configuration parameters that must be set up by
        !           790: the installation in a consistent way, you can use conditionals to detect
        !           791: an inconsistency and report it with `#error'.  For example,
        !           792: 
        !           793:      #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
        !           794:          || HASH_TABLE_SIZE % 5 == 0
        !           795:      #error HASH_TABLE_SIZE should not be divisible by a small prime
        !           796:      #endif
        !           797: 
        !           798:    The command `#warning' is like the command `#error', but causes the
        !           799: preprocessor to issue a warning and continue preprocessing.  The rest of
        !           800: the line that follows `#warning' is used as the warning message.
        !           801: 
        !           802:    You might use `#warning' in obsolete header files, with a message
        !           803: directing the user to the header file which should be used instead.
        !           804: 
        !           805: 
        !           806: File: cpp.info,  Node: Combining Sources,  Next: Other Commands,  Prev: Conditionals,  Up: Top
        !           807: 
        !           808: Combining Source Files
        !           809: ======================
        !           810: 
        !           811:    One of the jobs of the C preprocessor is to inform the C compiler of
        !           812: where each line of C code came from: which source file and which line
        !           813: number.
        !           814: 
        !           815:    C code can come from multiple source files if you use `#include';
        !           816: both `#include' and the use of conditionals and macros can cause the
        !           817: line number of a line in the preprocessor output to be different from
        !           818: the line's number in the original source file.  You will appreciate the
        !           819: value of making both the C compiler (in error messages) and symbolic
        !           820: debuggers such as GDB use the line numbers in your source file.
        !           821: 
        !           822:    The C preprocessor builds on this feature by offering a command by
        !           823: which you can control the feature explicitly.  This is useful when a
        !           824: file for input to the C preprocessor is the output from another program
        !           825: such as the `bison' parser generator, which operates on another file
        !           826: that is the true source file.  Parts of the output from `bison' are
        !           827: generated from scratch, other parts come from a standard parser file.
        !           828: The rest are copied nearly verbatim from the source file, but their
        !           829: line numbers in the `bison' output are not the same as their original
        !           830: line numbers.  Naturally you would like compiler error messages and
        !           831: symbolic debuggers to know the original source file and line number of
        !           832: each line in the `bison' input.
        !           833: 
        !           834:    `bison' arranges this by writing `#line' commands into the output
        !           835: file.  `#line' is a command that specifies the original line number and
        !           836: source file name for subsequent input in the current preprocessor input
        !           837: file.  `#line' has three variants:
        !           838: 
        !           839: `#line LINENUM'
        !           840:      Here LINENUM is a decimal integer constant.  This specifies that
        !           841:      the line number of the following line of input, in its original
        !           842:      source file, was LINENUM.
        !           843: 
        !           844: `#line LINENUM FILENAME'
        !           845:      Here LINENUM is a decimal integer constant and FILENAME is a
        !           846:      string constant.  This specifies that the following line of input
        !           847:      came originally from source file FILENAME and its line number there
        !           848:      was LINENUM.  Keep in mind that FILENAME is not just a file name;
        !           849:      it is surrounded by doublequote characters so that it looks like a
        !           850:      string constant.
        !           851: 
        !           852: `#line ANYTHING ELSE'
        !           853:      ANYTHING ELSE is checked for macro calls, which are expanded.  The
        !           854:      result should be a decimal integer constant followed optionally by
        !           855:      a string constant, as described above.
        !           856: 
        !           857:    `#line' commands alter the results of the `__FILE__' and `__LINE__'
        !           858: predefined macros from that point on.  *Note Standard Predefined::.
        !           859: 
        !           860:    The output of the preprocessor (which is the input for the rest of
        !           861: the compiler) contains commands that look much like `#line' commands.
        !           862: They start with just `#' instead of `#line', but this is followed by a
        !           863: line number and file name as in `#line'.  *Note Output::.
        !           864: 
        !           865: 
        !           866: File: cpp.info,  Node: Other Commands,  Next: Output,  Prev: Combining Sources,  Up: Top
        !           867: 
        !           868: Miscellaneous Preprocessor Commands
        !           869: ===================================
        !           870: 
        !           871:    This section describes three additional preprocessor commands.  They
        !           872: are not very useful, but are mentioned for completeness.
        !           873: 
        !           874:    The "null command" consists of a `#' followed by a Newline, with
        !           875: only whitespace (including comments) in between.  A null command is
        !           876: understood as a preprocessor command but has no effect on the
        !           877: preprocessor output.  The primary significance of the existence of the
        !           878: null command is that an input line consisting of just a `#' will
        !           879: produce no output, rather than a line of output containing just a `#'.
        !           880: Supposedly some old C programs contain such lines.
        !           881: 
        !           882:    The ANSI standard specifies that the `#pragma' command has an
        !           883: arbitrary, implementation-defined effect.  In the GNU C preprocessor,
        !           884: `#pragma' commands are not used, except for `#pragma once' (*note
        !           885: Once-Only::.).  However, they are left in the preprocessor output, so
        !           886: they are available to the compilation pass.
        !           887: 
        !           888:    The `#ident' command is supported for compatibility with certain
        !           889: other systems.  It is followed by a line of text.  On some systems, the
        !           890: text is copied into a special place in the object file; on most systems,
        !           891: the text is ignored and this command has no effect.  Typically `#ident'
        !           892: is only used in header files supplied with those systems where it is
        !           893: meaningful.
        !           894: 
        !           895: 
        !           896: File: cpp.info,  Node: Output,  Next: Invocation,  Prev: Other Commands,  Up: Top
        !           897: 
        !           898: C Preprocessor Output
        !           899: =====================
        !           900: 
        !           901:    The output from the C preprocessor looks much like the input, except
        !           902: that all preprocessor command lines have been replaced with blank lines
        !           903: and all comments with spaces.  Whitespace within a line is not altered;
        !           904: however, a space is inserted after the expansions of most macro calls.
        !           905: 
        !           906:    Source file name and line number information is conveyed by lines of
        !           907: the form
        !           908: 
        !           909:      # LINENUM FILENAME FLAGS
        !           910: 
        !           911: which are inserted as needed into the middle of the input (but never
        !           912: within a string or character constant).  Such a line means that the
        !           913: following line originated in file FILENAME at line LINENUM.
        !           914: 
        !           915:    After the file name comes zero or more flags, which are `1', `2' or
        !           916: `3'.  If there are multiple flags, spaces separate them.  Here is what
        !           917: the flags mean:
        !           918: 
        !           919: `1'
        !           920:      This indicates the start of a new file.
        !           921: 
        !           922: `2'
        !           923:      This indicates returning to a file (after having included another
        !           924:      file).
        !           925: 
        !           926: `3'
        !           927:      This indicates that the following text comes from a system header
        !           928:      file, so certain warnings should be suppressed.
        !           929: 
        !           930: 
        !           931: File: cpp.info,  Node: Invocation,  Next: Concept Index,  Prev: Output,  Up: Top
        !           932: 
        !           933: Invoking the C Preprocessor
        !           934: ===========================
        !           935: 
        !           936:    Most often when you use the C preprocessor you will not have to
        !           937: invoke it explicitly: the C compiler will do so automatically.
        !           938: However, the preprocessor is sometimes useful individually.
        !           939: 
        !           940:    The C preprocessor expects two file names as arguments, INFILE and
        !           941: OUTFILE.  The preprocessor reads INFILE together with any other files
        !           942: it specifies with `#include'.  All the output generated by the combined
        !           943: input files is written in OUTFILE.
        !           944: 
        !           945:    Either INFILE or OUTFILE may be `-', which as INFILE means to read
        !           946: from standard input and as OUTFILE means to write to standard output.
        !           947: Also, if OUTFILE or both file names are omitted, the standard output
        !           948: and standard input are used for the omitted file names.
        !           949: 
        !           950:    Here is a table of command options accepted by the C preprocessor.
        !           951: These options can also be given when compiling a C program; they are
        !           952: passed along automatically to the preprocessor when it is invoked by the
        !           953: compiler.
        !           954: 
        !           955: `-P'
        !           956:      Inhibit generation of `#'-lines with line-number information in
        !           957:      the output from the preprocessor (*note Output::.).  This might be
        !           958:      useful when running the preprocessor on something that is not C
        !           959:      code and will be sent to a program which might be confused by the
        !           960:      `#'-lines.
        !           961: 
        !           962: `-C'
        !           963:      Do not discard comments: pass them through to the output file.
        !           964:      Comments appearing in arguments of a macro call will be copied to
        !           965:      the output before the expansion of the macro call.
        !           966: 
        !           967: `-traditional'
        !           968:      Try to imitate the behavior of old-fashioned C, as opposed to ANSI
        !           969:      C.
        !           970: 
        !           971:         * Traditional macro expansion pays no attention to singlequote
        !           972:           or doublequote characters; macro argument symbols are
        !           973:           replaced by the argument values even when they appear within
        !           974:           apparent string or character constants.
        !           975: 
        !           976:         * Traditionally, it is permissible for a macro expansion to end
        !           977:           in the middle of a string or character constant.  The
        !           978:           constant continues into the text surrounding the macro call.
        !           979: 
        !           980:         * However, traditionally the end of the line terminates a
        !           981:           string or character constant, with no error.
        !           982: 
        !           983:         * In traditional C, a comment is equivalent to no text at all.
        !           984:           (In ANSI C, a comment counts as whitespace.)
        !           985: 
        !           986:         * Traditional C does not have the concept of a "preprocessing
        !           987:           number".  It considers `1.0e+4' to be three tokens: `1.0e',
        !           988:           `+', and `4'.
        !           989: 
        !           990:         * A macro is not suppressed within its own definition, in
        !           991:           traditional C.  Thus, any macro that is used recursively
        !           992:           inevitably causes an error.
        !           993: 
        !           994:         * The character `#' has no special meaning within a macro
        !           995:           definition in traditional C.
        !           996: 
        !           997:         * In traditional C, the text at the end of a macro expansion
        !           998:           can run together with the text after the macro call, to
        !           999:           produce a single token.  (This is impossible in ANSI C.)
        !          1000: 
        !          1001:         * Traditionally, `\' inside a macro argument suppresses the
        !          1002:           syntactic significance of the following character.
        !          1003: 
        !          1004: `-trigraphs'
        !          1005:      Process ANSI standard trigraph sequences.  These are
        !          1006:      three-character sequences, all starting with `??', that are
        !          1007:      defined by ANSI C to stand for single characters.  For example,
        !          1008:      `??/' stands for `\', so `'??/n'' is a character constant for a
        !          1009:      newline.  Strictly speaking, the GNU C preprocessor does not
        !          1010:      support all programs in ANSI Standard C unless `-trigraphs' is
        !          1011:      used, but if you ever notice the difference it will be with relief.
        !          1012: 
        !          1013:      You don't want to know any more about trigraphs.
        !          1014: 
        !          1015: `-pedantic'
        !          1016:      Issue warnings required by the ANSI C standard in certain cases
        !          1017:      such as when text other than a comment follows `#else' or `#endif'.
        !          1018: 
        !          1019: `-pedantic-errors'
        !          1020:      Like `-pedantic', except that errors are produced rather than
        !          1021:      warnings.
        !          1022: 
        !          1023: `-Wtrigraphs'
        !          1024:      Warn if any trigraphs are encountered (assuming they are enabled).
        !          1025: 
        !          1026: `-Wcomment'
        !          1027:      Warn whenever a comment-start sequence `/*' appears in a comment.
        !          1028: 
        !          1029: `-Wall'
        !          1030:      Requests both `-Wtrigraphs' and `-Wcomment' (but not
        !          1031:      `-Wtraditional').
        !          1032: 
        !          1033: `-Wtraditional'
        !          1034:      Warn about certain constructs that behave differently in
        !          1035:      traditional and ANSI C.
        !          1036: 
        !          1037: `-I DIRECTORY'
        !          1038:      Add the directory DIRECTORY to the end of the list of directories
        !          1039:      to be searched for header files (*note Include Syntax::.).  This
        !          1040:      can be used to override a system header file, substituting your
        !          1041:      own version, since these directories are searched before the system
        !          1042:      header file directories.  If you use more than one `-I' option,
        !          1043:      the directories are scanned in left-to-right order; the standard
        !          1044:      system directories come after.
        !          1045: 
        !          1046: `-I-'
        !          1047:      Any directories specified with `-I' options before the `-I-'
        !          1048:      option are searched only for the case of `#include "FILE"'; they
        !          1049:      are not searched for `#include <FILE>'.
        !          1050: 
        !          1051:      If additional directories are specified with `-I' options after
        !          1052:      the `-I-', these directories are searched for all `#include'
        !          1053:      commands.
        !          1054: 
        !          1055:      In addition, the `-I-' option inhibits the use of the current
        !          1056:      directory as the first search directory for `#include "FILE"'.
        !          1057:      Therefore, the current directory is searched only if it is
        !          1058:      requested explicitly with `-I.'.  Specifying both `-I-' and `-I.'
        !          1059:      allows you to control precisely which directories are searched
        !          1060:      before the current one and which are searched after.
        !          1061: 
        !          1062: `-nostdinc'
        !          1063:      Do not search the standard system directories for header files.
        !          1064:      Only the directories you have specified with `-I' options (and the
        !          1065:      current directory, if appropriate) are searched.
        !          1066: 
        !          1067: `-nostdinc++'
        !          1068:      Do not search for header files in the C++-specific standard
        !          1069:      directories, but do still search the other standard directories.
        !          1070:      (This option is used when building libg++.)
        !          1071: 
        !          1072: `-D NAME'
        !          1073:      Predefine NAME as a macro, with definition `1'.
        !          1074: 
        !          1075: `-D NAME=DEFINITION'
        !          1076:      Predefine NAME as a macro, with definition DEFINITION.  There are
        !          1077:      no restrictions on the contents of DEFINITION, but if you are
        !          1078:      invoking the preprocessor from a shell or shell-like program you
        !          1079:      may need to use the shell's quoting syntax to protect characters
        !          1080:      such as spaces that have a meaning in the shell syntax.  If you
        !          1081:      use more than one `-D' for the same NAME, the rightmost definition
        !          1082:      takes effect.
        !          1083: 
        !          1084: `-U NAME'
        !          1085:      Do not predefine NAME.  If both `-U' and `-D' are specified for
        !          1086:      one name, the `-U' beats the `-D' and the name is not predefined.
        !          1087: 
        !          1088: `-undef'
        !          1089:      Do not predefine any nonstandard macros.
        !          1090: 
        !          1091: `-A PREDICATE(ANSWER)'
        !          1092:      Make an assertion with the predicate PREDICATE and answer ANSWER.
        !          1093:      *Note Assertions::.
        !          1094: 
        !          1095:      You can use `-A-' to disable all predefined assertions; it also
        !          1096:      undefines all predefined macros that identify the type of target
        !          1097:      system.
        !          1098: 
        !          1099: `-dM'
        !          1100:      Instead of outputting the result of preprocessing, output a list of
        !          1101:      `#define' commands for all the macros defined during the execution
        !          1102:      of the preprocessor, including predefined macros.  This gives you
        !          1103:      a way of finding out what is predefined in your version of the
        !          1104:      preprocessor; assuming you have no file `foo.h', the command
        !          1105: 
        !          1106:           touch foo.h; cpp -dM foo.h
        !          1107: 
        !          1108:      will show the values of any predefined macros.
        !          1109: 
        !          1110: `-dD'
        !          1111:      Like `-dM' except in two respects: it does *not* include the
        !          1112:      predefined macros, and it outputs *both* the `#define' commands
        !          1113:      and the result of preprocessing.  Both kinds of output go to the
        !          1114:      standard output file.
        !          1115: 
        !          1116: `-M'
        !          1117:      Instead of outputting the result of preprocessing, output a rule
        !          1118:      suitable for `make' describing the dependencies of the main source
        !          1119:      file.  The preprocessor outputs one `make' rule containing the
        !          1120:      object file name for that source file, a colon, and the names of
        !          1121:      all the included files.  If there are many included files then the
        !          1122:      rule is split into several lines using `\'-newline.
        !          1123: 
        !          1124:      This feature is used in automatic updating of makefiles.
        !          1125: 
        !          1126: `-MM'
        !          1127:      Like `-M' but mention only the files included with `#include
        !          1128:      "FILE"'.  System header files included with `#include <FILE>' are
        !          1129:      omitted.
        !          1130: 
        !          1131: `-MD'
        !          1132:      Like `-M' but the dependency information is written to files with
        !          1133:      names made by replacing `.c' with `.d' at the end of the input
        !          1134:      file names.  This is in addition to compiling the file as
        !          1135:      specified--`-MD' does not inhibit ordinary compilation the way
        !          1136:      `-M' does.
        !          1137: 
        !          1138:      In Mach, you can use the utility `md' to merge the `.d' files into
        !          1139:      a single dependency file suitable for using with the `make'
        !          1140:      command.
        !          1141: 
        !          1142: `-MMD'
        !          1143:      Like `-MD' except mention only user header files, not system
        !          1144:      header files.
        !          1145: 
        !          1146: `-H'
        !          1147:      Print the name of each header file used, in addition to other
        !          1148:      normal activities.
        !          1149: 
        !          1150: `-imacros FILE'
        !          1151:      Process FILE as input, discarding the resulting output, before
        !          1152:      processing the regular input file.  Because the output generated
        !          1153:      from FILE is discarded, the only effect of `-imacros FILE' is to
        !          1154:      make the macros defined in FILE available for use in the main
        !          1155:      input.
        !          1156: 
        !          1157: `-include FILE'
        !          1158:      Process FILE as input, and include all the resulting output,
        !          1159:      before processing the regular input file.
        !          1160: 
        !          1161: `-idirafter DIR'
        !          1162:      Add the directory DIR to the second include path.  The directories
        !          1163:      on the second include path are searched when a header file is not
        !          1164:      found in any of the directories in the main include path (the one
        !          1165:      that `-I' adds to).
        !          1166: 
        !          1167: `-iprefix PREFIX'
        !          1168:      Specify PREFIX as the prefix for subsequent `-iwithprefix' options.
        !          1169: 
        !          1170: `-iwithprefix DIR'
        !          1171:      Add a directory to the second include path.  The directory's name
        !          1172:      is made by concatenating PREFIX and DIR, where PREFIX was
        !          1173:      specified previously with `-iprefix'.
        !          1174: 
        !          1175: `-lang-c'
        !          1176: `-lang-c++'
        !          1177: `-lang-objc'
        !          1178: `-lang-objc++'
        !          1179:      Specify the source language.  `-lang-c++' makes the preprocessor
        !          1180:      handle C++ comment syntax (comments may begin with `//', in which
        !          1181:      case they end at end of line), and includes extra default include
        !          1182:      directories for C++; and `-lang-objc' enables the Objective C
        !          1183:      `#import' command.  `-lang-c' explicitly turns off both of these
        !          1184:      extensions, and `-lang-objc++' enables both.
        !          1185: 
        !          1186:      These options are generated by the compiler driver `gcc', but not
        !          1187:      passed from the `gcc' command line.
        !          1188: 
        !          1189: `-lint'
        !          1190:      Look for commands to the program checker `lint' embedded in
        !          1191:      comments, and emit them preceded by `#pragma lint'.  For example,
        !          1192:      the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'.
        !          1193: 
        !          1194:      This option is available only when you call `cpp' directly; `gcc'
        !          1195:      will not pass it from its command line.
        !          1196: 
        !          1197: `-$'
        !          1198:      Forbid the use of `$' in identifiers.  This is required for ANSI
        !          1199:      conformance.  `gcc' automatically supplies this option to the
        !          1200:      preprocessor if you specify `-ansi', but `gcc' doesn't recognize
        !          1201:      the `-$' option itself--to use it without the other effects of
        !          1202:      `-ansi', you must call the preprocessor directly.
        !          1203: 
        !          1204: 
        !          1205: File: cpp.info,  Node: Concept Index,  Next: Index,  Prev: Invocation,  Up: Top
        !          1206: 
        !          1207: Concept Index
        !          1208: *************
        !          1209: 
        !          1210: * Menu:
        !          1211: 
        !          1212: * assertions:                           Assertions.
        !          1213: * assertions, undoing:                  Assertions.
        !          1214: * cascaded macros:                      Cascaded Macros.
        !          1215: * commands:                             Commands.
        !          1216: * concatenation:                        Concatenation.
        !          1217: * conditionals:                         Conditionals.
        !          1218: * header file:                          Header Files.
        !          1219: * inheritance:                          Inheritance.
        !          1220: * line control:                         Combining Sources.
        !          1221: * macro body uses macro:                Cascaded Macros.
        !          1222: * null command:                         Other Commands.
        !          1223: * options:                              Invocation.
        !          1224: * output format:                        Output.
        !          1225: * overriding a header file:             Inheritance.
        !          1226: * predefined macros:                    Predefined.
        !          1227: * predicates:                           Assertions.
        !          1228: * preprocessor commands:                Commands.
        !          1229: * redefining macros:                    Redefining.
        !          1230: * repeated inclusion:                   Once-Only.
        !          1231: * retracting assertions:                Assertions.
        !          1232: * second include path:                  Invocation.
        !          1233: * self-reference:                       Self-Reference.
        !          1234: * semicolons (after macro calls):       Swallow Semicolon.
        !          1235: * side effects (in macro arguments):    Side Effects.
        !          1236: * stringification:                      Stringification.
        !          1237: * testing predicates:                   Assertions.
        !          1238: * unassert:                             Assertions.
        !          1239: * undefining macros:                    Undefining.
        !          1240: * unsafe macros:                        Side Effects.
        !          1241: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.