Return to cpp.texi CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/cpp.texi, revision 1.1

1.1     ! root        1: \input texinfo
        !             2: @setfilename cpp.info
        !             3: @settitle The C Preprocessor
        !             4: 
        !             5: @ignore
        !             6: @ifinfo
        !             7: @format
        !             8: START-INFO-DIR-ENTRY
        !             9: * Cpp: (cpp).                  The C preprocessor.
        !            10: END-INFO-DIR-ENTRY
        !            11: @end format
        !            12: @end ifinfo
        !            13: @end ignore
        !            14: 
        !            15: @c @smallbook
        !            16: @c @cropmarks
        !            17: @c @finalout
        !            18: @setchapternewpage odd
        !            19: @ifinfo
        !            20: This file documents the GNU C Preprocessor.
        !            21: 
        !            22: Copyright 1987, 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
        !            23: 
        !            24: Permission is granted to make and distribute verbatim copies of
        !            25: this manual provided the copyright notice and this permission notice
        !            26: are preserved on all copies.
        !            27: 
        !            28: @ignore
        !            29: Permission is granted to process this file through Tex and print the
        !            30: results, provided the printed document carries copying permission
        !            31: notice identical to this one except for the removal of this paragraph
        !            32: (this paragraph not being relevant to the printed manual).
        !            33: 
        !            34: @end ignore
        !            35: Permission is granted to copy and distribute modified versions of this
        !            36: manual under the conditions for verbatim copying, provided also that
        !            37: the entire resulting derived work is distributed under the terms of a
        !            38: permission notice identical to this one.
        !            39: 
        !            40: Permission is granted to copy and distribute translations of this manual
        !            41: into another language, under the above conditions for modified versions.
        !            42: @end ifinfo
        !            43: 
        !            44: @titlepage
        !            45: @c @finalout
        !            46: @title The C Preprocessor
        !            47: @subtitle Last revised July 1992
        !            48: @subtitle for GCC version 2
        !            49: @author Richard M. Stallman
        !            50: @page
        !            51: @vskip 2pc
        !            52: This booklet is eventually intended to form the first chapter of a GNU 
        !            53: C Language manual.
        !            54: 
        !            55: @vskip 0pt plus 1filll
        !            56: Copyright @copyright{} 1987, 1989, 1991, 1992 Free Software Foundation, Inc.
        !            57: 
        !            58: Permission is granted to make and distribute verbatim copies of
        !            59: this manual provided the copyright notice and this permission notice
        !            60: are preserved on all copies.
        !            61: 
        !            62: Permission is granted to copy and distribute modified versions of this
        !            63: manual under the conditions for verbatim copying, provided also that
        !            64: the entire resulting derived work is distributed under the terms of a
        !            65: permission notice identical to this one.
        !            66: 
        !            67: Permission is granted to copy and distribute translations of this manual
        !            68: into another language, under the above conditions for modified versions.
        !            69: @end titlepage
        !            70: @page
        !            71: 
        !            72: @node Top, Global Actions,, (DIR)
        !            73: @chapter The C Preprocessor
        !            74: 
        !            75: The C preprocessor is a @dfn{macro processor} that is used automatically by
        !            76: the C compiler to transform your program before actual compilation.  It is
        !            77: called a macro processor because it allows you to define @dfn{macros},
        !            78: which are brief abbreviations for longer constructs.
        !            79: 
        !            80: The C preprocessor provides four separate facilities that you can use as
        !            81: you see fit:
        !            82: 
        !            83: @itemize @bullet
        !            84: @item
        !            85: Inclusion of header files.  These are files of declarations that can be
        !            86: substituted into your program.
        !            87: 
        !            88: @item
        !            89: Macro expansion.  You can define @dfn{macros}, which are abbreviations
        !            90: for arbitrary fragments of C code, and then the C preprocessor will
        !            91: replace the macros with their definitions throughout the program.
        !            92: 
        !            93: @item
        !            94: Conditional compilation.  Using special preprocessor commands, you
        !            95: can include or exclude parts of the program according to various
        !            96: conditions.
        !            97: 
        !            98: @item
        !            99: Line control.  If you use a program to combine or rearrange source files into
        !           100: an intermediate file which is then compiled, you can use line control
        !           101: to inform the compiler of where each source line originally came from.
        !           102: @end itemize
        !           103: 
        !           104: C preprocessors vary in some details.  This manual discusses the GNU C
        !           105: preprocessor, the C Compatible Compiler Preprocessor.  The GNU C
        !           106: preprocessor provides a superset of the features of ANSI Standard C.
        !           107: 
        !           108: ANSI Standard C requires the rejection of many harmless constructs commonly
        !           109: used by today's C programs.  Such incompatibility would be inconvenient for
        !           110: users, so the GNU C preprocessor is configured to accept these constructs
        !           111: by default.  Strictly speaking, to get ANSI Standard C, you must use the
        !           112: options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in
        !           113: practice the consequences of having strict ANSI Standard C make it
        !           114: undesirable to do this.  @xref{Invocation}.
        !           115: 
        !           116: @menu
        !           117: * Global Actions::    Actions made uniformly on all input files.
        !           118: * Commands::          General syntax of preprocessor commands.
        !           119: * Header Files::      How and why to use header files.
        !           120: * Macros::            How and why to use macros.
        !           121: * Conditionals::      How and why to use conditionals.
        !           122: * Combining Sources:: Use of line control when you combine source files.
        !           123: * Other Commands::    Miscellaneous preprocessor commands.
        !           124: * Output::            Format of output from the C preprocessor.
        !           125: * Invocation::        How to invoke the preprocessor; command options.
        !           126: * Concept Index::     Index of concepts and terms.
        !           127: * Index::             Index of commands, predefined macros and options.
        !           128: @end menu
        !           129: 
        !           130: @node Global Actions, Commands, Top, Top
        !           131: @section Transformations Made Globally
        !           132: 
        !           133: Most C preprocessor features are inactive unless you give specific commands
        !           134: to request their use.  (Preprocessor commands are lines starting with
        !           135: @samp{#}; @pxref{Commands}).  But there are three transformations that the
        !           136: preprocessor always makes on all the input it receives, even in the absence
        !           137: of commands.
        !           138: 
        !           139: @itemize @bullet
        !           140: @item
        !           141: All C comments are replaced with single spaces.
        !           142: 
        !           143: @item
        !           144: Backslash-Newline sequences are deleted, no matter where.  This
        !           145: feature allows you to break long lines for cosmetic purposes without
        !           146: changing their meaning.
        !           147: 
        !           148: @item
        !           149: Predefined macro names are replaced with their expansions
        !           150: (@pxref{Predefined}).
        !           151: @end itemize
        !           152: 
        !           153: The first two transformations are done @emph{before} nearly all other parsing
        !           154: and before preprocessor commands are recognized.  Thus, for example, you
        !           155: can split a line cosmetically with Backslash-Newline anywhere (except
        !           156: when trigraphs are in use; see below).
        !           157: 
        !           158: @example
        !           159: /*
        !           160: */ # /*
        !           161: */ defi\
        !           162: ne FO\
        !           163: O 10\
        !           164: 20
        !           165: @end example
        !           166: 
        !           167: @noindent
        !           168: is equivalent into @samp{#define FOO 1020}.  You can split even an escape
        !           169: sequence with Backslash-Newline.  For example, you can split @code{"foo\bar"}
        !           170: between the @samp{\} and the @samp{b} to get
        !           171: 
        !           172: @example
        !           173: "foo\\
        !           174: bar"
        !           175: @end example
        !           176: 
        !           177: @noindent
        !           178: This behavior is unclean: in all other contexts, a Backslash can be
        !           179: inserted in a string constant as an ordinary character by writing a double
        !           180: Backslash, and this creates an exception.  But the ANSI C standard requires
        !           181: it.  (Strict ANSI C does not allow Newlines in string constants, so they
        !           182: do not consider this a problem.)
        !           183: 
        !           184: But there are a few exceptions to all three transformations.
        !           185: 
        !           186: @itemize @bullet
        !           187: @item
        !           188: C comments and predefined macro names are not recognized inside a
        !           189: @samp{#include} command in which the file name is delimited with
        !           190: @samp{<} and @samp{>}.
        !           191: 
        !           192: @item
        !           193: C comments and predefined macro names are never recognized within a
        !           194: character or string constant.  (Strictly speaking, this is the rule,
        !           195: not an exception, but it is worth noting here anyway.)
        !           196: 
        !           197: @item
        !           198: Backslash-Newline may not safely be used within an ANSI ``trigraph''.
        !           199: Trigraphs are converted before Backslash-Newline is deleted.  If you
        !           200: write what looks like a trigraph with a Backslash-Newline inside, the
        !           201: Backslash-Newline is deleted as usual, but it is then too late to
        !           202: recognize the trigraph.
        !           203: 
        !           204: This exception is relevant only if you use the @samp{-trigraphs}
        !           205: option to enable trigraph processing.  @xref{Invocation}.
        !           206: @end itemize
        !           207: 
        !           208: @node Commands, Header Files, Global Actions, Top
        !           209: @section Preprocessor Commands
        !           210: 
        !           211: @cindex preprocessor commands
        !           212: @cindex commands
        !           213: Most preprocessor features are active only if you use preprocessor commands
        !           214: to request their use.
        !           215: 
        !           216: Preprocessor commands are lines in your program that start with @samp{#}.
        !           217: The @samp{#} is followed by an identifier that is the @dfn{command name}.
        !           218: For example, @samp{#define} is the command that defines a macro.
        !           219: Whitespace is also allowed before and after the @samp{#}.
        !           220: 
        !           221: The set of valid command names is fixed.  Programs cannot define new
        !           222: preprocessor commands.
        !           223: 
        !           224: Some command names require arguments; these make up the rest of the command
        !           225: line and must be separated from the command name by whitespace.  For example,
        !           226: @samp{#define} must be followed by a macro name and the intended expansion
        !           227: of the macro.
        !           228: 
        !           229: A preprocessor command cannot be more than one line in normal circumstances.
        !           230: It may be split cosmetically with Backslash-Newline, but that has no effect
        !           231: on its meaning.  Comments containing Newlines can also divide the command into
        !           232: multiple lines, but the comments are changed to Spaces before the command
        !           233: is interpreted.  The only way a significant Newline can occur in a preprocessor
        !           234: command is within a string constant or character constant.  Note that
        !           235: most C compilers that might be applied to the output from the preprocessor
        !           236: do not accept string or character constants containing Newlines.
        !           237: 
        !           238: The @samp{#} and the command name cannot come from a macro expansion.  For
        !           239: example, if @samp{foo} is defined as a macro expanding to @samp{define},
        !           240: that does not make @samp{#foo} a valid preprocessor command.
        !           241: 
        !           242: @node Header Files, Macros, Commands, Top
        !           243: @section Header Files
        !           244: 
        !           245: @cindex header file
        !           246: A header file is a file containing C declarations and macro definitions
        !           247: (@pxref{Macros}) to be shared between several source files.  You request
        !           248: the use of a header file in your program with the C preprocessor command
        !           249: @samp{#include}.
        !           250: 
        !           251: @menu
        !           252: * Header Uses::         What header files are used for.
        !           253: * Include Syntax::      How to write @samp{#include} commands.
        !           254: * Include Operation::   What @samp{#include} does.
        !           255: * Once-Only::          Preventing multiple inclusion of one header file.
        !           256: * Inheritance::         Including one header file in another header file.
        !           257: @end menu
        !           258: 
        !           259: @node Header Uses, Include Syntax, Header Files, Header Files
        !           260: @subsection Uses of Header Files
        !           261: 
        !           262: Header files serve two kinds of purposes.
        !           263: 
        !           264: @itemize @bullet
        !           265: @item
        !           266: @findex system header files
        !           267: System header files declare the interfaces to parts of the operating
        !           268: system.  You include them in your program to supply the definitions and
        !           269: declarations you need to invoke system calls and libraries.
        !           270: 
        !           271: @item
        !           272: Your own header files contain declarations for interfaces between the
        !           273: source files of your program.  Each time you have a group of related
        !           274: declarations and macro definitions all or most of which are needed in
        !           275: several different source files, it is a good idea to create a header
        !           276: file for them.
        !           277: @end itemize
        !           278: 
        !           279: Including a header file produces the same results in C compilation as
        !           280: copying the header file into each source file that needs it.  But such
        !           281: copying would be time-consuming and error-prone.  With a header file, the
        !           282: related declarations appear in only one place.  If they need to be changed,
        !           283: they can be changed in one place, and programs that include the header file
        !           284: will automatically use the new version when next recompiled.  The header
        !           285: file eliminates the labor of finding and changing all the copies as well as
        !           286: the risk that a failure to find one copy will result in inconsistencies
        !           287: within a program.
        !           288: 
        !           289: The usual convention is to give header files names that end with @file{.h}.
        !           290: 
        !           291: @node Include Syntax, Include Operation, Header Uses, Header Files
        !           292: @subsection The @samp{#include} Command
        !           293: 
        !           294: @findex #include
        !           295: Both user and system header files are included using the preprocessor
        !           296: command @samp{#include}.  It has three variants:
        !           297: 
        !           298: @table @code
        !           299: @item #include <@var{file}>
        !           300: This variant is used for system header files.  It searches for a file
        !           301: named @var{file} in a list of directories specified by you, then in a
        !           302: standard list of system directories.  You specify directories to
        !           303: search for header files with the command option @samp{-I}
        !           304: (@pxref{Invocation}).  The option @samp{-nostdinc} inhibits searching
        !           305: the standard system directories; in this case only the directories
        !           306: you specify are searched.
        !           307: 
        !           308: The parsing of this form of @samp{#include} is slightly special
        !           309: because comments are not recognized within the @samp{<@dots{}>}.
        !           310: Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment
        !           311: and the command specifies inclusion of a system header file named
        !           312: @file{x/*y}.  Of course, a header file with such a name is unlikely to
        !           313: exist on Unix, where shell wildcard features would make it hard to
        !           314: manipulate.@refill
        !           315: 
        !           316: The argument @var{file} may not contain a @samp{>} character.  It may,
        !           317: however, contain a @samp{<} character.
        !           318: 
        !           319: @item #include "@var{file}"
        !           320: This variant is used for header files of your own program.  It
        !           321: searches for a file named @var{file} first in the current directory,
        !           322: then in the same directories used for system header files.  The
        !           323: current directory is the directory of the current input file.  It is
        !           324: tried first because it is presumed to be the location of the files
        !           325: that the current input file refers to.  (If the @samp{-I-} option is
        !           326: used, the special treatment of the current directory is inhibited.)
        !           327: 
        !           328: The argument @var{file} may not contain @samp{"} characters.  If
        !           329: backslashes occur within @var{file}, they are considered ordinary text
        !           330: characters, not escape characters.  None of the character escape
        !           331: sequences appropriate to string constants in C are processed.  Thus,
        !           332: @samp{#include "x\n\\y"} specifies a filename containing three
        !           333: backslashes.  It is not clear why this behavior is ever useful, but
        !           334: the ANSI standard specifies it.
        !           335: 
        !           336: @item #include @var{anything else}
        !           337: This variant is called a @dfn{computed #include}.  Any @samp{#include}
        !           338: command whose argument does not fit the above two forms is a computed
        !           339: include.  The text @var{anything else} is checked for macro calls,
        !           340: which are expanded (@pxref{Macros}).  When this is done, the result
        !           341: must fit one of the above two variants---in particular, the expanded
        !           342: text must in the end be surrounded by either quotes or angle braces.
        !           343: 
        !           344: This feature allows you to define a macro which controls the file name
        !           345: to be used at a later point in the program.  One application of this
        !           346: is to allow a site-configuration file for your program to specify the
        !           347: names of the system include files to be used.  This can help in
        !           348: porting the program to various operating systems in which the
        !           349: necessary system header files are found in different places.
        !           350: @end table
        !           351: 
        !           352: @node Include Operation, Once-Only, Include Syntax, Header Files
        !           353: @subsection How @samp{#include} Works
        !           354: 
        !           355: The @samp{#include} command works by directing the C preprocessor to scan
        !           356: the specified file as input before continuing with the rest of the current
        !           357: file.  The output from the preprocessor contains the output already
        !           358: generated, followed by the output resulting from the included file,
        !           359: followed by the output that comes from the text after the @samp{#include}
        !           360: command.  For example, given two files as follows:
        !           361: 
        !           362: @example
        !           363: /* File program.c */
        !           364: int x;
        !           365: #include "header.h"
        !           366: 
        !           367: main ()
        !           368: @{
        !           369:   printf (test ());
        !           370: @}
        !           371: 
        !           372: 
        !           373: /* File header.h */
        !           374: char *test ();
        !           375: @end example
        !           376: 
        !           377: @noindent
        !           378: the output generated by the C preprocessor for @file{program.c} as input
        !           379: would be
        !           380: 
        !           381: @example
        !           382: int x;
        !           383: char *test ();
        !           384: 
        !           385: main ()
        !           386: @{
        !           387:   printf (test ());
        !           388: @}
        !           389: @end example
        !           390: 
        !           391: Included files are not limited to declarations and macro definitions; those
        !           392: are merely the typical uses.  Any fragment of a C program can be included
        !           393: from another file.  The include file could even contain the beginning of a
        !           394: statement that is concluded in the containing file, or the end of a
        !           395: statement that was started in the including file.  However, a comment or a
        !           396: string or character constant may not start in the included file and finish
        !           397: in the including file.  An unterminated comment, string constant or
        !           398: character constant in an included file is considered to end (with an error
        !           399: message) at the end of the file.
        !           400: 
        !           401: The line following the @samp{#include} command is always treated as a
        !           402: separate line by the C preprocessor even if the included file lacks a final
        !           403: newline.
        !           404: 
        !           405: @node Once-Only, Inheritance, Include Operation, Header Files
        !           406: @subsection Once-Only Include Files
        !           407: @cindex repeated inclusion
        !           408: 
        !           409: Very often, one header file includes another.  It can easily result that a
        !           410: certain header file is included more than once.  This may lead to errors,
        !           411: if the header file defines structure types or typedefs, and is certainly
        !           412: wasteful.  Therefore, we often wish to prevent multiple inclusion of a
        !           413: header file.
        !           414: 
        !           415: The standard way to do this is to enclose the entire real contents of the
        !           416: file in a conditional, like this:
        !           417: 
        !           418: @example
        !           419: #ifndef __FILE_FOO_SEEN__
        !           420: #define __FILE_FOO_SEEN__
        !           421: 
        !           422: @var{the entire file}
        !           423: 
        !           424: #endif /* __FILE_FOO_SEEN__ */
        !           425: @end example
        !           426: 
        !           427: The macro @code{__FILE_FOO_SEEN__} indicates that the file has been
        !           428: included once already; its name should begin with @samp{__} to avoid
        !           429: conflicts with user programs, and it should contain the name of the file
        !           430: and some additional text, to avoid conflicts with other header files.
        !           431: 
        !           432: The GNU C preprocessor is programmed to notice when a header file uses
        !           433: this particular construct and handle it efficiently.  If a header file
        !           434: is contained entirely in a @samp{#ifndef} conditional, then it records
        !           435: that fact.  If a subsequent @samp{#include} specifies the same file,
        !           436: and the macro in the @samp{#ifndef} is already defined, then the file
        !           437: is entirely skipped, without even reading it.
        !           438: 
        !           439: @findex #pragma once
        !           440: There is also an explicit command to tell the preprocessor that it need
        !           441: not include a file more than once.  This is called @samp{#pragma once},
        !           442: and was used @emph{in addition to} the @samp{#ifndef} conditional around
        !           443: the contents of the header file.  @samp{#pragma once} is now obsolete
        !           444: and should not be used at all.
        !           445: 
        !           446: In the Objective C language, there is a variant of @samp{#include}
        !           447: called @samp{#import} which includes a file, but does so at most once.
        !           448: If you use @samp{#import} @emph{instead of} @samp{#include}, then you
        !           449: don't need the conditionals inside the header file to prevent multiple
        !           450: execution of the contents.
        !           451: 
        !           452: @samp{#import} is obsolete because it is not a well-designed feature.
        !           453: It requires the users of a header file---the applications
        !           454: programmers---to know that a certain header file should only be included
        !           455: once.  It is much better for the header file's implementor to write the
        !           456: file so that users don't need to know this.  Using @samp{#ifndef}
        !           457: accomplishes this goal.
        !           458: 
        !           459: @node Inheritance,, Once-Only, Header Files
        !           460: @section Inheritance and Header Files
        !           461: @cindex inheritance
        !           462: @cindex overriding a header file
        !           463: 
        !           464: @dfn{Inheritance} is what happens when one object or file derives some
        !           465: of its contents by virtual copying from another object or file.  In
        !           466: the case of C header files, inheritance means that one header file 
        !           467: includes another header file and then replaces or adds something.
        !           468: 
        !           469: If the inheriting header file and the base header file have different
        !           470: names, then inheritance is straightforward: simply write @samp{#include
        !           471: "@var{base}"} in the inheriting file.
        !           472: 
        !           473: Sometimes it is necessary to give the inheriting file the same name as
        !           474: the base file.  This is less straightforward.
        !           475: 
        !           476: For example, suppose an application program uses the system header file
        !           477: @file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h}
        !           478: on a particular system doesn't do what the application program expects.
        !           479: It might be convenient to define a ``local'' version, perhaps under the
        !           480: name @file{/usr/local/include/sys/signal.h}, to override or add to the
        !           481: one supplied by the system.
        !           482: 
        !           483: You can do this by using the option @samp{-I.} for compilation, and
        !           484: writing a file @file{sys/signal.h} that does what the application
        !           485: program expects.  But making this file include the standard
        !           486: @file{sys/signal.h} is not so easy---writing @samp{#include
        !           487: <sys/signal.h>} in that file doesn't work, because it includes your own
        !           488: version of the file, not the standard system version.  Used in that file
        !           489: itself, this leads to an infinite recursion and a fatal error in
        !           490: compilation.
        !           491: 
        !           492: @samp{#include </usr/include/sys/signal.h>} would find the proper file,
        !           493: but that is not clean, since it makes an assumption about where the
        !           494: system header file is found.  This is bad for maintenance, since it
        !           495: means that any change in where the system's header files are kept
        !           496: requires a change somewhere else.
        !           497: 
        !           498: @findex #include_next
        !           499: The clean way to solve this problem is to use 
        !           500: @samp{#include_next}, which means, ``Include the @emph{next} file with
        !           501: this name.''  This command works like @samp{#include} except in
        !           502: searching for the specified file: it starts searching the list of header
        !           503: file directories @emph{after} the directory in which the current file
        !           504: was found.
        !           505: 
        !           506: Suppose you specify @samp{-I /usr/local/include}, and the list of
        !           507: directories to search also includes @file{/usr/include}; and suppose that
        !           508: both directories contain a file named @file{sys/signal.h}.  Ordinary
        !           509: @samp{#include <sys/signal.h>} finds the file under
        !           510: @file{/usr/local/include}.  If that file contains @samp{#include_next
        !           511: <sys/signal.h>}, it starts searching after that directory, and finds the
        !           512: file in @file{/usr/include}.
        !           513: 
        !           514: @node Macros, Conditionals, Header Files, Top
        !           515: @section Macros
        !           516: 
        !           517: A macro is a sort of abbreviation which you can define once and then
        !           518: use later.  There are many complicated features associated with macros
        !           519: in the C preprocessor.
        !           520: 
        !           521: @menu
        !           522: * Simple Macros::    Macros that always expand the same way.
        !           523: * Argument Macros::  Macros that accept arguments that are substituted
        !           524:                        into the macro expansion.
        !           525: * Predefined::       Predefined macros that are always available.
        !           526: * Stringification::  Macro arguments converted into string constants.
        !           527: * Concatenation::    Building tokens from parts taken from macro arguments.
        !           528: * Undefining::       Cancelling a macro's definition.
        !           529: * Redefining::       Changing a macro's definition.
        !           530: * Macro Pitfalls::   Macros can confuse the unwary.  Here we explain
        !           531:                        several common problems and strange features.
        !           532: @end menu
        !           533: 
        !           534: @node Simple Macros, Argument Macros, Macros, Macros
        !           535: @subsection Simple Macros
        !           536: 
        !           537: A @dfn{simple macro} is a kind of abbreviation.  It is a name which
        !           538: stands for a fragment of code.  Some people refer to these as
        !           539: @dfn{manifest constants}.
        !           540: 
        !           541: Before you can use a macro, you must @dfn{define} it explicitly with the
        !           542: @samp{#define} command.  @samp{#define} is followed by the name of the
        !           543: macro and then the code it should be an abbreviation for.  For example,
        !           544: 
        !           545: @example
        !           546: #define BUFFER_SIZE 1020
        !           547: @end example
        !           548: 
        !           549: @noindent
        !           550: defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text
        !           551: @samp{1020}.  Therefore, if somewhere after this @samp{#define} command
        !           552: there comes a C statement of the form
        !           553: 
        !           554: @example
        !           555: foo = (char *) xmalloc (BUFFER_SIZE);
        !           556: @end example
        !           557: 
        !           558: @noindent
        !           559: then the C preprocessor will recognize and @dfn{expand} the macro
        !           560: @samp{BUFFER_SIZE}, resulting in
        !           561: 
        !           562: @example
        !           563: foo = (char *) xmalloc (1020);
        !           564: @end example
        !           565: 
        !           566: @noindent
        !           567: the definition must be a single line; however, it may not end in the
        !           568: middle of a multi-line string constant or character constant.
        !           569: 
        !           570: The use of all upper case for macro names is a standard convention.
        !           571: Programs are easier to read when it is possible to tell at a glance which
        !           572: names are macros.
        !           573: 
        !           574: Normally, a macro definition must be a single line, like all C preprocessor
        !           575: commands.  (You can split a long macro definition cosmetically with
        !           576: Backslash-Newline.)  There is one exception: Newlines can be included in
        !           577: the macro definition if within a string or character constant.  By the same
        !           578: token, it is not possible for a macro definition to contain an unbalanced
        !           579: quote character; the definition automatically extends to include the
        !           580: matching quote character that ends the string or character constant.
        !           581: Comments within a macro definition may contain Newlines, which make no
        !           582: difference since the comments are entirely replaced with Spaces regardless
        !           583: of their contents.
        !           584: 
        !           585: Aside from the above, there is no restriction on what can go in a macro
        !           586: body.  Parentheses need not balance.  The body need not resemble valid C
        !           587: code.  (Of course, you might get error messages from the C compiler when
        !           588: you use the macro.)
        !           589: 
        !           590: The C preprocessor scans your program sequentially, so macro definitions
        !           591: take effect at the place you write them.  Therefore, the following input to
        !           592: the C preprocessor
        !           593: 
        !           594: @example
        !           595: foo = X;
        !           596: #define X 4
        !           597: bar = X;
        !           598: @end example
        !           599: 
        !           600: @noindent
        !           601: produces as output
        !           602: 
        !           603: @example
        !           604: foo = X;
        !           605: 
        !           606: bar = 4;
        !           607: @end example
        !           608: 
        !           609: After the preprocessor expands a macro name, the macro's definition body is
        !           610: appended to the front of the remaining input, and the check for macro calls
        !           611: continues.  Therefore, the macro body can contain calls to other macros.
        !           612: For example, after
        !           613: 
        !           614: @example
        !           615: #define BUFSIZE 1020
        !           616: #define TABLESIZE BUFSIZE
        !           617: @end example
        !           618: 
        !           619: @noindent
        !           620: the name @samp{TABLESIZE} when used in the program would go through two
        !           621: stages of expansion, resulting ultimately in @samp{1020}.
        !           622: 
        !           623: This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
        !           624: The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
        !           625: specify---in this case, @samp{BUFSIZE}---and does not check to see whether
        !           626: it too is the name of a macro.  It's only when you @emph{use} @samp{TABLESIZE}
        !           627: that the result of its expansion is checked for more macro names.
        !           628: @xref{Cascaded Macros}.
        !           629: 
        !           630: @node Argument Macros, Predefined, Simple Macros, Macros
        !           631: @subsection Macros with Arguments
        !           632: 
        !           633: A simple macro always stands for exactly the same text, each time it is
        !           634: used.  Macros can be more flexible when they accept @dfn{arguments}.
        !           635: Arguments are fragments of code that you supply each time the macro is
        !           636: used.  These fragments are included in the expansion of the macro according
        !           637: to the directions in the macro definition.
        !           638: 
        !           639: To define a macro that uses arguments, you write a @samp{#define} command
        !           640: with a list of @dfn{argument names} in parentheses after the name of the
        !           641: macro.  The argument names may be any valid C identifiers, separated by
        !           642: commas and optionally whitespace.  The open-parenthesis must follow the
        !           643: macro name immediately, with no space in between.
        !           644: 
        !           645: For example, here is a macro that computes the minimum of two numeric
        !           646: values, as it is defined in many C programs:
        !           647: 
        !           648: @example
        !           649: #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
        !           650: @end example
        !           651: 
        !           652: @noindent
        !           653: (This is not the best way to define a ``minimum'' macro in GNU C.
        !           654: @xref{Side Effects}, for more information.)
        !           655: 
        !           656: To use a macro that expects arguments, you write the name of the macro
        !           657: followed by a list of @dfn{actual arguments} in parentheses, separated by
        !           658: commas.  The number of actual arguments you give must match the number of
        !           659: arguments the macro expects.   Examples of use of the macro @samp{min}
        !           660: include @samp{min (1, 2)} and @samp{min (x + 28, *p)}.
        !           661: 
        !           662: The expansion text of the macro depends on the arguments you use.
        !           663: Each of the argument names of the macro is replaced, throughout the
        !           664: macro definition, with the corresponding actual argument.  Using the
        !           665: same macro @samp{min} defined above, @samp{min (1, 2)} expands into
        !           666: 
        !           667: @example
        !           668: ((1) < (2) ? (1) : (2))
        !           669: @end example
        !           670: 
        !           671: @noindent
        !           672: where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}.
        !           673: 
        !           674: Likewise, @samp{min (x + 28, *p)} expands into
        !           675: 
        !           676: @example
        !           677: ((x + 28) < (*p) ? (x + 28) : (*p))
        !           678: @end example
        !           679: 
        !           680: Parentheses in the actual arguments must balance; a comma within
        !           681: parentheses does not end an argument.  However, there is no requirement
        !           682: for brackets or braces to balance, and they do not prevent a comma from
        !           683: separating arguments.  Thus,
        !           684: 
        !           685: @example
        !           686: macro (array[x = y, x + 1])
        !           687: @end example
        !           688: 
        !           689: @noindent
        !           690: passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x +
        !           691: 1]}.  If you want to supply @samp{array[x = y, x + 1]} as an argument,
        !           692: you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C
        !           693: code.
        !           694: 
        !           695: After the actual arguments are substituted into the macro body, the entire
        !           696: result is appended to the front of the remaining input, and the check for
        !           697: macro calls continues.  Therefore, the actual arguments can contain calls
        !           698: to other macros, either with or without arguments, or even to the same
        !           699: macro.  The macro body can also contain calls to other macros.  For
        !           700: example, @samp{min (min (a, b), c)} expands into this text:
        !           701: 
        !           702: @example
        !           703: ((((a) < (b) ? (a) : (b))) < (c)
        !           704:  ? (((a) < (b) ? (a) : (b)))
        !           705:  : (c))
        !           706: @end example
        !           707: 
        !           708: @noindent
        !           709: (Line breaks shown here for clarity would not actually be generated.)
        !           710: 
        !           711: If a macro @code{foo} takes one argument, and you want to supply an
        !           712: empty argument, you must write at least some whitespace between the
        !           713: parentheses, like this: @samp{foo ( )}.  Just @samp{foo ()} is providing
        !           714: no arguments, which is an error if @code{foo} expects an argument.  But
        !           715: @samp{foo0 ()} is the correct way to call a macro defined to take zero
        !           716: arguments, like this:
        !           717: 
        !           718: @example
        !           719: #define foo0() @dots{}
        !           720: @end example
        !           721: 
        !           722: If you use the macro name followed by something other than an
        !           723: open-parenthesis (after ignoring any spaces, tabs and comments that
        !           724: follow), it is not a call to the macro, and the preprocessor does not
        !           725: change what you have written.  Therefore, it is possible for the same name
        !           726: to be a variable or function in your program as well as a macro, and you
        !           727: can choose in each instance whether to refer to the macro (if an actual
        !           728: argument list follows) or the variable or function (if an argument list
        !           729: does not follow).
        !           730: 
        !           731: Such dual use of one name could be confusing and should be avoided
        !           732: except when the two meanings are effectively synonymous: that is, when the
        !           733: name is both a macro and a function and the two have similar effects.  You
        !           734: can think of the name simply as a function; use of the name for purposes
        !           735: other than calling it (such as, to take the address) will refer to the
        !           736: function, while calls will expand the macro and generate better but
        !           737: equivalent code.  For example, you can use a function named @samp{min} in
        !           738: the same source file that defines the macro.  If you write @samp{&min} with
        !           739: no argument list, you refer to the function.  If you write @samp{min (x,
        !           740: bb)}, with an argument list, the macro is expanded.  If you write
        !           741: @samp{(min) (a, bb)}, where the name @samp{min} is not followed by an
        !           742: open-parenthesis, the macro is not expanded, so you wind up with a call to
        !           743: the function @samp{min}.
        !           744: 
        !           745: You may not define the same name as both a simple macro and a macro with
        !           746: arguments.
        !           747: 
        !           748: In the definition of a macro with arguments, the list of argument names
        !           749: must follow the macro name immediately with no space in between.  If there
        !           750: is a space after the macro name, the macro is defined as taking no
        !           751: arguments, and all the rest of the line is taken to be the expansion.  The
        !           752: reason for this is that it is often useful to define a macro that takes no
        !           753: arguments and whose definition begins with an identifier in parentheses.
        !           754: This rule about spaces makes it possible for you to do either this:
        !           755: 
        !           756: @example
        !           757: #define FOO(x) - 1 / (x)
        !           758: @end example
        !           759: 
        !           760: @noindent
        !           761: (which defines @samp{FOO} to take an argument and expand into minus the
        !           762: reciprocal of that argument) or this:
        !           763: 
        !           764: @example
        !           765: #define BAR (x) - 1 / (x)
        !           766: @end example
        !           767: 
        !           768: @noindent
        !           769: (which defines @samp{BAR} to take no argument and always expand into
        !           770: @samp{(x) - 1 / (x)}).
        !           771: 
        !           772: Note that the @emph{uses} of a macro with arguments can have spaces before
        !           773: the left parenthesis; it's the @emph{definition} where it matters whether
        !           774: there is a space.
        !           775: 
        !           776: @node Predefined, Stringification, Argument Macros, Macros
        !           777: @subsection Predefined Macros
        !           778: 
        !           779: @cindex predefined macros
        !           780: Several simple macros are predefined.  You can use them without giving
        !           781: definitions for them.  They fall into two classes: standard macros and
        !           782: system-specific macros.
        !           783: 
        !           784: @menu
        !           785: * Standard Predefined::     Standard predefined macros.
        !           786: * Nonstandard Predefined::  Nonstandard predefined macros.
        !           787: @end menu
        !           788: 
        !           789: @node Standard Predefined, Nonstandard Predefined, Predefined, Predefined
        !           790: @subsubsection Standard Predefined Macros
        !           791: 
        !           792: The standard predefined macros are available with the same meanings
        !           793: regardless of the machine or operating system on which you are using GNU C.
        !           794: Their names all start and end with double underscores.  Those preceding
        !           795: @code{__GNUC__} in this table are standardized by ANSI C; the rest are
        !           796: GNU C extensions.
        !           797: 
        !           798: @table @code
        !           799: @item __FILE__
        !           800: @findex __FILE__
        !           801: This macro expands to the name of the current input file, in the form of
        !           802: a C string constant.  The precise name returned is the one that was
        !           803: specified in @samp{#include} or as the input file name argument.
        !           804: 
        !           805: @item __LINE__
        !           806: @findex __LINE__
        !           807: This macro expands to the current input line number, in the form of a
        !           808: decimal integer constant.  While we call it a predefined macro, it's
        !           809: a pretty strange macro, since its ``definition'' changes with each
        !           810: new line of source code.
        !           811: 
        !           812: This and @samp{__FILE__} are useful in generating an error message to
        !           813: report an inconsistency detected by the program; the message can state
        !           814: the source line at which the inconsistency was detected.  For example,
        !           815: 
        !           816: @smallexample
        !           817: fprintf (stderr, "Internal error: "
        !           818:                 "negative string length "
        !           819:                  "%d at %s, line %d.",
        !           820:          length, __FILE__, __LINE__);
        !           821: @end smallexample
        !           822: 
        !           823: A @samp{#include} command changes the expansions of @samp{__FILE__}
        !           824: and @samp{__LINE__} to correspond to the included file.  At the end of
        !           825: that file, when processing resumes on the input file that contained
        !           826: the @samp{#include} command, the expansions of @samp{__FILE__} and
        !           827: @samp{__LINE__} revert to the values they had before the
        !           828: @samp{#include} (but @samp{__LINE__} is then incremented by one as
        !           829: processing moves to the line after the @samp{#include}).
        !           830: 
        !           831: The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered
        !           832: if a @samp{#line} command is used.  @xref{Combining Sources}.
        !           833: 
        !           834: @item __INCLUDE_LEVEL__
        !           835: @findex __INCLUDE_LEVEL_
        !           836: This macro expands to a decimal integer constant that represents the
        !           837: depth of nesting in include files.  The value of this macro is
        !           838: incremented on every @samp{#include} command and decremented at every
        !           839: end of file.
        !           840: 
        !           841: @item __DATE__
        !           842: @findex __DATE__
        !           843: This macro expands to a string constant that describes the date on
        !           844: which the preprocessor is being run.  The string constant contains
        !           845: eleven characters and looks like @samp{"Jan 29 1987"} or @w{@samp{"Apr
        !           846: 1 1905"}}.
        !           847: 
        !           848: @item __TIME__
        !           849: @findex __TIME__
        !           850: This macro expands to a string constant that describes the time at
        !           851: which the preprocessor is being run.  The string constant contains
        !           852: eight characters and looks like @samp{"23:59:01"}.
        !           853: 
        !           854: @item __STDC__
        !           855: @findex __STDC__
        !           856: This macro expands to the constant 1, to signify that this is ANSI
        !           857: Standard C.  (Whether that is actually true depends on what C compiler
        !           858: will operate on the output from the preprocessor.)
        !           859: 
        !           860: @item __GNUC__
        !           861: This macro is defined if and only if this is GNU C.  This macro is
        !           862: defined only when the entire GNU C compiler is in use; if you invoke
        !           863: the preprocessor directly, @samp{__GNUC__} is undefined.
        !           864: 
        !           865: @item __GNUG__
        !           866: The GNU C compiler defines this when the compilation language is
        !           867: C++; use @samp{__GNUG__} to distinguish between GNU C and GNU
        !           868: C++.
        !           869: 
        !           870: @item __cplusplus 
        !           871: The draft ANSI standard for C++ used to require predefining this
        !           872: variable.  Though it is no longer required, GNU C++ continues to define
        !           873: it, as do other popular C++ compilers.  You can use @samp{__cplusplus}
        !           874: to test whether a header is compiled by a C compiler or a C++ compiler.
        !           875: 
        !           876: @item __STRICT_ANSI__
        !           877: This macro is defined if and only if the @samp{-ansi} switch was
        !           878: specified when GNU C was invoked.  Its definition is the null string.
        !           879: This macro exists primarily to direct certain GNU header files not to
        !           880: define certain traditional Unix constructs which are incompatible with
        !           881: ANSI C.
        !           882: 
        !           883: @item __BASE_FILE__
        !           884: @findex __BASE_FILE__
        !           885: This macro expands to the name of the main input file, in the form
        !           886: of a C string constant.  This is the source file that was specified
        !           887: as an argument when the C compiler was invoked.
        !           888: 
        !           889: @item __VERSION__
        !           890: This macro expands to a string which describes the version number of
        !           891: GNU C.  The string is normally a sequence of decimal numbers separated
        !           892: by periods, such as @samp{"1.18"}.  The only reasonable use of this
        !           893: macro is to incorporate it into a string constant.
        !           894: 
        !           895: @item __OPTIMIZE__
        !           896: This macro is defined in optimizing compilations.  It causes certain
        !           897: GNU header files to define alternative macro definitions for some
        !           898: system library functions.  It is unwise to refer to or test the
        !           899: definition of this macro unless you make very sure that programs will
        !           900: execute with the same effect regardless.
        !           901: 
        !           902: @item __CHAR_UNSIGNED__
        !           903: This macro is defined if and only if the data type @code{char} is
        !           904: unsigned on the target machine.  It exists to cause the standard
        !           905: header file @file{limit.h} to work correctly.  It is bad practice
        !           906: to refer to this macro yourself; instead, refer to the standard
        !           907: macros defined in @file{limit.h}.  The preprocessor uses
        !           908: this macro to determine whether or not to sign-extend large character
        !           909: constants written in octal; see @ref{#if Command,,The @samp{#if} Command}.
        !           910: @end table
        !           911: 
        !           912: @node Nonstandard Predefined,, Standard Predefined, Predefined
        !           913: @subsubsection Nonstandard Predefined Macros
        !           914: 
        !           915: The C preprocessor normally has several predefined macros that vary between
        !           916: machines because their purpose is to indicate what type of system and
        !           917: machine is in use.  This manual, being for all systems and machines, cannot
        !           918: tell you exactly what their names are; instead, we offer a list of some
        !           919: typical ones.  You can use @samp{cpp -dM} to see the values of
        !           920: predefined macros; @pxref{Invocation}.
        !           921: 
        !           922: Some nonstandard predefined macros describe the operating system in use,
        !           923: with more or less specificity.  For example,
        !           924: 
        !           925: @table @code
        !           926: @item unix
        !           927: @findex unix
        !           928: @samp{unix} is normally predefined on all Unix systems.
        !           929: 
        !           930: @item BSD
        !           931: @findex BSD
        !           932: @samp{BSD} is predefined on recent versions of Berkeley Unix
        !           933: (perhaps only in version 4.3).
        !           934: @end table
        !           935: 
        !           936: Other nonstandard predefined macros describe the kind of CPU, with more or
        !           937: less specificity.  For example,
        !           938: 
        !           939: @table @code
        !           940: @item vax
        !           941: @findex vax
        !           942: @samp{vax} is predefined on Vax computers.
        !           943: 
        !           944: @item mc68000
        !           945: @findex mc68000
        !           946: @samp{mc68000} is predefined on most computers whose CPU is a Motorola
        !           947: 68000, 68010 or 68020.
        !           948: 
        !           949: @item m68k
        !           950: @findex m68k
        !           951: @samp{m68k} is also predefined on most computers whose CPU is a 68000,
        !           952: 68010 or 68020; however, some makers use @samp{mc68000} and some use
        !           953: @samp{m68k}.  Some predefine both names.  What happens in GNU C
        !           954: depends on the system you are using it on.
        !           955: 
        !           956: @item M68020
        !           957: @findex M68020
        !           958: @samp{M68020} has been observed to be predefined on some systems that
        !           959: use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which
        !           960: are less specific.
        !           961: 
        !           962: @item _AM29K
        !           963: @findex _AM29K
        !           964: @itemx _AM29000
        !           965: @findex _AM29000
        !           966: Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000
        !           967: CPU family.
        !           968: 
        !           969: @item ns32000
        !           970: @findex ns32000
        !           971: @samp{ns32000} is predefined on computers which use the National
        !           972: Semiconductor 32000 series CPU.
        !           973: @end table
        !           974: 
        !           975: Yet other nonstandard predefined macros describe the manufacturer of
        !           976: the system.  For example,
        !           977: 
        !           978: @table @code
        !           979: @item sun
        !           980: @findex sun
        !           981: @samp{sun} is predefined on all models of Sun computers.
        !           982: 
        !           983: @item pyr
        !           984: @findex pyr
        !           985: @samp{pyr} is predefined on all models of Pyramid computers.
        !           986: 
        !           987: @item sequent
        !           988: @findex sequent
        !           989: @samp{sequent} is predefined on all models of Sequent computers.
        !           990: @end table
        !           991: 
        !           992: These predefined symbols are not only nonstandard, they are contrary to the
        !           993: ANSI standard because their names do not start with underscores.
        !           994: Therefore, the option @samp{-ansi} inhibits the definition of these
        !           995: symbols.
        !           996: 
        !           997: This tends to make @samp{-ansi} useless, since many programs depend on the
        !           998: customary nonstandard predefined symbols.  Even system header files check
        !           999: them and will generate incorrect declarations if they do not find the names
        !          1000: that are expected.  You might think that the header files supplied for the
        !          1001: Uglix computer would not need to test what machine they are running on,
        !          1002: because they can simply assume it is the Uglix; but often they do, and they
        !          1003: do so using the customary names.  As a result, very few C programs will
        !          1004: compile with @samp{-ansi}.  We intend to avoid such problems on the GNU
        !          1005: system.
        !          1006: 
        !          1007: What, then, should you do in an ANSI C program to test the type of machine
        !          1008: it will run on?
        !          1009: 
        !          1010: GNU C offers a parallel series of symbols for this purpose, whose names
        !          1011: are made from the customary ones by adding @samp{__} at the beginning
        !          1012: and end.  Thus, the symbol @code{__vax__} would be available on a Vax,
        !          1013: and so on.
        !          1014: 
        !          1015: The set of nonstandard predefined names in the GNU C preprocessor is
        !          1016: controlled (when @code{cpp} is itself compiled) by the macro
        !          1017: @samp{CPP_PREDEFINES}, which should be a string containing @samp{-D}
        !          1018: options, separated by spaces.  For example, on the Sun 3, we use the
        !          1019: following definition:
        !          1020: 
        !          1021: @example
        !          1022: #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
        !          1023: @end example
        !          1024: 
        !          1025: @noindent 
        !          1026: This macro is usually specified in @file{tm.h}.
        !          1027: 
        !          1028: @node Stringification, Concatenation, Predefined, Macros
        !          1029: @subsection Stringification
        !          1030: 
        !          1031: @cindex stringification
        !          1032: @dfn{Stringification} means turning a code fragment into a string constant
        !          1033: whose contents are the text for the code fragment.  For example,
        !          1034: stringifying @samp{foo (z)} results in @samp{"foo (z)"}.
        !          1035: 
        !          1036: In the C preprocessor, stringification is an option available when macro
        !          1037: arguments are substituted into the macro definition.  In the body of the
        !          1038: definition, when an argument name appears, the character @samp{#} before
        !          1039: the name specifies stringification of the corresponding actual argument
        !          1040: when it is substituted at that point in the definition.  The same argument
        !          1041: may be substituted in other places in the definition without
        !          1042: stringification if the argument name appears in those places with no
        !          1043: @samp{#}.
        !          1044: 
        !          1045: Here is an example of a macro definition that uses stringification:
        !          1046: 
        !          1047: @smallexample
        !          1048: #define WARN_IF(EXP) \
        !          1049: do @{ if (EXP) \
        !          1050:         fprintf (stderr, "Warning: " #EXP "\n"); @} \
        !          1051: while (0)
        !          1052: @end smallexample
        !          1053: 
        !          1054: @noindent
        !          1055: Here the actual argument for @samp{EXP} is substituted once as given,
        !          1056: into the @samp{if} statement, and once as stringified, into the
        !          1057: argument to @samp{fprintf}.  The @samp{do} and @samp{while (0)} are
        !          1058: a kludge to make it possible to write @samp{WARN_IF (@var{arg});},
        !          1059: which the resemblance of @samp{WARN_IF} to a function would make
        !          1060: C programmers want to do; @pxref{Swallow Semicolon}).
        !          1061: 
        !          1062: The stringification feature is limited to transforming one macro argument
        !          1063: into one string constant: there is no way to combine the argument with
        !          1064: other text and then stringify it all together.  But the example above shows
        !          1065: how an equivalent result can be obtained in ANSI Standard C using the
        !          1066: feature that adjacent string constants are concatenated as one string
        !          1067: constant.  The preprocessor stringifies the actual value of @samp{EXP} 
        !          1068: into a separate string constant, resulting in text like
        !          1069: 
        !          1070: @smallexample
        !          1071: do @{ if (x == 0) \
        !          1072:         fprintf (stderr, "Warning: " "x == 0" "\n"); @} \
        !          1073: while (0)
        !          1074: @end smallexample
        !          1075: 
        !          1076: @noindent
        !          1077: but the C compiler then sees three consecutive string constants and
        !          1078: concatenates them into one, producing effectively
        !          1079: 
        !          1080: @smallexample
        !          1081: do @{ if (x == 0) \
        !          1082:         fprintf (stderr, "Warning: x == 0\n"); @} \
        !          1083: while (0)
        !          1084: @end smallexample
        !          1085: 
        !          1086: Stringification in C involves more than putting doublequote characters
        !          1087: around the fragment; it is necessary to put backslashes in front of all
        !          1088: doublequote characters, and all backslashes in string and character
        !          1089: constants, in order to get a valid C string constant with the proper
        !          1090: contents.  Thus, stringifying @samp{p = "foo\n";} results in @samp{"p =
        !          1091: \"foo\\n\";"}.  However, backslashes that are not inside of string or
        !          1092: character constants are not duplicated: @samp{\n} by itself stringifies to
        !          1093: @samp{"\n"}.
        !          1094: 
        !          1095: Whitespace (including comments) in the text being stringified is handled
        !          1096: according to precise rules.  All leading and trailing whitespace is ignored.
        !          1097: Any sequence of whitespace in the middle of the text is converted to
        !          1098: a single space in the stringified result.
        !          1099: 
        !          1100: @node Concatenation, Undefining, Stringification, Macros
        !          1101: @subsection Concatenation
        !          1102: 
        !          1103: @cindex concatenation
        !          1104: @dfn{Concatenation} means joining two strings into one.  In the context
        !          1105: of macro expansion, concatenation refers to joining two lexical units
        !          1106: into one longer one.  Specifically, an actual argument to the macro can be
        !          1107: concatenated with another actual argument or with fixed text to produce
        !          1108: a longer name.  The longer name might be the name of a function,
        !          1109: variable or type, or a C keyword; it might even be the name of another
        !          1110: macro, in which case it will be expanded.
        !          1111: 
        !          1112: When you define a macro, you request concatenation with the special
        !          1113: operator @samp{##} in the macro body.  When the macro is called,
        !          1114: after actual arguments are substituted, all @samp{##} operators are
        !          1115: deleted, and so is any whitespace next to them (including whitespace
        !          1116: that was part of an actual argument).  The result is to concatenate
        !          1117: the syntactic tokens on either side of the @samp{##}.
        !          1118: 
        !          1119: Consider a C program that interprets named commands.  There probably needs
        !          1120: to be a table of commands, perhaps an array of structures declared as
        !          1121: follows:
        !          1122: 
        !          1123: @example
        !          1124: struct command
        !          1125: @{
        !          1126:   char *name;
        !          1127:   void (*function) ();
        !          1128: @};
        !          1129: 
        !          1130: struct command commands[] =
        !          1131: @{
        !          1132:   @{ "quit", quit_command@},
        !          1133:   @{ "help", help_command@},
        !          1134:   @dots{}
        !          1135: @};
        !          1136: @end example
        !          1137: 
        !          1138: It would be cleaner not to have to give each command name twice, once in
        !          1139: the string constant and once in the function name.  A macro which takes the
        !          1140: name of a command as an argument can make this unnecessary.  The string
        !          1141: constant can be created with stringification, and the function name by
        !          1142: concatenating the argument with @samp{_command}.  Here is how it is done:
        !          1143: 
        !          1144: @example
        !          1145: #define COMMAND(NAME)  @{ #NAME, NAME ## _command @}
        !          1146: 
        !          1147: struct command commands[] =
        !          1148: @{
        !          1149:   COMMAND (quit),
        !          1150:   COMMAND (help),
        !          1151:   @dots{}
        !          1152: @};
        !          1153: @end example
        !          1154: 
        !          1155: The usual case of concatenation is concatenating two names (or a name and a
        !          1156: number) into a longer name.  But this isn't the only valid case.  It is
        !          1157: also possible to concatenate two numbers (or a number and a name, such as
        !          1158: @samp{1.5} and @samp{e3}) into a number.  Also, multi-character operators
        !          1159: such as @samp{+=} can be formed by concatenation.  In some cases it is even
        !          1160: possible to piece together a string constant.  However, two pieces of text
        !          1161: that don't together form a valid lexical unit cannot be concatenated.  For
        !          1162: example, concatenation with @samp{x} on one side and @samp{+} on the other
        !          1163: is not meaningful because those two characters can't fit together in any
        !          1164: lexical unit of C.  The ANSI standard says that such attempts at
        !          1165: concatenation are undefined, but in the GNU C preprocessor it is well
        !          1166: defined: it puts the @samp{x} and @samp{+} side by side with no particular
        !          1167: special results.
        !          1168: 
        !          1169: Keep in mind that the C preprocessor converts comments to whitespace before
        !          1170: macros are even considered.  Therefore, you cannot create a comment by
        !          1171: concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a
        !          1172: comment is not a lexical unit, but rather the beginning of a ``long'' space
        !          1173: character.  Also, you can freely use comments next to a @samp{##} in a
        !          1174: macro definition, or in actual arguments that will be concatenated, because
        !          1175: the comments will be converted to spaces at first sight, and concatenation
        !          1176: will later discard the spaces.
        !          1177: 
        !          1178: @node Undefining, Redefining, Concatenation, Macros
        !          1179: @subsection Undefining Macros
        !          1180: 
        !          1181: @cindex undefining macros
        !          1182: To @dfn{undefine} a macro means to cancel its definition.  This is done
        !          1183: with the @samp{#undef} command.  @samp{#undef} is followed by the macro
        !          1184: name to be undefined.
        !          1185: 
        !          1186: Like definition, undefinition occurs at a specific point in the source
        !          1187: file, and it applies starting from that point.  The name ceases to be a
        !          1188: macro name, and from that point on it is treated by the preprocessor as if
        !          1189: it had never been a macro name.
        !          1190: 
        !          1191: For example,
        !          1192: 
        !          1193: @example
        !          1194: #define FOO 4
        !          1195: x = FOO;
        !          1196: #undef FOO
        !          1197: x = FOO;
        !          1198: @end example
        !          1199: 
        !          1200: @noindent
        !          1201: expands into
        !          1202: 
        !          1203: @example
        !          1204: x = 4;
        !          1205: 
        !          1206: x = FOO;
        !          1207: @end example
        !          1208: 
        !          1209: @noindent
        !          1210: In this example, @samp{FOO} had better be a variable or function as well
        !          1211: as (temporarily) a macro, in order for the result of the expansion to be
        !          1212: valid C code.
        !          1213: 
        !          1214: The same form of @samp{#undef} command will cancel definitions with
        !          1215: arguments or definitions that don't expect arguments.  The @samp{#undef}
        !          1216: command has no effect when used on a name not currently defined as a macro.
        !          1217: 
        !          1218: @node Redefining, Macro Pitfalls, Undefining, Macros
        !          1219: @subsection Redefining Macros
        !          1220: 
        !          1221: @cindex redefining macros
        !          1222: @dfn{Redefining} a macro means defining (with @samp{#define}) a name that
        !          1223: is already defined as a macro.
        !          1224: 
        !          1225: A redefinition is trivial if the new definition is transparently identical
        !          1226: to the old one.  You probably wouldn't deliberately write a trivial
        !          1227: redefinition, but they can happen automatically when a header file is
        !          1228: included more than once (@pxref{Header Files}), so they are accepted
        !          1229: silently and without effect.
        !          1230: 
        !          1231: Nontrivial redefinition is considered likely to be an error, so
        !          1232: it provokes a warning message from the preprocessor.  However, sometimes it
        !          1233: is useful to change the definition of a macro in mid-compilation.  You can
        !          1234: inhibit the warning by undefining the macro with @samp{#undef} before the
        !          1235: second definition.
        !          1236: 
        !          1237: In order for a redefinition to be trivial, the new definition must
        !          1238: exactly match the one already in effect, with two possible exceptions:
        !          1239: 
        !          1240: @itemize @bullet
        !          1241: @item
        !          1242: Whitespace may be added or deleted at the beginning or the end.
        !          1243: 
        !          1244: @item
        !          1245: Whitespace may be changed in the middle (but not inside strings).
        !          1246: However, it may not be eliminated entirely, and it may not be added
        !          1247: where there was no whitespace at all.
        !          1248: @end itemize
        !          1249: 
        !          1250: Recall that a comment counts as whitespace.
        !          1251: 
        !          1252: @node Macro Pitfalls,, Redefining, Macros
        !          1253: @subsection Pitfalls and Subtleties of Macros
        !          1254: 
        !          1255: In this section we describe some special rules that apply to macros and
        !          1256: macro expansion, and point out certain cases in which the rules have
        !          1257: counterintuitive consequences that you must watch out for.
        !          1258: 
        !          1259: @menu
        !          1260: * Misnesting::        Macros can contain unmatched parentheses.
        !          1261: * Macro Parentheses:: Why apparently superfluous parentheses
        !          1262:                          may be necessary to avoid incorrect grouping.
        !          1263: * Swallow Semicolon:: Macros that look like functions
        !          1264:                          but expand into compound statements.
        !          1265: * Side Effects::      Unsafe macros that cause trouble when
        !          1266:                          arguments contain side effects.
        !          1267: * Self-Reference::    Macros whose definitions use the macros' own names.
        !          1268: * Argument Prescan::  Actual arguments are checked for macro calls
        !          1269:                          before they are substituted.
        !          1270: * Cascaded Macros::   Macros whose definitions use other macros.
        !          1271: * Newlines in Args::  Sometimes line numbers get confused.
        !          1272: @end menu
        !          1273: 
        !          1274: @node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls
        !          1275: @subsubsection Improperly Nested Constructs
        !          1276: 
        !          1277: Recall that when a macro is called with arguments, the arguments are
        !          1278: substituted into the macro body and the result is checked, together with
        !          1279: the rest of the input file, for more macro calls.
        !          1280: 
        !          1281: It is possible to piece together a macro call coming partially from the
        !          1282: macro body and partially from the actual arguments.  For example,
        !          1283: 
        !          1284: @example
        !          1285: #define double(x) (2*(x))
        !          1286: #define call_with_1(x) x(1)
        !          1287: @end example
        !          1288: 
        !          1289: @noindent
        !          1290: would expand @samp{call_with_1 (double)} into @samp{(2*(1))}.
        !          1291: 
        !          1292: Macro definitions do not have to have balanced parentheses.  By writing an
        !          1293: unbalanced open parenthesis in a macro body, it is possible to create a
        !          1294: macro call that begins inside the macro body but ends outside of it.  For
        !          1295: example,
        !          1296: 
        !          1297: @example
        !          1298: #define strange(file) fprintf (file, "%s %d",
        !          1299: @dots{}
        !          1300: strange(stderr) p, 35)
        !          1301: @end example
        !          1302: 
        !          1303: @noindent
        !          1304: This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}!
        !          1305: 
        !          1306: @node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls
        !          1307: @subsubsection Unintended Grouping of Arithmetic
        !          1308: 
        !          1309: You may have noticed that in most of the macro definition examples shown
        !          1310: above, each occurrence of a macro argument name had parentheses around it.
        !          1311: In addition, another pair of parentheses usually surround the entire macro
        !          1312: definition.  Here is why it is best to write macros that way.
        !          1313: 
        !          1314: Suppose you define a macro as follows,
        !          1315: 
        !          1316: @example
        !          1317: #define ceil_div(x, y) (x + y - 1) / y
        !          1318: @end example
        !          1319: 
        !          1320: @noindent
        !          1321: whose purpose is to divide, rounding up.  (One use for this operation is
        !          1322: to compute how many @samp{int} objects are needed to hold a certain
        !          1323: number of @samp{char} objects.)  Then suppose it is used as follows:
        !          1324: 
        !          1325: @example
        !          1326: a = ceil_div (b & c, sizeof (int));
        !          1327: @end example
        !          1328: 
        !          1329: @noindent
        !          1330: This expands into
        !          1331: 
        !          1332: @example
        !          1333: a = (b & c + sizeof (int) - 1) / sizeof (int);
        !          1334: @end example
        !          1335: 
        !          1336: @noindent
        !          1337: which does not do what is intended.  The operator-precedence rules of
        !          1338: C make it equivalent to this:
        !          1339: 
        !          1340: @example
        !          1341: a = (b & (c + sizeof (int) - 1)) / sizeof (int);
        !          1342: @end example
        !          1343: 
        !          1344: @noindent
        !          1345: But what we want is this:
        !          1346: 
        !          1347: @example
        !          1348: a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
        !          1349: @end example
        !          1350: 
        !          1351: @noindent
        !          1352: Defining the macro as
        !          1353: 
        !          1354: @example
        !          1355: #define ceil_div(x, y) ((x) + (y) - 1) / (y)
        !          1356: @end example
        !          1357: 
        !          1358: @noindent
        !          1359: provides the desired result.
        !          1360: 
        !          1361: However, unintended grouping can result in another way.  Consider
        !          1362: @samp{sizeof ceil_div(1, 2)}.  That has the appearance of a C expression
        !          1363: that would compute the size of the type of @samp{ceil_div (1, 2)}, but in
        !          1364: fact it means something very different.  Here is what it expands to:
        !          1365: 
        !          1366: @example
        !          1367: sizeof ((1) + (2) - 1) / (2)
        !          1368: @end example
        !          1369: 
        !          1370: @noindent
        !          1371: This would take the size of an integer and divide it by two.  The precedence
        !          1372: rules have put the division outside the @samp{sizeof} when it was intended
        !          1373: to be inside.
        !          1374: 
        !          1375: Parentheses around the entire macro definition can prevent such problems.
        !          1376: Here, then, is the recommended way to define @samp{ceil_div}:
        !          1377: 
        !          1378: @example
        !          1379: #define ceil_div(x, y) (((x) + (y) - 1) / (y))
        !          1380: @end example
        !          1381: 
        !          1382: @node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls
        !          1383: @subsubsection Swallowing the Semicolon
        !          1384: 
        !          1385: @cindex semicolons (after macro calls)
        !          1386: Often it is desirable to define a macro that expands into a compound
        !          1387: statement.  Consider, for example, the following macro, that advances a
        !          1388: pointer (the argument @samp{p} says where to find it) across whitespace
        !          1389: characters:
        !          1390: 
        !          1391: @example
        !          1392: #define SKIP_SPACES (p, limit)  \
        !          1393: @{ register char *lim = (limit); \
        !          1394:   while (p != lim) @{            \
        !          1395:     if (*p++ != ' ') @{          \
        !          1396:       p--; break; @}@}@}
        !          1397: @end example
        !          1398: 
        !          1399: @noindent
        !          1400: Here Backslash-Newline is used to split the macro definition, which must
        !          1401: be a single line, so that it resembles the way such C code would be
        !          1402: laid out if not part of a macro definition.
        !          1403: 
        !          1404: A call to this macro might be @samp{SKIP_SPACES (p, lim)}.  Strictly
        !          1405: speaking, the call expands to a compound statement, which is a complete
        !          1406: statement with no need for a semicolon to end it.  But it looks like a
        !          1407: function call.  So it minimizes confusion if you can use it like a function
        !          1408: call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);}
        !          1409: 
        !          1410: But this can cause trouble before @samp{else} statements, because the
        !          1411: semicolon is actually a null statement.  Suppose you write
        !          1412: 
        !          1413: @example
        !          1414: if (*p != 0)
        !          1415:   SKIP_SPACES (p, lim);
        !          1416: else @dots{}
        !          1417: @end example
        !          1418: 
        !          1419: @noindent
        !          1420: The presence of two statements---the compound statement and a null
        !          1421: statement---in between the @samp{if} condition and the @samp{else}
        !          1422: makes invalid C code.
        !          1423: 
        !          1424: The definition of the macro @samp{SKIP_SPACES} can be altered to solve
        !          1425: this problem, using a @samp{do @dots{} while} statement.  Here is how:
        !          1426: 
        !          1427: @example
        !          1428: #define SKIP_SPACES (p, limit)     \
        !          1429: do @{ register char *lim = (limit); \
        !          1430:      while (p != lim) @{            \
        !          1431:        if (*p++ != ' ') @{          \
        !          1432:          p--; break; @}@}@}           \
        !          1433: while (0)
        !          1434: @end example
        !          1435: 
        !          1436: Now @samp{SKIP_SPACES (p, lim);} expands into
        !          1437: 
        !          1438: @example
        !          1439: do @{@dots{}@} while (0);
        !          1440: @end example
        !          1441: 
        !          1442: @noindent
        !          1443: which is one statement.
        !          1444: 
        !          1445: @node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls
        !          1446: @subsubsection Duplication of Side Effects
        !          1447: 
        !          1448: @cindex side effects (in macro arguments)
        !          1449: @cindex unsafe macros
        !          1450: Many C programs define a macro @samp{min}, for ``minimum'', like this:
        !          1451: 
        !          1452: @example
        !          1453: #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
        !          1454: @end example
        !          1455: 
        !          1456: When you use this macro with an argument containing a side effect,
        !          1457: as shown here,
        !          1458: 
        !          1459: @example
        !          1460: next = min (x + y, foo (z));
        !          1461: @end example
        !          1462: 
        !          1463: @noindent
        !          1464: it expands as follows:
        !          1465: 
        !          1466: @example
        !          1467: next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
        !          1468: @end example
        !          1469: 
        !          1470: @noindent
        !          1471: where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)}
        !          1472: for @samp{Y}.
        !          1473: 
        !          1474: The function @samp{foo} is used only once in the statement as it appears
        !          1475: in the program, but the expression @samp{foo (z)} has been substituted
        !          1476: twice into the macro expansion.  As a result, @samp{foo} might be called
        !          1477: two times when the statement is executed.  If it has side effects or
        !          1478: if it takes a long time to compute, the results might not be what you
        !          1479: intended.  We say that @samp{min} is an @dfn{unsafe} macro.
        !          1480: 
        !          1481: The best solution to this problem is to define @samp{min} in a way that
        !          1482: computes the value of @samp{foo (z)} only once.  The C language offers no
        !          1483: standard way to do this, but it can be done with GNU C extensions as
        !          1484: follows:
        !          1485: 
        !          1486: @example
        !          1487: #define min(X, Y)                     \
        !          1488: (@{ typeof (X) __x = (X), __y = (Y);   \
        !          1489:    (__x < __y) ? __x : __y; @})
        !          1490: @end example
        !          1491: 
        !          1492: If you do not wish to use GNU C extensions, the only solution is to be
        !          1493: careful when @emph{using} the macro @samp{min}.  For example, you can
        !          1494: calculate the value of @samp{foo (z)}, save it in a variable, and use that
        !          1495: variable in @samp{min}:
        !          1496: 
        !          1497: @example
        !          1498: #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
        !          1499: @dots{}
        !          1500: @{
        !          1501:   int tem = foo (z);
        !          1502:   next = min (x + y, tem);
        !          1503: @}
        !          1504: @end example
        !          1505: 
        !          1506: @noindent
        !          1507: (where we assume that @samp{foo} returns type @samp{int}).
        !          1508: 
        !          1509: @node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls
        !          1510: @subsubsection Self-Referential Macros
        !          1511: 
        !          1512: @cindex self-reference
        !          1513: A @dfn{self-referential} macro is one whose name appears in its definition.
        !          1514: A special feature of ANSI Standard C is that the self-reference is not
        !          1515: considered a macro call.  It is passed into the preprocessor output
        !          1516: unchanged.
        !          1517: 
        !          1518: Let's consider an example:
        !          1519: 
        !          1520: @example
        !          1521: #define foo (4 + foo)
        !          1522: @end example
        !          1523: 
        !          1524: @noindent
        !          1525: where @samp{foo} is also a variable in your program.
        !          1526: 
        !          1527: Following the ordinary rules, each reference to @samp{foo} will expand into
        !          1528: @samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(4
        !          1529: + (4 + foo))}; and so on until it causes a fatal error (memory full) in the
        !          1530: preprocessor.
        !          1531: 
        !          1532: However, the special rule about self-reference cuts this process short
        !          1533: after one step, at @samp{(4 + foo)}.  Therefore, this macro definition
        !          1534: has the possibly useful effect of causing the program to add 4 to
        !          1535: the value of @samp{foo} wherever @samp{foo} is referred to.
        !          1536: 
        !          1537: In most cases, it is a bad idea to take advantage of this feature.  A
        !          1538: person reading the program who sees that @samp{foo} is a variable will
        !          1539: not expect that it is a macro as well.  The reader will come across the
        !          1540: identifier @samp{foo} in the program and think its value should be that
        !          1541: of the variable @samp{foo}, whereas in fact the value is four greater.
        !          1542: 
        !          1543: The special rule for self-reference applies also to @dfn{indirect}
        !          1544: self-reference.  This is the case where a macro @var{x} expands to use a
        !          1545: macro @samp{y}, and the expansion of @samp{y} refers to the macro
        !          1546: @samp{x}.  The resulting reference to @samp{x} comes indirectly from the
        !          1547: expansion of @samp{x}, so it is a self-reference and is not further
        !          1548: expanded.  Thus, after
        !          1549: 
        !          1550: @example
        !          1551: #define x (4 + y)
        !          1552: #define y (2 * x)
        !          1553: @end example
        !          1554: 
        !          1555: @noindent
        !          1556: @samp{x} would expand into @samp{(4 + (2 * x))}.  Clear?
        !          1557: 
        !          1558: But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}.
        !          1559: Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference
        !          1560: because @samp{x} is not ``in progress''.  So it does expand.  However,
        !          1561: the expansion of @samp{x} contains a reference to @samp{y}, and that
        !          1562: is an indirect self-reference now because @samp{y} is ``in progress''.
        !          1563: The result is that @samp{y} expands to @samp{(2 * (4 + y))}.
        !          1564: 
        !          1565: It is not clear that this behavior would ever be useful, but it is specified
        !          1566: by the ANSI C standard, so you may need to understand it.
        !          1567: 
        !          1568: @node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls
        !          1569: @subsubsection Separate Expansion of Macro Arguments
        !          1570: 
        !          1571: We have explained that the expansion of a macro, including the substituted
        !          1572: actual arguments, is scanned over again for macro calls to be expanded.
        !          1573: 
        !          1574: What really happens is more subtle: first each actual argument text is scanned
        !          1575: separately for macro calls.  Then the results of this are substituted into
        !          1576: the macro body to produce the macro expansion, and the macro expansion
        !          1577: is scanned again for macros to expand.
        !          1578: 
        !          1579: The result is that the actual arguments are scanned @emph{twice} to expand
        !          1580: macro calls in them.
        !          1581: 
        !          1582: Most of the time, this has no effect.  If the actual argument contained
        !          1583: any macro calls, they are expanded during the first scan.  The result
        !          1584: therefore contains no macro calls, so the second scan does not change it.
        !          1585: If the actual argument were substituted as given, with no prescan,
        !          1586: the single remaining scan would find the same macro calls and produce
        !          1587: the same results.
        !          1588: 
        !          1589: You might expect the double scan to change the results when a
        !          1590: self-referential macro is used in an actual argument of another macro
        !          1591: (@pxref{Self-Reference}): the self-referential macro would be expanded once
        !          1592: in the first scan, and a second time in the second scan.  But this is not
        !          1593: what happens.  The self-references that do not expand in the first scan are
        !          1594: marked so that they will not expand in the second scan either.
        !          1595: 
        !          1596: The prescan is not done when an argument is stringified or concatenated.
        !          1597: Thus,
        !          1598: 
        !          1599: @example
        !          1600: #define str(s) #s
        !          1601: #define foo 4
        !          1602: str (foo)
        !          1603: @end example
        !          1604: 
        !          1605: @noindent
        !          1606: expands to @samp{"foo"}.  Once more, prescan has been prevented from
        !          1607: having any noticeable effect.
        !          1608: 
        !          1609: More precisely, stringification and concatenation use the argument as
        !          1610: written, in un-prescanned form.  The same actual argument would be used in
        !          1611: prescanned form if it is substituted elsewhere without stringification or
        !          1612: concatenation.
        !          1613: 
        !          1614: @example
        !          1615: #define str(s) #s lose(s)
        !          1616: #define foo 4
        !          1617: str (foo)
        !          1618: @end example
        !          1619: 
        !          1620: expands to @samp{"foo" lose(4)}.
        !          1621: 
        !          1622: You might now ask, ``Why mention the prescan, if it makes no difference?
        !          1623: And why not skip it and make the preprocessor faster?''  The answer is
        !          1624: that the prescan does make a difference in three special cases:
        !          1625: 
        !          1626: @itemize @bullet
        !          1627: @item
        !          1628: Nested calls to a macro.
        !          1629: 
        !          1630: @item
        !          1631: Macros that call other macros that stringify or concatenate.
        !          1632: 
        !          1633: @item
        !          1634: Macros whose expansions contain unshielded commas.
        !          1635: @end itemize
        !          1636: 
        !          1637: We say that @dfn{nested} calls to a macro occur when a macro's actual
        !          1638: argument contains a call to that very macro.  For example, if @samp{f}
        !          1639: is a macro that expects one argument, @samp{f (f (1))} is a nested
        !          1640: pair of calls to @samp{f}.  The desired expansion is made by
        !          1641: expanding @samp{f (1)} and substituting that into the definition of
        !          1642: @samp{f}.  The prescan causes the expected result to happen.
        !          1643: Without the prescan, @samp{f (1)} itself would be substituted as
        !          1644: an actual argument, and the inner use of @samp{f} would appear
        !          1645: during the main scan as an indirect self-reference and would not
        !          1646: be expanded.  Here, the prescan cancels an undesirable side effect
        !          1647: (in the medical, not computational, sense of the term) of the special
        !          1648: rule for self-referential macros.
        !          1649: 
        !          1650: But prescan causes trouble in certain other cases of nested macro calls.
        !          1651: Here is an example:
        !          1652: 
        !          1653: @example
        !          1654: #define foo  a,b
        !          1655: #define bar(x) lose(x)
        !          1656: #define lose(x) (1 + (x))
        !          1657: 
        !          1658: bar(foo)
        !          1659: @end example
        !          1660: 
        !          1661: @noindent
        !          1662: We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which
        !          1663: would then turn into @samp{(1 + (a,b))}.  But instead, @samp{bar(foo)}
        !          1664: expands into @samp{lose(a,b)}, and you get an error because @code{lose}
        !          1665: requires a single argument.  In this case, the problem is easily solved
        !          1666: by the same parentheses that ought to be used to prevent misnesting of
        !          1667: arithmetic operations:
        !          1668: 
        !          1669: @example
        !          1670: #define foo (a,b)
        !          1671: #define bar(x) lose((x))
        !          1672: @end example
        !          1673: 
        !          1674: The problem is more serious when the operands of the macro are not
        !          1675: expressions; for example, when they are statements.  Then parentheses
        !          1676: are unacceptable because they would make for invalid C code:
        !          1677: 
        !          1678: @example
        !          1679: #define foo @{ int a, b; @dots{} @}
        !          1680: @end example
        !          1681: 
        !          1682: @noindent
        !          1683: In GNU C you can shield the commas using the @samp{(@{@dots{}@})}
        !          1684: construct which turns a compound statement into an expression:
        !          1685: 
        !          1686: @example
        !          1687: #define foo (@{ int a, b; @dots{} @})
        !          1688: @end example
        !          1689: 
        !          1690: Or you can rewrite the macro definition to avoid such commas:
        !          1691: 
        !          1692: @example
        !          1693: #define foo @{ int a; int b; @dots{} @}
        !          1694: @end example
        !          1695: 
        !          1696: There is also one case where prescan is useful.  It is possible
        !          1697: to use prescan to expand an argument and then stringify it---if you use
        !          1698: two levels of macros.  Let's add a new macro @samp{xstr} to the
        !          1699: example shown above:
        !          1700: 
        !          1701: @example
        !          1702: #define xstr(s) str(s)
        !          1703: #define str(s) #s
        !          1704: #define foo 4
        !          1705: xstr (foo)
        !          1706: @end example
        !          1707: 
        !          1708: This expands into @samp{"4"}, not @samp{"foo"}.  The reason for the
        !          1709: difference is that the argument of @samp{xstr} is expanded at prescan
        !          1710: (because @samp{xstr} does not specify stringification or concatenation of
        !          1711: the argument).  The result of prescan then forms the actual argument for
        !          1712: @samp{str}.  @samp{str} uses its argument without prescan because it
        !          1713: performs stringification; but it cannot prevent or undo the prescanning
        !          1714: already done by @samp{xstr}.
        !          1715: 
        !          1716: @node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls
        !          1717: @subsubsection Cascaded Use of Macros
        !          1718: 
        !          1719: @cindex cascaded macros
        !          1720: @cindex macro body uses macro
        !          1721: A @dfn{cascade} of macros is when one macro's body contains a reference
        !          1722: to another macro.  This is very common practice.  For example,
        !          1723: 
        !          1724: @example
        !          1725: #define BUFSIZE 1020
        !          1726: #define TABLESIZE BUFSIZE
        !          1727: @end example
        !          1728: 
        !          1729: This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
        !          1730: The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
        !          1731: specify---in this case, @samp{BUFSIZE}---and does not check to see whether
        !          1732: it too is the name of a macro.
        !          1733: 
        !          1734: It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion
        !          1735: is checked for more macro names.
        !          1736: 
        !          1737: This makes a difference if you change the definition of @samp{BUFSIZE}
        !          1738: at some point in the source file.  @samp{TABLESIZE}, defined as shown,
        !          1739: will always expand using the definition of @samp{BUFSIZE} that is
        !          1740: currently in effect:
        !          1741: 
        !          1742: @example
        !          1743: #define BUFSIZE 1020
        !          1744: #define TABLESIZE BUFSIZE
        !          1745: #undef BUFSIZE
        !          1746: #define BUFSIZE 37
        !          1747: @end example
        !          1748: 
        !          1749: @noindent
        !          1750: Now @samp{TABLESIZE} expands (in two stages) to @samp{37}.
        !          1751: 
        !          1752: @node Newlines in Args,, Cascaded Macros, Macro Pitfalls
        !          1753: @subsection Newlines in Macro Arguments
        !          1754: 
        !          1755: Traditional macro processing carries forward all newlines in macro
        !          1756: arguments into the expansion of the macro.  This means that, if some of
        !          1757: the arguments are substituted more than once, or not at all, or out of
        !          1758: order, newlines can be duplicated, lost, or moved around within the
        !          1759: expansion.  If the expansion consists of multiple statements, then the
        !          1760: effect is to distort the line numbers of some of these statements.  The
        !          1761: result can be incorrect line numbers, in error messages or displayed in
        !          1762: a debugger.
        !          1763: 
        !          1764: The GNU C preprocessor operating in ANSI C mode adjusts appropriately
        !          1765: for multiple use of an argument---the first use expands all the
        !          1766: newlines, and subsequent uses of the same argument produce no newlines.
        !          1767: But even in this mode, it can produce incorrect line numbering if
        !          1768: arguments are used out of order, or not used at all.
        !          1769: 
        !          1770: Here is an example illustrating this problem:
        !          1771: 
        !          1772: @example
        !          1773: #define ignore_second_arg(a,b,c) a; c
        !          1774: 
        !          1775: ignore_second_arg (foo (),
        !          1776:                    ignored (),
        !          1777:                    syntax error);
        !          1778: @end example
        !          1779: 
        !          1780: @noindent
        !          1781: The syntax error triggered by the tokens @samp{syntax error} results
        !          1782: in an error message citing line four, even though the statement text
        !          1783: comes from line five.
        !          1784: 
        !          1785: @node Conditionals, Combining Sources, Macros, Top
        !          1786: @section Conditionals
        !          1787: 
        !          1788: @cindex conditionals
        !          1789: In a macro processor, a @dfn{conditional} is a command that allows a part
        !          1790: of the program to be ignored during compilation, on some conditions.
        !          1791: In the C preprocessor, a conditional can test either an arithmetic expression
        !          1792: or whether a name is defined as a macro.
        !          1793: 
        !          1794: A conditional in the C preprocessor resembles in some ways an @samp{if}
        !          1795: statement in C, but it is important to understand the difference between
        !          1796: them.  The condition in an @samp{if} statement is tested during the execution
        !          1797: of your program.  Its purpose is to allow your program to behave differently
        !          1798: from run to run, depending on the data it is operating on.  The condition
        !          1799: in a preprocessor conditional command is tested when your program is compiled.
        !          1800: Its purpose is to allow different code to be included in the program depending
        !          1801: on the situation at the time of compilation.
        !          1802: 
        !          1803: @menu
        !          1804: * Uses: Conditional Uses.       What conditionals are for.
        !          1805: * Syntax: Conditional Syntax.   How conditionals are written.
        !          1806: * Deletion: Deleted Code.       Making code into a comment.
        !          1807: * Macros: Conditionals-Macros.  Why conditionals are used with macros.
        !          1808: * Assertions::                 How and why to use assertions.
        !          1809: * Errors: #error Command.       Detecting inconsistent compilation parameters.
        !          1810: @end menu
        !          1811: 
        !          1812: @node Conditional Uses
        !          1813: @subsection Why Conditionals are Used
        !          1814: 
        !          1815: Generally there are three kinds of reason to use a conditional.
        !          1816: 
        !          1817: @itemize @bullet
        !          1818: @item
        !          1819: A program may need to use different code depending on the machine or
        !          1820: operating system it is to run on.  In some cases the code for one
        !          1821: operating system may be erroneous on another operating system; for
        !          1822: example, it might refer to library routines that do not exist on the
        !          1823: other system.  When this happens, it is not enough to avoid executing
        !          1824: the invalid code: merely having it in the program makes it impossible
        !          1825: to link the program and run it.  With a preprocessor conditional, the
        !          1826: offending code can be effectively excised from the program when it is
        !          1827: not valid.
        !          1828: 
        !          1829: @item
        !          1830: You may want to be able to compile the same source file into two
        !          1831: different programs.  Sometimes the difference between the programs is
        !          1832: that one makes frequent time-consuming consistency checks on its
        !          1833: intermediate data while the other does not.
        !          1834: 
        !          1835: @item
        !          1836: A conditional whose condition is always false is a good way to exclude
        !          1837: code from the program but keep it as a sort of comment for future
        !          1838: reference.
        !          1839: @end itemize
        !          1840: 
        !          1841: Most simple programs that are intended to run on only one machine will
        !          1842: not need to use preprocessor conditionals.
        !          1843: 
        !          1844: @node Conditional Syntax
        !          1845: @subsection Syntax of Conditionals
        !          1846: 
        !          1847: @findex #if
        !          1848: A conditional in the C preprocessor begins with a @dfn{conditional
        !          1849: command}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
        !          1850: @xref{Conditionals-Macros}, for information on @samp{#ifdef} and
        !          1851: @samp{#ifndef}; only @samp{#if} is explained here.
        !          1852: 
        !          1853: @menu
        !          1854: * If: #if Command.     Basic conditionals using @samp{#if} and @samp{#endif}.
        !          1855: * Else: #else Command. Including some text if the condition fails.
        !          1856: * Elif: #elif Command. Testing several alternative possibilities.
        !          1857: @end menu
        !          1858: 
        !          1859: @node #if Command
        !          1860: @subsubsection The @samp{#if} Command
        !          1861: 
        !          1862: The @samp{#if} command in its simplest form consists of
        !          1863: 
        !          1864: @example
        !          1865: #if @var{expression}
        !          1866: @var{controlled text}
        !          1867: #endif /* @var{expression} */
        !          1868: @end example
        !          1869: 
        !          1870: The comment following the @samp{#endif} is not required, but it is a good
        !          1871: practice because it helps people match the @samp{#endif} to the
        !          1872: corresponding @samp{#if}.  Such comments should always be used, except in
        !          1873: short conditionals that are not nested.  In fact, you can put anything at
        !          1874: all after the @samp{#endif} and it will be ignored by the GNU C preprocessor,
        !          1875: but only comments are acceptable in ANSI Standard C.
        !          1876: 
        !          1877: @var{expression} is a C expression of integer type, subject to stringent
        !          1878: restrictions.  It may contain
        !          1879: 
        !          1880: @itemize @bullet
        !          1881: @item
        !          1882: Integer constants, which are all regarded as @code{long} or
        !          1883: @code{unsigned long}.
        !          1884: 
        !          1885: @item
        !          1886: Character constants, which are interpreted according to the character
        !          1887: set and conventions of the machine and operating system on which the
        !          1888: preprocessor is running.  The GNU C preprocessor uses the C data type
        !          1889: @samp{char} for these character constants; therefore, whether some
        !          1890: character codes are negative is determined by the C compiler used to
        !          1891: compile the preprocessor.  If it treats @samp{char} as signed, then
        !          1892: character codes large enough to set the sign bit will be considered
        !          1893: negative; otherwise, no character code is considered negative.
        !          1894: 
        !          1895: @item
        !          1896: Arithmetic operators for addition, subtraction, multiplication,
        !          1897: division, bitwise operations, shifts, comparisons, and @samp{&&} and
        !          1898: @samp{||}.
        !          1899: 
        !          1900: @item
        !          1901: Identifiers that are not macros, which are all treated as zero(!).
        !          1902: 
        !          1903: @item
        !          1904: Macro calls.  All macro calls in the expression are expanded before
        !          1905: actual computation of the expression's value begins.
        !          1906: @end itemize
        !          1907: 
        !          1908: Note that @samp{sizeof} operators and @code{enum}-type values are not allowed.
        !          1909: @code{enum}-type values, like all other identifiers that are not taken
        !          1910: as macro calls and expanded, are treated as zero.
        !          1911: 
        !          1912: The @var{controlled text} inside of a conditional can include
        !          1913: preprocessor commands.  Then the commands inside the conditional are
        !          1914: obeyed only if that branch of the conditional succeeds.  The text can
        !          1915: also contain other conditional groups.  However, the @samp{#if} and
        !          1916: @samp{#endif} commands must balance.
        !          1917: 
        !          1918: @node #else Command
        !          1919: @subsubsection The @samp{#else} Command
        !          1920: 
        !          1921: @findex #else
        !          1922: The @samp{#else} command can be added to a conditional to provide
        !          1923: alternative text to be used if the condition is false.  This is what
        !          1924: it looks like:
        !          1925: 
        !          1926: @example
        !          1927: #if @var{expression}
        !          1928: @var{text-if-true}
        !          1929: #else /* Not @var{expression} */
        !          1930: @var{text-if-false}
        !          1931: #endif /* Not @var{expression} */
        !          1932: @end example
        !          1933: 
        !          1934: If @var{expression} is nonzero, and thus the @var{text-if-true} is 
        !          1935: active, then @samp{#else} acts like a failing conditional and the
        !          1936: @var{text-if-false} is ignored.  Contrariwise, if the @samp{#if}
        !          1937: conditional fails, the @var{text-if-false} is considered included.
        !          1938: 
        !          1939: @node #elif Command
        !          1940: @subsubsection The @samp{#elif} Command
        !          1941: 
        !          1942: @findex #elif
        !          1943: One common case of nested conditionals is used to check for more than two
        !          1944: possible alternatives.  For example, you might have
        !          1945: 
        !          1946: @example
        !          1947: #if X == 1
        !          1948: @dots{}
        !          1949: #else /* X != 1 */
        !          1950: #if X == 2
        !          1951: @dots{}
        !          1952: #else /* X != 2 */
        !          1953: @dots{}
        !          1954: #endif /* X != 2 */
        !          1955: #endif /* X != 1 */
        !          1956: @end example
        !          1957: 
        !          1958: Another conditional command, @samp{#elif}, allows this to be abbreviated
        !          1959: as follows:
        !          1960: 
        !          1961: @example
        !          1962: #if X == 1
        !          1963: @dots{}
        !          1964: #elif X == 2
        !          1965: @dots{}
        !          1966: #else /* X != 2 and X != 1*/
        !          1967: @dots{}
        !          1968: #endif /* X != 2 and X != 1*/
        !          1969: @end example
        !          1970: 
        !          1971: @samp{#elif} stands for ``else if''.  Like @samp{#else}, it goes in the
        !          1972: middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not
        !          1973: require a matching @samp{#endif} of its own.  Like @samp{#if}, the
        !          1974: @samp{#elif} command includes an expression to be tested.
        !          1975: 
        !          1976: The text following the @samp{#elif} is processed only if the original
        !          1977: @samp{#if}-condition failed and the @samp{#elif} condition succeeds.
        !          1978: More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif}
        !          1979: group.  Then the text after each @samp{#elif} is processed only if the
        !          1980: @samp{#elif} condition succeeds after the original @samp{#if} and any
        !          1981: previous @samp{#elif} commands within it have failed.  @samp{#else} is
        !          1982: equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any
        !          1983: number of @samp{#elif} commands, but @samp{#elif} may not follow
        !          1984: @samp{#else}.
        !          1985: 
        !          1986: @node Deleted Code
        !          1987: @subsection Keeping Deleted Code for Future Reference
        !          1988: 
        !          1989: If you replace or delete a part of the program but want to keep the old
        !          1990: code around as a comment for future reference, the easy way to do this is
        !          1991: to put @samp{#if 0} before it and @samp{#endif} after it.
        !          1992: 
        !          1993: This works even if the code being turned off contains conditionals, but
        !          1994: they must be entire conditionals (balanced @samp{#if} and @samp{#endif}).
        !          1995: 
        !          1996: @node Conditionals-Macros
        !          1997: @subsection Conditionals and Macros
        !          1998: 
        !          1999: Conditionals are useful in connection with macros or assertions, because
        !          2000: those are the only ways that an expression's value can vary from one
        !          2001: compilation to another.  A @samp{#if} command whose expression uses no
        !          2002: macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you
        !          2003: might as well determine which one, by computing the value of the
        !          2004: expression yourself, and then simplify the program.
        !          2005: 
        !          2006: For example, here is a conditional that tests the expression
        !          2007: @samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro.
        !          2008: 
        !          2009: @example
        !          2010: #if BUFSIZE == 1020
        !          2011:   printf ("Large buffers!\n");
        !          2012: #endif /* BUFSIZE is large */
        !          2013: @end example
        !          2014: 
        !          2015: (Programmers often wish they could test the size of a variable or data
        !          2016: type in @samp{#if}, but this does not work.  The preprocessor does not
        !          2017: understand @code{sizeof}, or typedef names, or even the type keywords
        !          2018: such as @code{int}.)
        !          2019: 
        !          2020: @findex defined
        !          2021: The special operator @samp{defined} is used in @samp{#if} expressions to
        !          2022: test whether a certain name is defined as a macro.  Either @samp{defined
        !          2023: @var{name}} or @samp{defined (@var{name})} is an expression whose value
        !          2024: is 1 if @var{name} is defined as macro at the current point in the
        !          2025: program, and 0 otherwise.  For the @samp{defined} operator it makes no
        !          2026: difference what the definition of the macro is; all that matters is
        !          2027: whether there is a definition.  Thus, for example,@refill
        !          2028: 
        !          2029: @example
        !          2030: #if defined (vax) || defined (ns16000)
        !          2031: @end example
        !          2032: 
        !          2033: @noindent
        !          2034: would include the following code if either of the names @samp{vax} and
        !          2035: @samp{ns16000} is defined as a macro.  You can test the same condition
        !          2036: using assertions (@pxref{Assertions}), like this:
        !          2037: 
        !          2038: @example
        !          2039: #if #cpu (vax) || #cpu (ns16000)
        !          2040: @end example
        !          2041: 
        !          2042: If a macro is defined and later undefined with @samp{#undef},
        !          2043: subsequent use of the @samp{defined} operator returns 0, because
        !          2044: the name is no longer defined.  If the macro is defined again with
        !          2045: another @samp{#define}, @samp{defined} will recommence returning 1.
        !          2046: 
        !          2047: @findex #ifdef
        !          2048: @findex #ifndef
        !          2049: Conditionals that test just the definedness of one name are very common, so
        !          2050: there are two special short conditional commands for this case.
        !          2051: 
        !          2052: @table @code
        !          2053: @item #ifdef @var{name}
        !          2054: is equivalent to @samp{#if defined (@var{name})}.
        !          2055: 
        !          2056: @item #ifndef @var{name}
        !          2057: is equivalent to @samp{#if ! defined (@var{name})}.
        !          2058: @end table
        !          2059: 
        !          2060: Macro definitions can vary between compilations for several reasons.
        !          2061: 
        !          2062: @itemize @bullet
        !          2063: @item
        !          2064: Some macros are predefined on each kind of machine.  For example, on a
        !          2065: Vax, the name @samp{vax} is a predefined macro.  On other machines, it
        !          2066: would not be defined.
        !          2067: 
        !          2068: @item
        !          2069: Many more macros are defined by system header files.  Different
        !          2070: systems and machines define different macros, or give them different
        !          2071: values.  It is useful to test these macros with conditionals to avoid
        !          2072: using a system feature on a machine where it is not implemented.
        !          2073: 
        !          2074: @item
        !          2075: Macros are a common way of allowing users to customize a program for
        !          2076: different machines or applications.  For example, the macro
        !          2077: @samp{BUFSIZE} might be defined in a configuration file for your
        !          2078: program that is included as a header file in each source file.  You
        !          2079: would use @samp{BUFSIZE} in a preprocessor conditional in order to
        !          2080: generate different code depending on the chosen configuration.
        !          2081: 
        !          2082: @item
        !          2083: Macros can be defined or undefined with @samp{-D} and @samp{-U}
        !          2084: command options when you compile the program.  You can arrange to
        !          2085: compile the same source file into two different programs by choosing
        !          2086: a macro name to specify which program you want, writing conditionals
        !          2087: to test whether or how this macro is defined, and then controlling
        !          2088: the state of the macro with compiler command options.
        !          2089: @xref{Invocation}.
        !          2090: @end itemize
        !          2091: 
        !          2092: @ifinfo
        !          2093: Assertions are usually predefined, but can be defined with preprocessor
        !          2094: commands or command-line options.
        !          2095: @end ifinfo
        !          2096: 
        !          2097: @node Assertions
        !          2098: @subsection Assertions
        !          2099: 
        !          2100: @cindex assertions
        !          2101: @dfn{Assertions} are a more systematic alternative to macros in writing
        !          2102: conditionals to test what sort of computer or system the compiled
        !          2103: program will run on.  Assertions are usually predefined, but you can
        !          2104: define them with preprocessor commands or command-line options.
        !          2105: 
        !          2106: @cindex predicates
        !          2107: The macros traditionally used to describe the type of target are not
        !          2108: classified in any way according to which question they answer; they may
        !          2109: indicate a hardware architecture, a particular hardware model, an
        !          2110: operating system, a particular version of an operating system, or
        !          2111: specific configuration options.  These are jumbled together in a single
        !          2112: namespace.  In contrast, each assertion consists of a named question and
        !          2113: an answer.  The question is usually called the @dfn{predicate}.
        !          2114: An assertion looks like this:
        !          2115: 
        !          2116: @example
        !          2117: #@var{predicate} (@var{answer})
        !          2118: @end example
        !          2119: 
        !          2120: @noindent
        !          2121: You must use a properly formed identifier for @var{predicate}.  The
        !          2122: value of @var{answer} can be any sequence of words; all characters are
        !          2123: significant except for leading and trailing whitespace, and differences
        !          2124: in internal whitespace sequences are ignored.  Thus, @samp{x + y} is
        !          2125: different from @samp{x+y} but equivalent to @samp{x + y}.  @samp{)} is
        !          2126: not allowed in an answer.
        !          2127: 
        !          2128: @cindex testing predicates
        !          2129: Here is a conditional to test whether the answer @var{answer} is asserted
        !          2130: for the predicate @var{predicate}:
        !          2131: 
        !          2132: @example
        !          2133: #if #@var{predicate} (@var{answer})
        !          2134: @end example
        !          2135: 
        !          2136: @noindent
        !          2137: There may be more than one answer asserted for a given predicate.  If
        !          2138: you omit the answer, you can test whether @emph{any} answer is asserted
        !          2139: for @var{predicate}:
        !          2140: 
        !          2141: @example
        !          2142: #if #@var{predicate}
        !          2143: @end example
        !          2144: 
        !          2145: Most of the time, the assertions you test will be predefined assertions.
        !          2146: GNU C provides three predefined predicates: @code{system}, @code{cpu},
        !          2147: and @code{machine}.  @code{system} is for assertions about the type of
        !          2148: software, @code{cpu} describes the type of computer architecture, and
        !          2149: @code{machine} gives more information about the computer.  For example,
        !          2150: on a GNU system, the following assertions would be true:
        !          2151: 
        !          2152: @example
        !          2153: #system (gnu)
        !          2154: #system (mach)
        !          2155: #system (mach 3)
        !          2156: #system (mach 3.@var{subversion})
        !          2157: #system (hurd)
        !          2158: #system (hurd @var{version})
        !          2159: @end example
        !          2160: 
        !          2161: @noindent
        !          2162: and perhaps others.  The alternatives with
        !          2163: more or less version information let you ask more or less detailed
        !          2164: questions about the type of system software.
        !          2165: 
        !          2166: On a Unix system, you would find @code{#system (unix)} and perhaps one of:
        !          2167: @code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)},
        !          2168: @code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)},
        !          2169: @code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)}
        !          2170: with possible version numbers following.
        !          2171: 
        !          2172: Other values for @code{system} are @code{#system (mvs)}
        !          2173: and @code{#system (vms)}.
        !          2174: 
        !          2175: @strong{Portability note:} Many Unix C compilers provide only one answer
        !          2176: for the @code{system} assertion: @code{#system (unix)}, if they support
        !          2177: assertions at all.  This is less than useful.
        !          2178: 
        !          2179: An assertion with a multi-word answer is completely different from several
        !          2180: assertions with individual single-word answers.  For example, the presence
        !          2181: of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true.
        !          2182: It also does not directly imply @code{system (mach)}, but in GNU C, that
        !          2183: last will normally be asserted as well.
        !          2184: 
        !          2185: The current list of possible assertion values for @code{cpu} is:
        !          2186: @code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu
        !          2187: (clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu
        !          2188: (tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)},
        !          2189: @code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu
        !          2190: (m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)},
        !          2191: @code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)},
        !          2192: @code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu
        !          2193: (tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}.
        !          2194: 
        !          2195: @findex #assert
        !          2196: You can create assertions within a C program using @samp{#assert}, like
        !          2197: this:
        !          2198: 
        !          2199: @example
        !          2200: #assert @var{predicate} (@var{answer})
        !          2201: @end example
        !          2202: 
        !          2203: @noindent
        !          2204: (Note the absence of a @samp{#} before @var{predicate}.)
        !          2205: 
        !          2206: @cindex unassert
        !          2207: @cindex assertions, undoing
        !          2208: @cindex retracting assertions
        !          2209: @findex #unassert
        !          2210: Each time you do this, you assert a new true answer for @var{predicate}.
        !          2211: Asserting one answer does not invalidate previously asserted answers;
        !          2212: they all remain true.  The only way to remove an assertion is with
        !          2213: @samp{#unassert}.  @samp{#unassert} has the same syntax as
        !          2214: @samp{#assert}.  You can also remove all assertions about
        !          2215: @var{predicate} like this:
        !          2216: 
        !          2217: @example
        !          2218: #unassert @var{predicate}
        !          2219: @end example
        !          2220: 
        !          2221: You can also add or cancel assertions using command options
        !          2222: when you run @code{gcc} or @code{cpp}.  @xref{Invocation}.
        !          2223: 
        !          2224: @node #error Command
        !          2225: @subsection The @samp{#error} and @samp{#warning} Commands
        !          2226: 
        !          2227: @findex #error
        !          2228: The command @samp{#error} causes the preprocessor to report a fatal
        !          2229: error.  The rest of the line that follows @samp{#error} is used as the
        !          2230: error message.
        !          2231: 
        !          2232: You would use @samp{#error} inside of a conditional that detects a
        !          2233: combination of parameters which you know the program does not properly
        !          2234: support.  For example, if you know that the program will not run
        !          2235: properly on a Vax, you might write
        !          2236: 
        !          2237: @smallexample
        !          2238: #ifdef vax
        !          2239: #error Won't work on Vaxen.  See comments at get_last_object.
        !          2240: #endif
        !          2241: @end smallexample
        !          2242: 
        !          2243: @noindent
        !          2244: @xref{Nonstandard Predefined}, for why this works.
        !          2245: 
        !          2246: If you have several configuration parameters that must be set up by
        !          2247: the installation in a consistent way, you can use conditionals to detect
        !          2248: an inconsistency and report it with @samp{#error}.  For example,
        !          2249: 
        !          2250: @smallexample
        !          2251: #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
        !          2252:     || HASH_TABLE_SIZE % 5 == 0
        !          2253: #error HASH_TABLE_SIZE should not be divisible by a small prime
        !          2254: #endif
        !          2255: @end smallexample
        !          2256: 
        !          2257: @findex #warning
        !          2258: The command @samp{#warning} is like the command @samp{#error}, but causes
        !          2259: the preprocessor to issue a warning and continue preprocessing.  The rest of
        !          2260: the line that follows @samp{#warning} is used as the warning message.
        !          2261: 
        !          2262: You might use @samp{#warning} in obsolete header files, with a message
        !          2263: directing the user to the header file which should be used instead.
        !          2264: 
        !          2265: @node Combining Sources, Other Commands, Conditionals, Top
        !          2266: @section Combining Source Files
        !          2267: 
        !          2268: @cindex line control
        !          2269: @findex #line
        !          2270: One of the jobs of the C preprocessor is to inform the C compiler of where
        !          2271: each line of C code came from: which source file and which line number.
        !          2272: 
        !          2273: C code can come from multiple source files if you use @samp{#include};
        !          2274: both @samp{#include} and the use of conditionals and macros can cause
        !          2275: the line number of a line in the preprocessor output to be different
        !          2276: from the line's number in the original source file.  You will appreciate
        !          2277: the value of making both the C compiler (in error messages) and symbolic
        !          2278: debuggers such as GDB use the line numbers in your source file.
        !          2279: 
        !          2280: The C preprocessor builds on this feature by offering a command by which
        !          2281: you can control the feature explicitly.  This is useful when a file for
        !          2282: input to the C preprocessor is the output from another program such as the
        !          2283: @code{bison} parser generator, which operates on another file that is the
        !          2284: true source file.  Parts of the output from @code{bison} are generated from
        !          2285: scratch, other parts come from a standard parser file.  The rest are copied
        !          2286: nearly verbatim from the source file, but their line numbers in the
        !          2287: @code{bison} output are not the same as their original line numbers.
        !          2288: Naturally you would like compiler error messages and symbolic debuggers to
        !          2289: know the original source file and line number of each line in the
        !          2290: @code{bison} input.
        !          2291: 
        !          2292: @code{bison} arranges this by writing @samp{#line} commands into the output
        !          2293: file.  @samp{#line} is a command that specifies the original line number
        !          2294: and source file name for subsequent input in the current preprocessor input
        !          2295: file.  @samp{#line} has three variants:
        !          2296: 
        !          2297: @table @code
        !          2298: @item #line @var{linenum}
        !          2299: Here @var{linenum} is a decimal integer constant.  This specifies that
        !          2300: the line number of the following line of input, in its original source file,
        !          2301: was @var{linenum}.
        !          2302: 
        !          2303: @item #line @var{linenum} @var{filename}
        !          2304: Here @var{linenum} is a decimal integer constant and @var{filename}
        !          2305: is a string constant.  This specifies that the following line of input
        !          2306: came originally from source file @var{filename} and its line number there
        !          2307: was @var{linenum}.  Keep in mind that @var{filename} is not just a
        !          2308: file name; it is surrounded by doublequote characters so that it looks
        !          2309: like a string constant.
        !          2310: 
        !          2311: @item #line @var{anything else}
        !          2312: @var{anything else} is checked for macro calls, which are expanded.
        !          2313: The result should be a decimal integer constant followed optionally
        !          2314: by a string constant, as described above.
        !          2315: @end table
        !          2316: 
        !          2317: @samp{#line} commands alter the results of the @samp{__FILE__} and
        !          2318: @samp{__LINE__} predefined macros from that point on.  @xref{Standard
        !          2319: Predefined}.
        !          2320: 
        !          2321: The output of the preprocessor (which is the input for the rest of the
        !          2322: compiler) contains commands that look much like @samp{#line} commands.
        !          2323: They start with just @samp{#} instead of @samp{#line}, but this is
        !          2324: followed by a line number and file name as in @samp{#line}.  @xref{Output}.
        !          2325: 
        !          2326: @node Other Commands, Output, Combining Sources, Top
        !          2327: @section Miscellaneous Preprocessor Commands
        !          2328: 
        !          2329: @findex #pragma
        !          2330: @findex #ident
        !          2331: @cindex null command
        !          2332: This section describes three additional preprocessor commands.  They are
        !          2333: not very useful, but are mentioned for completeness.
        !          2334: 
        !          2335: The @dfn{null command} consists of a @samp{#} followed by a Newline, with
        !          2336: only whitespace (including comments) in between.  A null command is
        !          2337: understood as a preprocessor command but has no effect on the preprocessor
        !          2338: output.  The primary significance of the existence of the null command is
        !          2339: that an input line consisting of just a @samp{#} will produce no output,
        !          2340: rather than a line of output containing just a @samp{#}.  Supposedly
        !          2341: some old C programs contain such lines.
        !          2342: 
        !          2343: The ANSI standard specifies that the @samp{#pragma} command has an
        !          2344: arbitrary, implementation-defined effect.  In the GNU C preprocessor,
        !          2345: @samp{#pragma} commands are not used, except for @samp{#pragma once}
        !          2346: (@pxref{Once-Only}).  However, they are left in the preprocessor output,
        !          2347: so they are available to the compilation pass.
        !          2348: 
        !          2349: The @samp{#ident} command is supported for compatibility with certain
        !          2350: other systems.  It is followed by a line of text.  On some systems, the
        !          2351: text is copied into a special place in the object file; on most systems,
        !          2352: the text is ignored and this command has no effect.  Typically
        !          2353: @samp{#ident} is only used in header files supplied with those systems
        !          2354: where it is meaningful.
        !          2355: 
        !          2356: @node Output, Invocation, Other Commands, Top
        !          2357: @section C Preprocessor Output
        !          2358: 
        !          2359: @cindex output format
        !          2360: The output from the C preprocessor looks much like the input, except
        !          2361: that all preprocessor command lines have been replaced with blank lines
        !          2362: and all comments with spaces.  Whitespace within a line is not altered;
        !          2363: however, a space is inserted after the expansions of most macro calls.
        !          2364: 
        !          2365: Source file name and line number information is conveyed by lines of
        !          2366: the form
        !          2367: 
        !          2368: @example
        !          2369: # @var{linenum} @var{filename} @var{flags}
        !          2370: @end example
        !          2371: 
        !          2372: @noindent
        !          2373: which are inserted as needed into the middle of the input (but never
        !          2374: within a string or character constant).  Such a line means that the
        !          2375: following line originated in file @var{filename} at line @var{linenum}.
        !          2376: 
        !          2377: After the file name comes zero or more flags, which are @samp{1},
        !          2378: @samp{2} or @samp{3}.  If there are multiple flags, spaces separate
        !          2379: them.  Here is what the flags mean:
        !          2380: 
        !          2381: @table @samp
        !          2382: @item 1
        !          2383: This indicates the start of a new file.
        !          2384: @item 2
        !          2385: This indicates returning to a file (after having included another file).
        !          2386: @item 3
        !          2387: This indicates that the following text comes from a system header file,
        !          2388: so certain warnings should be suppressed.
        !          2389: @end table
        !          2390: 
        !          2391: @node Invocation, Concept Index, Output, Top
        !          2392: @section Invoking the C Preprocessor
        !          2393: 
        !          2394: Most often when you use the C preprocessor you will not have to invoke it
        !          2395: explicitly: the C compiler will do so automatically.  However, the
        !          2396: preprocessor is sometimes useful individually.
        !          2397: 
        !          2398: The C preprocessor expects two file names as arguments, @var{infile} and
        !          2399: @var{outfile}.  The preprocessor reads @var{infile} together with any other
        !          2400: files it specifies with @samp{#include}.  All the output generated by the
        !          2401: combined input files is written in @var{outfile}.
        !          2402: 
        !          2403: Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
        !          2404: means to read from standard input and as @var{outfile} means to write to
        !          2405: standard output.  Also, if @var{outfile} or both file names are omitted,
        !          2406: the standard output and standard input are used for the omitted file names.
        !          2407: 
        !          2408: @cindex options
        !          2409: Here is a table of command options accepted by the C preprocessor.
        !          2410: These options can also be given when compiling a C program; they are
        !          2411: passed along automatically to the preprocessor when it is invoked by the
        !          2412: compiler.
        !          2413: 
        !          2414: @table @samp
        !          2415: @item -P
        !          2416: @findex -P
        !          2417: Inhibit generation of @samp{#}-lines with line-number information in
        !          2418: the output from the preprocessor (@pxref{Output}).  This might be
        !          2419: useful when running the preprocessor on something that is not C code
        !          2420: and will be sent to a program which might be confused by the
        !          2421: @samp{#}-lines.
        !          2422: 
        !          2423: @item -C
        !          2424: @findex -C
        !          2425: Do not discard comments: pass them through to the output file.
        !          2426: Comments appearing in arguments of a macro call will be copied to the
        !          2427: output before the expansion of the macro call.
        !          2428: 
        !          2429: @item -traditional
        !          2430: @findex -traditional
        !          2431: Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
        !          2432: 
        !          2433: @itemize @bullet
        !          2434: @item
        !          2435: Traditional macro expansion pays no attention to singlequote or
        !          2436: doublequote characters; macro argument symbols are replaced by the
        !          2437: argument values even when they appear within apparent string or
        !          2438: character constants.
        !          2439: 
        !          2440: @item
        !          2441: Traditionally, it is permissible for a macro expansion to end in the
        !          2442: middle of a string or character constant.  The constant continues into
        !          2443: the text surrounding the macro call.
        !          2444: 
        !          2445: @item
        !          2446: However, traditionally the end of the line terminates a string or
        !          2447: character constant, with no error.
        !          2448: 
        !          2449: @item
        !          2450: In traditional C, a comment is equivalent to no text at all.  (In ANSI
        !          2451: C, a comment counts as whitespace.)
        !          2452: 
        !          2453: @item
        !          2454: Traditional C does not have the concept of a ``preprocessing number''.
        !          2455: It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+},
        !          2456: and @samp{4}.
        !          2457: 
        !          2458: @item
        !          2459: A macro is not suppressed within its own definition, in traditional C.
        !          2460: Thus, any macro that is used recursively inevitably causes an error.
        !          2461: 
        !          2462: @item
        !          2463: The character @samp{#} has no special meaning within a macro definition
        !          2464: in traditional C.
        !          2465: 
        !          2466: @item
        !          2467: In traditional C, the text at the end of a macro expansion can run
        !          2468: together with the text after the macro call, to produce a single token.
        !          2469: (This is impossible in ANSI C.)
        !          2470: 
        !          2471: @item
        !          2472: Traditionally, @samp{\} inside a macro argument suppresses the syntactic
        !          2473: significance of the following character.
        !          2474: @end itemize
        !          2475: 
        !          2476: @item -trigraphs
        !          2477: @findex -trigraphs
        !          2478: Process ANSI standard trigraph sequences.  These are three-character
        !          2479: sequences, all starting with @samp{??}, that are defined by ANSI C to
        !          2480: stand for single characters.  For example, @samp{??/} stands for
        !          2481: @samp{\}, so @samp{'??/n'} is a character constant for a newline.
        !          2482: Strictly speaking, the GNU C preprocessor does not support all
        !          2483: programs in ANSI Standard C unless @samp{-trigraphs} is used, but if
        !          2484: you ever notice the difference it will be with relief.
        !          2485: 
        !          2486: You don't want to know any more about trigraphs.
        !          2487: 
        !          2488: @item -pedantic
        !          2489: @findex -pedantic
        !          2490: Issue warnings required by the ANSI C standard in certain cases such
        !          2491: as when text other than a comment follows @samp{#else} or @samp{#endif}.
        !          2492: 
        !          2493: @item -pedantic-errors
        !          2494: @findex -pedantic-errors
        !          2495: Like @samp{-pedantic}, except that errors are produced rather than
        !          2496: warnings.
        !          2497: 
        !          2498: @item -Wtrigraphs
        !          2499: @findex -Wtrigraphs
        !          2500: Warn if any trigraphs are encountered (assuming they are enabled).
        !          2501: 
        !          2502: @item -Wcomment
        !          2503: @findex -Wcomment
        !          2504: @ignore
        !          2505: @c "Not worth documenting" both singular and plural forms of this
        !          2506: @c option, per RMS.  But also unclear which is better; hence may need to
        !          2507: @c switch this at some future date.  [email protected], 2jan92.
        !          2508: @itemx -Wcomments
        !          2509: (Both forms have the same effect).
        !          2510: @end ignore
        !          2511: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
        !          2512: 
        !          2513: @item -Wall
        !          2514: @findex -Wall
        !          2515: Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not
        !          2516: @samp{-Wtraditional}). 
        !          2517: 
        !          2518: @item -Wtraditional
        !          2519: @findex -Wtraditional
        !          2520: Warn about certain constructs that behave differently in traditional and
        !          2521: ANSI C.
        !          2522: 
        !          2523: @item -I @var{directory}
        !          2524: @findex -I
        !          2525: Add the directory @var{directory} to the end of the list of
        !          2526: directories to be searched for header files (@pxref{Include Syntax}).
        !          2527: This can be used to override a system header file, substituting your
        !          2528: own version, since these directories are searched before the system
        !          2529: header file directories.  If you use more than one @samp{-I} option,
        !          2530: the directories are scanned in left-to-right order; the standard
        !          2531: system directories come after.
        !          2532: 
        !          2533: @item -I-
        !          2534: Any directories specified with @samp{-I} options before the @samp{-I-}
        !          2535: option are searched only for the case of @samp{#include "@var{file}"};
        !          2536: they are not searched for @samp{#include <@var{file}>}.
        !          2537: 
        !          2538: If additional directories are specified with @samp{-I} options after
        !          2539: the @samp{-I-}, these directories are searched for all @samp{#include}
        !          2540: commands.
        !          2541: 
        !          2542: In addition, the @samp{-I-} option inhibits the use of the current
        !          2543: directory as the first search directory for @samp{#include "@var{file}"}.
        !          2544: Therefore, the current directory is searched only if it is requested
        !          2545: explicitly with @samp{-I.}.  Specifying both @samp{-I-} and @samp{-I.}
        !          2546: allows you to control precisely which directories are searched before
        !          2547: the current one and which are searched after.
        !          2548: 
        !          2549: @item -nostdinc
        !          2550: @findex -nostdinc
        !          2551: Do not search the standard system directories for header files.
        !          2552: Only the directories you have specified with @samp{-I} options
        !          2553: (and the current directory, if appropriate) are searched.
        !          2554: 
        !          2555: @item -nostdinc++
        !          2556: @findex -nostdinc++
        !          2557: Do not search for header files in the C++-specific standard directories,
        !          2558: but do still search the other standard directories.
        !          2559: (This option is used when building libg++.)
        !          2560: 
        !          2561: @item -D @var{name}
        !          2562: @findex -D
        !          2563: Predefine @var{name} as a macro, with definition @samp{1}.
        !          2564: 
        !          2565: @item -D @var{name}=@var{definition}
        !          2566: Predefine @var{name} as a macro, with definition @var{definition}.
        !          2567: There are no restrictions on the contents of @var{definition}, but if
        !          2568: you are invoking the preprocessor from a shell or shell-like program you
        !          2569: may need to use the shell's quoting syntax to protect characters such as
        !          2570: spaces that have a meaning in the shell syntax.  If you use more than
        !          2571: one @samp{-D} for the same @var{name}, the rightmost definition takes
        !          2572: effect.
        !          2573: 
        !          2574: @item -U @var{name}
        !          2575: @findex -U
        !          2576: Do not predefine @var{name}.  If both @samp{-U} and @samp{-D} are
        !          2577: specified for one name, the @samp{-U} beats the @samp{-D} and the name
        !          2578: is not predefined.
        !          2579: 
        !          2580: @item -undef
        !          2581: @findex -undef
        !          2582: Do not predefine any nonstandard macros.
        !          2583: 
        !          2584: @item -A @var{predicate}(@var{answer})
        !          2585: @findex -A
        !          2586: Make an assertion with the predicate @var{predicate} and answer
        !          2587: @var{answer}.  @xref{Assertions}.
        !          2588: 
        !          2589: @noindent
        !          2590: You can use @samp{-A-} to disable all predefined assertions; it also
        !          2591: undefines all predefined macros that identify the type of target system.
        !          2592: 
        !          2593: @item -dM
        !          2594: @findex -dM
        !          2595: Instead of outputting the result of preprocessing, output a list of
        !          2596: @samp{#define} commands for all the macros defined during the
        !          2597: execution of the preprocessor, including predefined macros.  This gives
        !          2598: you a way of finding out what is predefined in your version of the
        !          2599: preprocessor; assuming you have no file @samp{foo.h}, the command
        !          2600: 
        !          2601: @example
        !          2602: touch foo.h; cpp -dM foo.h
        !          2603: @end example
        !          2604: 
        !          2605: @noindent 
        !          2606: will show the values of any predefined macros.
        !          2607: 
        !          2608: @item -dD
        !          2609: @findex -dD
        !          2610: Like @samp{-dM} except in two respects: it does @emph{not} include the
        !          2611: predefined macros, and it outputs @emph{both} the @samp{#define}
        !          2612: commands and the result of preprocessing.  Both kinds of output go to
        !          2613: the standard output file.
        !          2614: 
        !          2615: @item -M
        !          2616: @findex -M
        !          2617: Instead of outputting the result of preprocessing, output a rule
        !          2618: suitable for @code{make} describing the dependencies of the main
        !          2619: source file.  The preprocessor outputs one @code{make} rule containing
        !          2620: the object file name for that source file, a colon, and the names of
        !          2621: all the included files.  If there are many included files then the
        !          2622: rule is split into several lines using @samp{\}-newline.
        !          2623: 
        !          2624: This feature is used in automatic updating of makefiles.
        !          2625: 
        !          2626: @item -MM
        !          2627: @findex -MM
        !          2628: Like @samp{-M} but mention only the files included with @samp{#include
        !          2629: "@var{file}"}.  System header files included with @samp{#include
        !          2630: <@var{file}>} are omitted.
        !          2631: 
        !          2632: @item -MD
        !          2633: @findex -MD
        !          2634: Like @samp{-M} but the dependency information is written to files with
        !          2635: names made by replacing @samp{.c} with @samp{.d} at the end of the
        !          2636: input file names.  This is in addition to compiling the file as
        !          2637: specified---@samp{-MD} does not inhibit ordinary compilation the way
        !          2638: @samp{-M} does.
        !          2639: 
        !          2640: In Mach, you can use the utility @code{md} to merge the @samp{.d} files
        !          2641: into a single dependency file suitable for using with the @samp{make}
        !          2642: command.
        !          2643: 
        !          2644: @item -MMD
        !          2645: @findex -MMD
        !          2646: Like @samp{-MD} except mention only user header files, not system
        !          2647: header files.
        !          2648: 
        !          2649: @item -H
        !          2650: @findex -H
        !          2651: Print the name of each header file used, in addition to other normal
        !          2652: activities.
        !          2653: 
        !          2654: @item -imacros @var{file}
        !          2655: @findex -imacros
        !          2656: Process @var{file} as input, discarding the resulting output, before
        !          2657: processing the regular input file.  Because the output generated from
        !          2658: @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
        !          2659: is to make the macros defined in @var{file} available for use in the
        !          2660: main input.
        !          2661: 
        !          2662: @item -include @var{file}
        !          2663: @findex -include
        !          2664: Process @var{file} as input, and include all the resulting output,
        !          2665: before processing the regular input file.  
        !          2666: 
        !          2667: @item -idirafter @var{dir}
        !          2668: @findex -idirafter
        !          2669: @cindex second include path
        !          2670: Add the directory @var{dir} to the second include path.  The directories
        !          2671: on the second include path are searched when a header file is not found
        !          2672: in any of the directories in the main include path (the one that
        !          2673: @samp{-I} adds to).
        !          2674: 
        !          2675: @item -iprefix @var{prefix}
        !          2676: @findex -iprefix
        !          2677: Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
        !          2678: options.
        !          2679: 
        !          2680: @item -iwithprefix @var{dir}
        !          2681: @findex -iwithprefix
        !          2682: Add a directory to the second include path.  The directory's name is
        !          2683: made by concatenating @var{prefix} and @var{dir}, where @var{prefix}
        !          2684: was specified previously with @samp{-iprefix}.
        !          2685: 
        !          2686: @item -lang-c
        !          2687: @itemx -lang-c++
        !          2688: @itemx -lang-objc
        !          2689: @itemx -lang-objc++
        !          2690: @findex -lang-c
        !          2691: @findex -lang-c++
        !          2692: @findex -lang-objc
        !          2693: @findex -lang-objc++
        !          2694: @findex #import
        !          2695: Specify the source language.  @samp{-lang-c++} makes the preprocessor
        !          2696: handle C++ comment syntax (comments may begin with @samp{//}, in which
        !          2697: case they end at end of line), and includes extra default include
        !          2698: directories for C++; and @samp{-lang-objc} enables the Objective C
        !          2699: @samp{#import} command.  @samp{-lang-c} explicitly turns off both of
        !          2700: these extensions, and @samp{-lang-objc++} enables both.
        !          2701: 
        !          2702: These options are generated by the compiler driver @code{gcc}, but not
        !          2703: passed from the @samp{gcc} command line.
        !          2704: 
        !          2705: @item -lint
        !          2706: Look for commands to the program checker @code{lint} embedded in
        !          2707: comments, and emit them preceded by @samp{#pragma lint}.  For example,
        !          2708: the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint
        !          2709: NOTREACHED}.
        !          2710: 
        !          2711: This option is available only when you call @code{cpp} directly;
        !          2712: @code{gcc} will not pass it from its command line.
        !          2713: 
        !          2714: @item -$
        !          2715: @findex -$
        !          2716: Forbid the use of @samp{$} in identifiers.  This is required for ANSI
        !          2717: conformance.  @code{gcc} automatically supplies this option to the
        !          2718: preprocessor if you specify @samp{-ansi}, but @code{gcc} doesn't
        !          2719: recognize the @samp{-$} option itself---to use it without the other
        !          2720: effects of @samp{-ansi}, you must call the preprocessor directly.
        !          2721: 
        !          2722: @end table
        !          2723: 
        !          2724: @node Concept Index, Index, Invocation, Top
        !          2725: @unnumbered Concept Index
        !          2726: @printindex cp
        !          2727: 
        !          2728: @node Index,, Concept Index, Top
        !          2729: @unnumbered Index of Commands, Macros and Options
        !          2730: @printindex fn
        !          2731: 
        !          2732: @contents
        !          2733: @bye

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