Return to cpp.info-1 CVS log

Up to [Apple XNU] / GNUtools / cc

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

1.1     ! root        1: This is Info file cpp.info, produced by Makeinfo-1.54 from the input
        !             2: file cpp.texi.
        !             3: 
        !             4:    This file documents the GNU C Preprocessor.
        !             5: 
        !             6:    Copyright 1987, 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
        !             7: 
        !             8:    Permission is granted to make and distribute verbatim copies of this
        !             9: manual provided the copyright notice and this permission notice are
        !            10: preserved on all copies.
        !            11: 
        !            12:    Permission is granted to copy and distribute modified versions of
        !            13: this manual under the conditions for verbatim copying, provided also
        !            14: that the entire resulting derived work is distributed under the terms
        !            15: of a permission notice identical to this one.
        !            16: 
        !            17:    Permission is granted to copy and distribute translations of this
        !            18: manual into another language, under the above conditions for modified
        !            19: versions.
        !            20: 
        !            21: 
        !            22: File: cpp.info,  Node: Top,  Next: Global Actions,  Up: (DIR)
        !            23: 
        !            24: The C Preprocessor
        !            25: ******************
        !            26: 
        !            27:    The C preprocessor is a "macro processor" that is used automatically
        !            28: by the C compiler to transform your program before actual compilation.
        !            29: It is called a macro processor because it allows you to define "macros",
        !            30: which are brief abbreviations for longer constructs.
        !            31: 
        !            32:    The C preprocessor provides four separate facilities that you can
        !            33: use as you see fit:
        !            34: 
        !            35:    * Inclusion of header files.  These are files of declarations that
        !            36:      can be substituted into your program.
        !            37: 
        !            38:    * Macro expansion.  You can define "macros", which are abbreviations
        !            39:      for arbitrary fragments of C code, and then the C preprocessor will
        !            40:      replace the macros with their definitions throughout the program.
        !            41: 
        !            42:    * Conditional compilation.  Using special preprocessor commands, you
        !            43:      can include or exclude parts of the program according to various
        !            44:      conditions.
        !            45: 
        !            46:    * Line control.  If you use a program to combine or rearrange source
        !            47:      files into an intermediate file which is then compiled, you can
        !            48:      use line control to inform the compiler of where each source line
        !            49:      originally came from.
        !            50: 
        !            51:    C preprocessors vary in some details.  This manual discusses the GNU
        !            52: C preprocessor, the C Compatible Compiler Preprocessor.  The GNU C
        !            53: preprocessor provides a superset of the features of ANSI Standard C.
        !            54: 
        !            55:    ANSI Standard C requires the rejection of many harmless constructs
        !            56: commonly used by today's C programs.  Such incompatibility would be
        !            57: inconvenient for users, so the GNU C preprocessor is configured to
        !            58: accept these constructs by default.  Strictly speaking, to get ANSI
        !            59: Standard C, you must use the options `-trigraphs', `-undef' and
        !            60: `-pedantic', but in practice the consequences of having strict ANSI
        !            61: Standard C make it undesirable to do this.  *Note Invocation::.
        !            62: 
        !            63: * Menu:
        !            64: 
        !            65: * Global Actions::    Actions made uniformly on all input files.
        !            66: * Commands::          General syntax of preprocessor commands.
        !            67: * Header Files::      How and why to use header files.
        !            68: * Macros::            How and why to use macros.
        !            69: * Conditionals::      How and why to use conditionals.
        !            70: * Combining Sources:: Use of line control when you combine source files.
        !            71: * Other Commands::    Miscellaneous preprocessor commands.
        !            72: * Output::            Format of output from the C preprocessor.
        !            73: * Invocation::        How to invoke the preprocessor; command options.
        !            74: * Concept Index::     Index of concepts and terms.
        !            75: * Index::             Index of commands, predefined macros and options.
        !            76: 
        !            77: 
        !            78: File: cpp.info,  Node: Global Actions,  Next: Commands,  Prev: Top,  Up: Top
        !            79: 
        !            80: Transformations Made Globally
        !            81: =============================
        !            82: 
        !            83:    Most C preprocessor features are inactive unless you give specific
        !            84: commands to request their use.  (Preprocessor commands are lines
        !            85: starting with `#'; *note Commands::.).  But there are three
        !            86: transformations that the preprocessor always makes on all the input it
        !            87: receives, even in the absence of commands.
        !            88: 
        !            89:    * All C comments are replaced with single spaces.
        !            90: 
        !            91:    * Backslash-Newline sequences are deleted, no matter where.  This
        !            92:      feature allows you to break long lines for cosmetic purposes
        !            93:      without changing their meaning.
        !            94: 
        !            95:    * Predefined macro names are replaced with their expansions (*note
        !            96:      Predefined::.).
        !            97: 
        !            98:    The first two transformations are done *before* nearly all other
        !            99: parsing and before preprocessor commands are recognized.  Thus, for
        !           100: example, you can split a line cosmetically with Backslash-Newline
        !           101: anywhere (except when trigraphs are in use; see below).
        !           102: 
        !           103:      /*
        !           104:      */ # /*
        !           105:      */ defi\
        !           106:      ne FO\
        !           107:      O 10\
        !           108:      20
        !           109: 
        !           110: is equivalent into `#define FOO 1020'.  You can split even an escape
        !           111: sequence with Backslash-Newline.  For example, you can split `"foo\bar"'
        !           112: between the `\' and the `b' to get
        !           113: 
        !           114:      "foo\\
        !           115:      bar"
        !           116: 
        !           117: This behavior is unclean: in all other contexts, a Backslash can be
        !           118: inserted in a string constant as an ordinary character by writing a
        !           119: double Backslash, and this creates an exception.  But the ANSI C
        !           120: standard requires it.  (Strict ANSI C does not allow Newlines in string
        !           121: constants, so they do not consider this a problem.)
        !           122: 
        !           123:    But there are a few exceptions to all three transformations.
        !           124: 
        !           125:    * C comments and predefined macro names are not recognized inside a
        !           126:      `#include' command in which the file name is delimited with `<'
        !           127:      and `>'.
        !           128: 
        !           129:    * C comments and predefined macro names are never recognized within a
        !           130:      character or string constant.  (Strictly speaking, this is the
        !           131:      rule, not an exception, but it is worth noting here anyway.)
        !           132: 
        !           133:    * Backslash-Newline may not safely be used within an ANSI "trigraph".
        !           134:      Trigraphs are converted before Backslash-Newline is deleted.  If
        !           135:      you write what looks like a trigraph with a Backslash-Newline
        !           136:      inside, the Backslash-Newline is deleted as usual, but it is then
        !           137:      too late to recognize the trigraph.
        !           138: 
        !           139:      This exception is relevant only if you use the `-trigraphs' option
        !           140:      to enable trigraph processing.  *Note Invocation::.
        !           141: 
        !           142: 
        !           143: File: cpp.info,  Node: Commands,  Next: Header Files,  Prev: Global Actions,  Up: Top
        !           144: 
        !           145: Preprocessor Commands
        !           146: =====================
        !           147: 
        !           148:    Most preprocessor features are active only if you use preprocessor
        !           149: commands to request their use.
        !           150: 
        !           151:    Preprocessor commands are lines in your program that start with `#'.
        !           152: The `#' is followed by an identifier that is the "command name".  For
        !           153: example, `#define' is the command that defines a macro.  Whitespace is
        !           154: also allowed before and after the `#'.
        !           155: 
        !           156:    The set of valid command names is fixed.  Programs cannot define new
        !           157: preprocessor commands.
        !           158: 
        !           159:    Some command names require arguments; these make up the rest of the
        !           160: command line and must be separated from the command name by whitespace.
        !           161: For example, `#define' must be followed by a macro name and the
        !           162: intended expansion of the macro.
        !           163: 
        !           164:    A preprocessor command cannot be more than one line in normal
        !           165: circumstances.  It may be split cosmetically with Backslash-Newline,
        !           166: but that has no effect on its meaning.  Comments containing Newlines
        !           167: can also divide the command into multiple lines, but the comments are
        !           168: changed to Spaces before the command is interpreted.  The only way a
        !           169: significant Newline can occur in a preprocessor command is within a
        !           170: string constant or character constant.  Note that most C compilers that
        !           171: might be applied to the output from the preprocessor do not accept
        !           172: string or character constants containing Newlines.
        !           173: 
        !           174:    The `#' and the command name cannot come from a macro expansion.  For
        !           175: example, if `foo' is defined as a macro expanding to `define', that
        !           176: does not make `#foo' a valid preprocessor command.
        !           177: 
        !           178: 
        !           179: File: cpp.info,  Node: Header Files,  Next: Macros,  Prev: Commands,  Up: Top
        !           180: 
        !           181: Header Files
        !           182: ============
        !           183: 
        !           184:    A header file is a file containing C declarations and macro
        !           185: definitions (*note Macros::.) to be shared between several source
        !           186: files.  You request the use of a header file in your program with the C
        !           187: preprocessor command `#include'.
        !           188: 
        !           189: * Menu:
        !           190: 
        !           191: * Header Uses::         What header files are used for.
        !           192: * Include Syntax::      How to write `#include' commands.
        !           193: * Include Operation::   What `#include' does.
        !           194: * Once-Only::          Preventing multiple inclusion of one header file.
        !           195: * Inheritance::         Including one header file in another header file.
        !           196: 
        !           197: 
        !           198: File: cpp.info,  Node: Header Uses,  Next: Include Syntax,  Prev: Header Files,  Up: Header Files
        !           199: 
        !           200: Uses of Header Files
        !           201: --------------------
        !           202: 
        !           203:    Header files serve two kinds of purposes.
        !           204: 
        !           205:    * System header files declare the interfaces to parts of the
        !           206:      operating system.  You include them in your program to supply the
        !           207:      definitions and declarations you need to invoke system calls and
        !           208:      libraries.
        !           209: 
        !           210:    * Your own header files contain declarations for interfaces between
        !           211:      the source files of your program.  Each time you have a group of
        !           212:      related declarations and macro definitions all or most of which
        !           213:      are needed in several different source files, it is a good idea to
        !           214:      create a header file for them.
        !           215: 
        !           216:    Including a header file produces the same results in C compilation as
        !           217: copying the header file into each source file that needs it.  But such
        !           218: copying would be time-consuming and error-prone.  With a header file,
        !           219: the related declarations appear in only one place.  If they need to be
        !           220: changed, they can be changed in one place, and programs that include
        !           221: the header file will automatically use the new version when next
        !           222: recompiled.  The header file eliminates the labor of finding and
        !           223: changing all the copies as well as the risk that a failure to find one
        !           224: copy will result in inconsistencies within a program.
        !           225: 
        !           226:    The usual convention is to give header files names that end with
        !           227: `.h'.
        !           228: 
        !           229: 
        !           230: File: cpp.info,  Node: Include Syntax,  Next: Include Operation,  Prev: Header Uses,  Up: Header Files
        !           231: 
        !           232: The `#include' Command
        !           233: ----------------------
        !           234: 
        !           235:    Both user and system header files are included using the preprocessor
        !           236: command `#include'.  It has three variants:
        !           237: 
        !           238: `#include <FILE>'
        !           239:      This variant is used for system header files.  It searches for a
        !           240:      file named FILE in a list of directories specified by you, then in
        !           241:      a standard list of system directories.  You specify directories to
        !           242:      search for header files with the command option `-I' (*note
        !           243:      Invocation::.).  The option `-nostdinc' inhibits searching the
        !           244:      standard system directories; in this case only the directories you
        !           245:      specify are searched.
        !           246: 
        !           247:      The parsing of this form of `#include' is slightly special because
        !           248:      comments are not recognized within the `<...>'.  Thus, in
        !           249:      `#include <x/*y>' the `/*' does not start a comment and the
        !           250:      command specifies inclusion of a system header file named `x/*y'.
        !           251:      Of course, a header file with such a name is unlikely to exist on
        !           252:      Unix, where shell wildcard features would make it hard to
        !           253:      manipulate.
        !           254: 
        !           255:      The argument FILE may not contain a `>' character.  It may,
        !           256:      however, contain a `<' character.
        !           257: 
        !           258: `#include "FILE"'
        !           259:      This variant is used for header files of your own program.  It
        !           260:      searches for a file named FILE first in the current directory,
        !           261:      then in the same directories used for system header files.  The
        !           262:      current directory is the directory of the current input file.  It
        !           263:      is tried first because it is presumed to be the location of the
        !           264:      files that the current input file refers to.  (If the `-I-' option
        !           265:      is used, the special treatment of the current directory is
        !           266:      inhibited.)
        !           267: 
        !           268:      The argument FILE may not contain `"' characters.  If backslashes
        !           269:      occur within FILE, they are considered ordinary text characters,
        !           270:      not escape characters.  None of the character escape sequences
        !           271:      appropriate to string constants in C are processed.  Thus,
        !           272:      `#include "x\n\\y"' specifies a filename containing three
        !           273:      backslashes.  It is not clear why this behavior is ever useful, but
        !           274:      the ANSI standard specifies it.
        !           275: 
        !           276: `#include ANYTHING ELSE'
        !           277:      This variant is called a "computed #include".  Any `#include'
        !           278:      command whose argument does not fit the above two forms is a
        !           279:      computed include.  The text ANYTHING ELSE is checked for macro
        !           280:      calls, which are expanded (*note Macros::.).  When this is done,
        !           281:      the result must fit one of the above two variants--in particular,
        !           282:      the expanded text must in the end be surrounded by either quotes
        !           283:      or angle braces.
        !           284: 
        !           285:      This feature allows you to define a macro which controls the file
        !           286:      name to be used at a later point in the program.  One application
        !           287:      of this is to allow a site-configuration file for your program to
        !           288:      specify the names of the system include files to be used.  This
        !           289:      can help in porting the program to various operating systems in
        !           290:      which the necessary system header files are found in different
        !           291:      places.
        !           292: 
        !           293: 
        !           294: File: cpp.info,  Node: Include Operation,  Next: Once-Only,  Prev: Include Syntax,  Up: Header Files
        !           295: 
        !           296: How `#include' Works
        !           297: --------------------
        !           298: 
        !           299:    The `#include' command works by directing the C preprocessor to scan
        !           300: the specified file as input before continuing with the rest of the
        !           301: current file.  The output from the preprocessor contains the output
        !           302: already generated, followed by the output resulting from the included
        !           303: file, followed by the output that comes from the text after the
        !           304: `#include' command.  For example, given two files as follows:
        !           305: 
        !           306:      /* File program.c */
        !           307:      int x;
        !           308:      #include "header.h"
        !           309:      
        !           310:      main ()
        !           311:      {
        !           312:        printf (test ());
        !           313:      }
        !           314:      
        !           315:      
        !           316:      /* File header.h */
        !           317:      char *test ();
        !           318: 
        !           319: the output generated by the C preprocessor for `program.c' as input
        !           320: would be
        !           321: 
        !           322:      int x;
        !           323:      char *test ();
        !           324:      
        !           325:      main ()
        !           326:      {
        !           327:        printf (test ());
        !           328:      }
        !           329: 
        !           330:    Included files are not limited to declarations and macro
        !           331: definitions; those are merely the typical uses.  Any fragment of a C
        !           332: program can be included from another file.  The include file could even
        !           333: contain the beginning of a statement that is concluded in the
        !           334: containing file, or the end of a statement that was started in the
        !           335: including file.  However, a comment or a string or character constant
        !           336: may not start in the included file and finish in the including file.
        !           337: An unterminated comment, string constant or character constant in an
        !           338: included file is considered to end (with an error message) at the end
        !           339: of the file.
        !           340: 
        !           341:    The line following the `#include' command is always treated as a
        !           342: separate line by the C preprocessor even if the included file lacks a
        !           343: final newline.
        !           344: 
        !           345: 
        !           346: File: cpp.info,  Node: Once-Only,  Next: Inheritance,  Prev: Include Operation,  Up: Header Files
        !           347: 
        !           348: Once-Only Include Files
        !           349: -----------------------
        !           350: 
        !           351:    Very often, one header file includes another.  It can easily result
        !           352: that a certain header file is included more than once.  This may lead
        !           353: to errors, if the header file defines structure types or typedefs, and
        !           354: is certainly wasteful.  Therefore, we often wish to prevent multiple
        !           355: inclusion of a header file.
        !           356: 
        !           357:    The standard way to do this is to enclose the entire real contents
        !           358: of the file in a conditional, like this:
        !           359: 
        !           360:      #ifndef __FILE_FOO_SEEN__
        !           361:      #define __FILE_FOO_SEEN__
        !           362:      
        !           363:      THE ENTIRE FILE
        !           364:      
        !           365:      #endif /* __FILE_FOO_SEEN__ */
        !           366: 
        !           367:    The macro `__FILE_FOO_SEEN__' indicates that the file has been
        !           368: included once already; its name should begin with `__' to avoid
        !           369: conflicts with user programs, and it should contain the name of the file
        !           370: and some additional text, to avoid conflicts with other header files.
        !           371: 
        !           372:    The GNU C preprocessor is programmed to notice when a header file
        !           373: uses this particular construct and handle it efficiently.  If a header
        !           374: file is contained entirely in a `#ifndef' conditional, then it records
        !           375: that fact.  If a subsequent `#include' specifies the same file, and the
        !           376: macro in the `#ifndef' is already defined, then the file is entirely
        !           377: skipped, without even reading it.
        !           378: 
        !           379:    There is also an explicit command to tell the preprocessor that it
        !           380: need not include a file more than once.  This is called `#pragma once',
        !           381: and was used *in addition to* the `#ifndef' conditional around the
        !           382: contents of the header file.  `#pragma once' is now obsolete and should
        !           383: not be used at all.
        !           384: 
        !           385:    In the Objective C language, there is a variant of `#include' called
        !           386: `#import' which includes a file, but does so at most once.  If you use
        !           387: `#import' *instead of* `#include', then you don't need the conditionals
        !           388: inside the header file to prevent multiple execution of the contents.
        !           389: 
        !           390:    `#import' is obsolete because it is not a well-designed feature.  It
        !           391: requires the users of a header file--the applications programmers--to
        !           392: know that a certain header file should only be included once.  It is
        !           393: much better for the header file's implementor to write the file so that
        !           394: users don't need to know this.  Using `#ifndef' accomplishes this goal.
        !           395: 
        !           396: 
        !           397: File: cpp.info,  Node: Inheritance,  Prev: Once-Only,  Up: Header Files
        !           398: 
        !           399: Inheritance and Header Files
        !           400: ============================
        !           401: 
        !           402:    "Inheritance" is what happens when one object or file derives some
        !           403: of its contents by virtual copying from another object or file.  In the
        !           404: case of C header files, inheritance means that one header file includes
        !           405: another header file and then replaces or adds something.
        !           406: 
        !           407:    If the inheriting header file and the base header file have different
        !           408: names, then inheritance is straightforward: simply write `#include
        !           409: "BASE"' in the inheriting file.
        !           410: 
        !           411:    Sometimes it is necessary to give the inheriting file the same name
        !           412: as the base file.  This is less straightforward.
        !           413: 
        !           414:    For example, suppose an application program uses the system header
        !           415: file `sys/signal.h', but the version of `/usr/include/sys/signal.h' on
        !           416: a particular system doesn't do what the application program expects.
        !           417: It might be convenient to define a "local" version, perhaps under the
        !           418: name `/usr/local/include/sys/signal.h', to override or add to the one
        !           419: supplied by the system.
        !           420: 
        !           421:    You can do this by using the option `-I.' for compilation, and
        !           422: writing a file `sys/signal.h' that does what the application program
        !           423: expects.  But making this file include the standard `sys/signal.h' is
        !           424: not so easy--writing `#include <sys/signal.h>' in that file doesn't
        !           425: work, because it includes your own version of the file, not the
        !           426: standard system version.  Used in that file itself, this leads to an
        !           427: infinite recursion and a fatal error in compilation.
        !           428: 
        !           429:    `#include </usr/include/sys/signal.h>' would find the proper file,
        !           430: but that is not clean, since it makes an assumption about where the
        !           431: system header file is found.  This is bad for maintenance, since it
        !           432: means that any change in where the system's header files are kept
        !           433: requires a change somewhere else.
        !           434: 
        !           435:    The clean way to solve this problem is to use `#include_next', which
        !           436: means, "Include the *next* file with this name."  This command works
        !           437: like `#include' except in searching for the specified file: it starts
        !           438: searching the list of header file directories *after* the directory in
        !           439: which the current file was found.
        !           440: 
        !           441:    Suppose you specify `-I /usr/local/include', and the list of
        !           442: directories to search also includes `/usr/include'; and suppose that
        !           443: both directories contain a file named `sys/signal.h'.  Ordinary
        !           444: `#include <sys/signal.h>' finds the file under `/usr/local/include'.
        !           445: If that file contains `#include_next <sys/signal.h>', it starts
        !           446: searching after that directory, and finds the file in `/usr/include'.
        !           447: 
        !           448: 
        !           449: File: cpp.info,  Node: Macros,  Next: Conditionals,  Prev: Header Files,  Up: Top
        !           450: 
        !           451: Macros
        !           452: ======
        !           453: 
        !           454:    A macro is a sort of abbreviation which you can define once and then
        !           455: use later.  There are many complicated features associated with macros
        !           456: in the C preprocessor.
        !           457: 
        !           458: * Menu:
        !           459: 
        !           460: * Simple Macros::    Macros that always expand the same way.
        !           461: * Argument Macros::  Macros that accept arguments that are substituted
        !           462:                        into the macro expansion.
        !           463: * Predefined::       Predefined macros that are always available.
        !           464: * Stringification::  Macro arguments converted into string constants.
        !           465: * Concatenation::    Building tokens from parts taken from macro arguments.
        !           466: * Undefining::       Cancelling a macro's definition.
        !           467: * Redefining::       Changing a macro's definition.
        !           468: * Macro Pitfalls::   Macros can confuse the unwary.  Here we explain
        !           469:                        several common problems and strange features.
        !           470: 
        !           471: 
        !           472: File: cpp.info,  Node: Simple Macros,  Next: Argument Macros,  Prev: Macros,  Up: Macros
        !           473: 
        !           474: Simple Macros
        !           475: -------------
        !           476: 
        !           477:    A "simple macro" is a kind of abbreviation.  It is a name which
        !           478: stands for a fragment of code.  Some people refer to these as "manifest
        !           479: constants".
        !           480: 
        !           481:    Before you can use a macro, you must "define" it explicitly with the
        !           482: `#define' command.  `#define' is followed by the name of the macro and
        !           483: then the code it should be an abbreviation for.  For example,
        !           484: 
        !           485:      #define BUFFER_SIZE 1020
        !           486: 
        !           487: defines a macro named `BUFFER_SIZE' as an abbreviation for the text
        !           488: `1020'.  Therefore, if somewhere after this `#define' command there
        !           489: comes a C statement of the form
        !           490: 
        !           491:      foo = (char *) xmalloc (BUFFER_SIZE);
        !           492: 
        !           493: then the C preprocessor will recognize and "expand" the macro
        !           494: `BUFFER_SIZE', resulting in
        !           495: 
        !           496:      foo = (char *) xmalloc (1020);
        !           497: 
        !           498: the definition must be a single line; however, it may not end in the
        !           499: middle of a multi-line string constant or character constant.
        !           500: 
        !           501:    The use of all upper case for macro names is a standard convention.
        !           502: Programs are easier to read when it is possible to tell at a glance
        !           503: which names are macros.
        !           504: 
        !           505:    Normally, a macro definition must be a single line, like all C
        !           506: preprocessor commands.  (You can split a long macro definition
        !           507: cosmetically with Backslash-Newline.)  There is one exception: Newlines
        !           508: can be included in the macro definition if within a string or character
        !           509: constant.  By the same token, it is not possible for a macro definition
        !           510: to contain an unbalanced quote character; the definition automatically
        !           511: extends to include the matching quote character that ends the string or
        !           512: character constant.  Comments within a macro definition may contain
        !           513: Newlines, which make no difference since the comments are entirely
        !           514: replaced with Spaces regardless of their contents.
        !           515: 
        !           516:    Aside from the above, there is no restriction on what can go in a
        !           517: macro body.  Parentheses need not balance.  The body need not resemble
        !           518: valid C code.  (Of course, you might get error messages from the C
        !           519: compiler when you use the macro.)
        !           520: 
        !           521:    The C preprocessor scans your program sequentially, so macro
        !           522: definitions take effect at the place you write them.  Therefore, the
        !           523: following input to the C preprocessor
        !           524: 
        !           525:      foo = X;
        !           526:      #define X 4
        !           527:      bar = X;
        !           528: 
        !           529: produces as output
        !           530: 
        !           531:      foo = X;
        !           532:      
        !           533:      bar = 4;
        !           534: 
        !           535:    After the preprocessor expands a macro name, the macro's definition
        !           536: body is appended to the front of the remaining input, and the check for
        !           537: macro calls continues.  Therefore, the macro body can contain calls to
        !           538: other macros.  For example, after
        !           539: 
        !           540:      #define BUFSIZE 1020
        !           541:      #define TABLESIZE BUFSIZE
        !           542: 
        !           543: the name `TABLESIZE' when used in the program would go through two
        !           544: stages of expansion, resulting ultimately in `1020'.
        !           545: 
        !           546:    This is not at all the same as defining `TABLESIZE' to be `1020'.
        !           547: The `#define' for `TABLESIZE' uses exactly the body you specify--in
        !           548: this case, `BUFSIZE'--and does not check to see whether it too is the
        !           549: name of a macro.  It's only when you *use* `TABLESIZE' that the result
        !           550: of its expansion is checked for more macro names.  *Note Cascaded
        !           551: Macros::.
        !           552: 
        !           553: 
        !           554: File: cpp.info,  Node: Argument Macros,  Next: Predefined,  Prev: Simple Macros,  Up: Macros
        !           555: 
        !           556: Macros with Arguments
        !           557: ---------------------
        !           558: 
        !           559:    A simple macro always stands for exactly the same text, each time it
        !           560: is used.  Macros can be more flexible when they accept "arguments".
        !           561: Arguments are fragments of code that you supply each time the macro is
        !           562: used.  These fragments are included in the expansion of the macro
        !           563: according to the directions in the macro definition.
        !           564: 
        !           565:    To define a macro that uses arguments, you write a `#define' command
        !           566: with a list of "argument names" in parentheses after the name of the
        !           567: macro.  The argument names may be any valid C identifiers, separated by
        !           568: commas and optionally whitespace.  The open-parenthesis must follow the
        !           569: macro name immediately, with no space in between.
        !           570: 
        !           571:    For example, here is a macro that computes the minimum of two numeric
        !           572: values, as it is defined in many C programs:
        !           573: 
        !           574:      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
        !           575: 
        !           576: (This is not the best way to define a "minimum" macro in GNU C.  *Note
        !           577: Side Effects::, for more information.)
        !           578: 
        !           579:    To use a macro that expects arguments, you write the name of the
        !           580: macro followed by a list of "actual arguments" in parentheses,
        !           581: separated by commas.  The number of actual arguments you give must
        !           582: match the number of arguments the macro expects.   Examples of use of
        !           583: the macro `min' include `min (1, 2)' and `min (x + 28, *p)'.
        !           584: 
        !           585:    The expansion text of the macro depends on the arguments you use.
        !           586: Each of the argument names of the macro is replaced, throughout the
        !           587: macro definition, with the corresponding actual argument.  Using the
        !           588: same macro `min' defined above, `min (1, 2)' expands into
        !           589: 
        !           590:      ((1) < (2) ? (1) : (2))
        !           591: 
        !           592: where `1' has been substituted for `X' and `2' for `Y'.
        !           593: 
        !           594:    Likewise, `min (x + 28, *p)' expands into
        !           595: 
        !           596:      ((x + 28) < (*p) ? (x + 28) : (*p))
        !           597: 
        !           598:    Parentheses in the actual arguments must balance; a comma within
        !           599: parentheses does not end an argument.  However, there is no requirement
        !           600: for brackets or braces to balance, and they do not prevent a comma from
        !           601: separating arguments.  Thus,
        !           602: 
        !           603:      macro (array[x = y, x + 1])
        !           604: 
        !           605: passes two arguments to `macro': `array[x = y' and `x + 1]'.  If you
        !           606: want to supply `array[x = y, x + 1]' as an argument, you must write it
        !           607: as `array[(x = y, x + 1)]', which is equivalent C code.
        !           608: 
        !           609:    After the actual arguments are substituted into the macro body, the
        !           610: entire result is appended to the front of the remaining input, and the
        !           611: check for macro calls continues.  Therefore, the actual arguments can
        !           612: contain calls to other macros, either with or without arguments, or
        !           613: even to the same macro.  The macro body can also contain calls to other
        !           614: macros.  For example, `min (min (a, b), c)' expands into this text:
        !           615: 
        !           616:      ((((a) < (b) ? (a) : (b))) < (c)
        !           617:       ? (((a) < (b) ? (a) : (b)))
        !           618:       : (c))
        !           619: 
        !           620: (Line breaks shown here for clarity would not actually be generated.)
        !           621: 
        !           622:    If a macro `foo' takes one argument, and you want to supply an empty
        !           623: argument, you must write at least some whitespace between the
        !           624: parentheses, like this: `foo ( )'.  Just `foo ()' is providing no
        !           625: arguments, which is an error if `foo' expects an argument.  But `foo0
        !           626: ()' is the correct way to call a macro defined to take zero arguments,
        !           627: like this:
        !           628: 
        !           629:      #define foo0() ...
        !           630: 
        !           631:    If you use the macro name followed by something other than an
        !           632: open-parenthesis (after ignoring any spaces, tabs and comments that
        !           633: follow), it is not a call to the macro, and the preprocessor does not
        !           634: change what you have written.  Therefore, it is possible for the same
        !           635: name to be a variable or function in your program as well as a macro,
        !           636: and you can choose in each instance whether to refer to the macro (if
        !           637: an actual argument list follows) or the variable or function (if an
        !           638: argument list does not follow).
        !           639: 
        !           640:    Such dual use of one name could be confusing and should be avoided
        !           641: except when the two meanings are effectively synonymous: that is, when
        !           642: the name is both a macro and a function and the two have similar
        !           643: effects.  You can think of the name simply as a function; use of the
        !           644: name for purposes other than calling it (such as, to take the address)
        !           645: will refer to the function, while calls will expand the macro and
        !           646: generate better but equivalent code.  For example, you can use a
        !           647: function named `min' in the same source file that defines the macro.
        !           648: If you write `&min' with no argument list, you refer to the function.
        !           649: If you write `min (x, bb)', with an argument list, the macro is
        !           650: expanded.  If you write `(min) (a, bb)', where the name `min' is not
        !           651: followed by an open-parenthesis, the macro is not expanded, so you wind
        !           652: up with a call to the function `min'.
        !           653: 
        !           654:    You may not define the same name as both a simple macro and a macro
        !           655: with arguments.
        !           656: 
        !           657:    In the definition of a macro with arguments, the list of argument
        !           658: names must follow the macro name immediately with no space in between.
        !           659: If there is a space after the macro name, the macro is defined as
        !           660: taking no arguments, and all the rest of the line is taken to be the
        !           661: expansion.  The reason for this is that it is often useful to define a
        !           662: macro that takes no arguments and whose definition begins with an
        !           663: identifier in parentheses.  This rule about spaces makes it possible
        !           664: for you to do either this:
        !           665: 
        !           666:      #define FOO(x) - 1 / (x)
        !           667: 
        !           668: (which defines `FOO' to take an argument and expand into minus the
        !           669: reciprocal of that argument) or this:
        !           670: 
        !           671:      #define BAR (x) - 1 / (x)
        !           672: 
        !           673: (which defines `BAR' to take no argument and always expand into `(x) -
        !           674: 1 / (x)').
        !           675: 
        !           676:    Note that the *uses* of a macro with arguments can have spaces before
        !           677: the left parenthesis; it's the *definition* where it matters whether
        !           678: there is a space.
        !           679: 
        !           680: 
        !           681: File: cpp.info,  Node: Predefined,  Next: Stringification,  Prev: Argument Macros,  Up: Macros
        !           682: 
        !           683: Predefined Macros
        !           684: -----------------
        !           685: 
        !           686:    Several simple macros are predefined.  You can use them without
        !           687: giving definitions for them.  They fall into two classes: standard
        !           688: macros and system-specific macros.
        !           689: 
        !           690: * Menu:
        !           691: 
        !           692: * Standard Predefined::     Standard predefined macros.
        !           693: * Nonstandard Predefined::  Nonstandard predefined macros.
        !           694: 
        !           695: 
        !           696: File: cpp.info,  Node: Standard Predefined,  Next: Nonstandard Predefined,  Prev: Predefined,  Up: Predefined
        !           697: 
        !           698: Standard Predefined Macros
        !           699: ..........................
        !           700: 
        !           701:    The standard predefined macros are available with the same meanings
        !           702: regardless of the machine or operating system on which you are using
        !           703: GNU C.  Their names all start and end with double underscores.  Those
        !           704: preceding `__GNUC__' in this table are standardized by ANSI C; the rest
        !           705: are GNU C extensions.
        !           706: 
        !           707: `__FILE__'
        !           708:      This macro expands to the name of the current input file, in the
        !           709:      form of a C string constant.  The precise name returned is the one
        !           710:      that was specified in `#include' or as the input file name
        !           711:      argument.
        !           712: 
        !           713: `__LINE__'
        !           714:      This macro expands to the current input line number, in the form
        !           715:      of a decimal integer constant.  While we call it a predefined
        !           716:      macro, it's a pretty strange macro, since its "definition" changes
        !           717:      with each new line of source code.
        !           718: 
        !           719:      This and `__FILE__' are useful in generating an error message to
        !           720:      report an inconsistency detected by the program; the message can
        !           721:      state the source line at which the inconsistency was detected.
        !           722:      For example,
        !           723: 
        !           724:           fprintf (stderr, "Internal error: "
        !           725:                         "negative string length "
        !           726:                            "%d at %s, line %d.",
        !           727:                    length, __FILE__, __LINE__);
        !           728: 
        !           729:      A `#include' command changes the expansions of `__FILE__' and
        !           730:      `__LINE__' to correspond to the included file.  At the end of that
        !           731:      file, when processing resumes on the input file that contained the
        !           732:      `#include' command, the expansions of `__FILE__' and `__LINE__'
        !           733:      revert to the values they had before the `#include' (but
        !           734:      `__LINE__' is then incremented by one as processing moves to the
        !           735:      line after the `#include').
        !           736: 
        !           737:      The expansions of both `__FILE__' and `__LINE__' are altered if a
        !           738:      `#line' command is used.  *Note Combining Sources::.
        !           739: 
        !           740: `__INCLUDE_LEVEL__'
        !           741:      This macro expands to a decimal integer constant that represents
        !           742:      the depth of nesting in include files.  The value of this macro is
        !           743:      incremented on every `#include' command and decremented at every
        !           744:      end of file.
        !           745: 
        !           746: `__DATE__'
        !           747:      This macro expands to a string constant that describes the date on
        !           748:      which the preprocessor is being run.  The string constant contains
        !           749:      eleven characters and looks like `"Jan 29 1987"' or `"Apr 1 1905"'.
        !           750: 
        !           751: `__TIME__'
        !           752:      This macro expands to a string constant that describes the time at
        !           753:      which the preprocessor is being run.  The string constant contains
        !           754:      eight characters and looks like `"23:59:01"'.
        !           755: 
        !           756: `__STDC__'
        !           757:      This macro expands to the constant 1, to signify that this is ANSI
        !           758:      Standard C.  (Whether that is actually true depends on what C
        !           759:      compiler will operate on the output from the preprocessor.)
        !           760: 
        !           761: `__GNUC__'
        !           762:      This macro is defined if and only if this is GNU C.  This macro is
        !           763:      defined only when the entire GNU C compiler is in use; if you
        !           764:      invoke the preprocessor directly, `__GNUC__' is undefined.
        !           765: 
        !           766: `__GNUG__'
        !           767:      The GNU C compiler defines this when the compilation language is
        !           768:      C++; use `__GNUG__' to distinguish between GNU C and GNU C++.
        !           769: 
        !           770: `__cplusplus'
        !           771:      The draft ANSI standard for C++ used to require predefining this
        !           772:      variable.  Though it is no longer required, GNU C++ continues to
        !           773:      define it, as do other popular C++ compilers.  You can use
        !           774:      `__cplusplus' to test whether a header is compiled by a C compiler
        !           775:      or a C++ compiler.
        !           776: 
        !           777: `__STRICT_ANSI__'
        !           778:      This macro is defined if and only if the `-ansi' switch was
        !           779:      specified when GNU C was invoked.  Its definition is the null
        !           780:      string.  This macro exists primarily to direct certain GNU header
        !           781:      files not to define certain traditional Unix constructs which are
        !           782:      incompatible with ANSI C.
        !           783: 
        !           784: `__BASE_FILE__'
        !           785:      This macro expands to the name of the main input file, in the form
        !           786:      of a C string constant.  This is the source file that was specified
        !           787:      as an argument when the C compiler was invoked.
        !           788: 
        !           789: `__VERSION__'
        !           790:      This macro expands to a string which describes the version number
        !           791:      of GNU C.  The string is normally a sequence of decimal numbers
        !           792:      separated by periods, such as `"1.18"'.  The only reasonable use
        !           793:      of this macro is to incorporate it into a string constant.
        !           794: 
        !           795: `__OPTIMIZE__'
        !           796:      This macro is defined in optimizing compilations.  It causes
        !           797:      certain GNU header files to define alternative macro definitions
        !           798:      for some system library functions.  It is unwise to refer to or
        !           799:      test the definition of this macro unless you make very sure that
        !           800:      programs will execute with the same effect regardless.
        !           801: 
        !           802: `__CHAR_UNSIGNED__'
        !           803:      This macro is defined if and only if the data type `char' is
        !           804:      unsigned on the target machine.  It exists to cause the standard
        !           805:      header file `limit.h' to work correctly.  It is bad practice to
        !           806:      refer to this macro yourself; instead, refer to the standard
        !           807:      macros defined in `limit.h'.  The preprocessor uses this macro to
        !           808:      determine whether or not to sign-extend large character constants
        !           809:      written in octal; see *Note The `#if' Command: #if Command.
        !           810: 
        !           811: 
        !           812: File: cpp.info,  Node: Nonstandard Predefined,  Prev: Standard Predefined,  Up: Predefined
        !           813: 
        !           814: Nonstandard Predefined Macros
        !           815: .............................
        !           816: 
        !           817:    The C preprocessor normally has several predefined macros that vary
        !           818: between machines because their purpose is to indicate what type of
        !           819: system and machine is in use.  This manual, being for all systems and
        !           820: machines, cannot tell you exactly what their names are; instead, we
        !           821: offer a list of some typical ones.  You can use `cpp -dM' to see the
        !           822: values of predefined macros; *note Invocation::..
        !           823: 
        !           824:    Some nonstandard predefined macros describe the operating system in
        !           825: use, with more or less specificity.  For example,
        !           826: 
        !           827: `unix'
        !           828:      `unix' is normally predefined on all Unix systems.
        !           829: 
        !           830: `BSD'
        !           831:      `BSD' is predefined on recent versions of Berkeley Unix (perhaps
        !           832:      only in version 4.3).
        !           833: 
        !           834:    Other nonstandard predefined macros describe the kind of CPU, with
        !           835: more or less specificity.  For example,
        !           836: 
        !           837: `vax'
        !           838:      `vax' is predefined on Vax computers.
        !           839: 
        !           840: `mc68000'
        !           841:      `mc68000' is predefined on most computers whose CPU is a Motorola
        !           842:      68000, 68010 or 68020.
        !           843: 
        !           844: `m68k'
        !           845:      `m68k' is also predefined on most computers whose CPU is a 68000,
        !           846:      68010 or 68020; however, some makers use `mc68000' and some use
        !           847:      `m68k'.  Some predefine both names.  What happens in GNU C depends
        !           848:      on the system you are using it on.
        !           849: 
        !           850: `M68020'
        !           851:      `M68020' has been observed to be predefined on some systems that
        !           852:      use 68020 CPUs--in addition to `mc68000' and `m68k', which are
        !           853:      less specific.
        !           854: 
        !           855: `_AM29K'
        !           856: `_AM29000'
        !           857:      Both `_AM29K' and `_AM29000' are predefined for the AMD 29000 CPU
        !           858:      family.
        !           859: 
        !           860: `ns32000'
        !           861:      `ns32000' is predefined on computers which use the National
        !           862:      Semiconductor 32000 series CPU.
        !           863: 
        !           864:    Yet other nonstandard predefined macros describe the manufacturer of
        !           865: the system.  For example,
        !           866: 
        !           867: `sun'
        !           868:      `sun' is predefined on all models of Sun computers.
        !           869: 
        !           870: `pyr'
        !           871:      `pyr' is predefined on all models of Pyramid computers.
        !           872: 
        !           873: `sequent'
        !           874:      `sequent' is predefined on all models of Sequent computers.
        !           875: 
        !           876:    These predefined symbols are not only nonstandard, they are contrary
        !           877: to the ANSI standard because their names do not start with underscores.
        !           878: Therefore, the option `-ansi' inhibits the definition of these symbols.
        !           879: 
        !           880:    This tends to make `-ansi' useless, since many programs depend on the
        !           881: customary nonstandard predefined symbols.  Even system header files
        !           882: check them and will generate incorrect declarations if they do not find
        !           883: the names that are expected.  You might think that the header files
        !           884: supplied for the Uglix computer would not need to test what machine
        !           885: they are running on, because they can simply assume it is the Uglix;
        !           886: but often they do, and they do so using the customary names.  As a
        !           887: result, very few C programs will compile with `-ansi'.  We intend to
        !           888: avoid such problems on the GNU system.
        !           889: 
        !           890:    What, then, should you do in an ANSI C program to test the type of
        !           891: machine it will run on?
        !           892: 
        !           893:    GNU C offers a parallel series of symbols for this purpose, whose
        !           894: names are made from the customary ones by adding `__' at the beginning
        !           895: and end.  Thus, the symbol `__vax__' would be available on a Vax, and
        !           896: so on.
        !           897: 
        !           898:    The set of nonstandard predefined names in the GNU C preprocessor is
        !           899: controlled (when `cpp' is itself compiled) by the macro
        !           900: `CPP_PREDEFINES', which should be a string containing `-D' options,
        !           901: separated by spaces.  For example, on the Sun 3, we use the following
        !           902: definition:
        !           903: 
        !           904:      #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
        !           905: 
        !           906: This macro is usually specified in `tm.h'.
        !           907: 
        !           908: 
        !           909: File: cpp.info,  Node: Stringification,  Next: Concatenation,  Prev: Predefined,  Up: Macros
        !           910: 
        !           911: Stringification
        !           912: ---------------
        !           913: 
        !           914:    "Stringification" means turning a code fragment into a string
        !           915: constant whose contents are the text for the code fragment.  For
        !           916: example, stringifying `foo (z)' results in `"foo (z)"'.
        !           917: 
        !           918:    In the C preprocessor, stringification is an option available when
        !           919: macro arguments are substituted into the macro definition.  In the body
        !           920: of the definition, when an argument name appears, the character `#'
        !           921: before the name specifies stringification of the corresponding actual
        !           922: argument when it is substituted at that point in the definition.  The
        !           923: same argument may be substituted in other places in the definition
        !           924: without stringification if the argument name appears in those places
        !           925: with no `#'.
        !           926: 
        !           927:    Here is an example of a macro definition that uses stringification:
        !           928: 
        !           929:      #define WARN_IF(EXP) \
        !           930:      do { if (EXP) \
        !           931:              fprintf (stderr, "Warning: " #EXP "\n"); } \
        !           932:      while (0)
        !           933: 
        !           934: Here the actual argument for `EXP' is substituted once as given, into
        !           935: the `if' statement, and once as stringified, into the argument to
        !           936: `fprintf'.  The `do' and `while (0)' are a kludge to make it possible
        !           937: to write `WARN_IF (ARG);', which the resemblance of `WARN_IF' to a
        !           938: function would make C programmers want to do; *note Swallow
        !           939: Semicolon::.).
        !           940: 
        !           941:    The stringification feature is limited to transforming one macro
        !           942: argument into one string constant: there is no way to combine the
        !           943: argument with other text and then stringify it all together.  But the
        !           944: example above shows how an equivalent result can be obtained in ANSI
        !           945: Standard C using the feature that adjacent string constants are
        !           946: concatenated as one string constant.  The preprocessor stringifies the
        !           947: actual value of `EXP' into a separate string constant, resulting in
        !           948: text like
        !           949: 
        !           950:      do { if (x == 0) \
        !           951:              fprintf (stderr, "Warning: " "x == 0" "\n"); } \
        !           952:      while (0)
        !           953: 
        !           954: but the C compiler then sees three consecutive string constants and
        !           955: concatenates them into one, producing effectively
        !           956: 
        !           957:      do { if (x == 0) \
        !           958:              fprintf (stderr, "Warning: x == 0\n"); } \
        !           959:      while (0)
        !           960: 
        !           961:    Stringification in C involves more than putting doublequote
        !           962: characters around the fragment; it is necessary to put backslashes in
        !           963: front of all doublequote characters, and all backslashes in string and
        !           964: character constants, in order to get a valid C string constant with the
        !           965: proper contents.  Thus, stringifying `p = "foo\n";' results in `"p =
        !           966: \"foo\\n\";"'.  However, backslashes that are not inside of string or
        !           967: character constants are not duplicated: `\n' by itself stringifies to
        !           968: `"\n"'.
        !           969: 
        !           970:    Whitespace (including comments) in the text being stringified is
        !           971: handled according to precise rules.  All leading and trailing
        !           972: whitespace is ignored.  Any sequence of whitespace in the middle of the
        !           973: text is converted to a single space in the stringified result.
        !           974: 
        !           975: 
        !           976: File: cpp.info,  Node: Concatenation,  Next: Undefining,  Prev: Stringification,  Up: Macros
        !           977: 
        !           978: Concatenation
        !           979: -------------
        !           980: 
        !           981:    "Concatenation" means joining two strings into one.  In the context
        !           982: of macro expansion, concatenation refers to joining two lexical units
        !           983: into one longer one.  Specifically, an actual argument to the macro can
        !           984: be concatenated with another actual argument or with fixed text to
        !           985: produce a longer name.  The longer name might be the name of a function,
        !           986: variable or type, or a C keyword; it might even be the name of another
        !           987: macro, in which case it will be expanded.
        !           988: 
        !           989:    When you define a macro, you request concatenation with the special
        !           990: operator `##' in the macro body.  When the macro is called, after
        !           991: actual arguments are substituted, all `##' operators are deleted, and
        !           992: so is any whitespace next to them (including whitespace that was part
        !           993: of an actual argument).  The result is to concatenate the syntactic
        !           994: tokens on either side of the `##'.
        !           995: 
        !           996:    Consider a C program that interprets named commands.  There probably
        !           997: needs to be a table of commands, perhaps an array of structures
        !           998: declared as follows:
        !           999: 
        !          1000:      struct command
        !          1001:      {
        !          1002:        char *name;
        !          1003:        void (*function) ();
        !          1004:      };
        !          1005:      
        !          1006:      struct command commands[] =
        !          1007:      {
        !          1008:        { "quit", quit_command},
        !          1009:        { "help", help_command},
        !          1010:        ...
        !          1011:      };
        !          1012: 
        !          1013:    It would be cleaner not to have to give each command name twice,
        !          1014: once in the string constant and once in the function name.  A macro
        !          1015: which takes the name of a command as an argument can make this
        !          1016: unnecessary.  The string constant can be created with stringification,
        !          1017: and the function name by concatenating the argument with `_command'.
        !          1018: Here is how it is done:
        !          1019: 
        !          1020:      #define COMMAND(NAME)  { #NAME, NAME ## _command }
        !          1021:      
        !          1022:      struct command commands[] =
        !          1023:      {
        !          1024:        COMMAND (quit),
        !          1025:        COMMAND (help),
        !          1026:        ...
        !          1027:      };
        !          1028: 
        !          1029:    The usual case of concatenation is concatenating two names (or a
        !          1030: name and a number) into a longer name.  But this isn't the only valid
        !          1031: case.  It is also possible to concatenate two numbers (or a number and
        !          1032: a name, such as `1.5' and `e3') into a number.  Also, multi-character
        !          1033: operators such as `+=' can be formed by concatenation.  In some cases
        !          1034: it is even possible to piece together a string constant.  However, two
        !          1035: pieces of text that don't together form a valid lexical unit cannot be
        !          1036: concatenated.  For example, concatenation with `x' on one side and `+'
        !          1037: on the other is not meaningful because those two characters can't fit
        !          1038: together in any lexical unit of C.  The ANSI standard says that such
        !          1039: attempts at concatenation are undefined, but in the GNU C preprocessor
        !          1040: it is well defined: it puts the `x' and `+' side by side with no
        !          1041: particular special results.
        !          1042: 
        !          1043:    Keep in mind that the C preprocessor converts comments to whitespace
        !          1044: before macros are even considered.  Therefore, you cannot create a
        !          1045: comment by concatenating `/' and `*': the `/*' sequence that starts a
        !          1046: comment is not a lexical unit, but rather the beginning of a "long"
        !          1047: space character.  Also, you can freely use comments next to a `##' in a
        !          1048: macro definition, or in actual arguments that will be concatenated,
        !          1049: because the comments will be converted to spaces at first sight, and
        !          1050: concatenation will later discard the spaces.
        !          1051: 
        !          1052: 
        !          1053: File: cpp.info,  Node: Undefining,  Next: Redefining,  Prev: Concatenation,  Up: Macros
        !          1054: 
        !          1055: Undefining Macros
        !          1056: -----------------
        !          1057: 
        !          1058:    To "undefine" a macro means to cancel its definition.  This is done
        !          1059: with the `#undef' command.  `#undef' is followed by the macro name to
        !          1060: be undefined.
        !          1061: 
        !          1062:    Like definition, undefinition occurs at a specific point in the
        !          1063: source file, and it applies starting from that point.  The name ceases
        !          1064: to be a macro name, and from that point on it is treated by the
        !          1065: preprocessor as if it had never been a macro name.
        !          1066: 
        !          1067:    For example,
        !          1068: 
        !          1069:      #define FOO 4
        !          1070:      x = FOO;
        !          1071:      #undef FOO
        !          1072:      x = FOO;
        !          1073: 
        !          1074: expands into
        !          1075: 
        !          1076:      x = 4;
        !          1077:      
        !          1078:      x = FOO;
        !          1079: 
        !          1080: In this example, `FOO' had better be a variable or function as well as
        !          1081: (temporarily) a macro, in order for the result of the expansion to be
        !          1082: valid C code.
        !          1083: 
        !          1084:    The same form of `#undef' command will cancel definitions with
        !          1085: arguments or definitions that don't expect arguments.  The `#undef'
        !          1086: command has no effect when used on a name not currently defined as a
        !          1087: macro.
        !          1088: 
        !          1089: 
        !          1090: File: cpp.info,  Node: Redefining,  Next: Macro Pitfalls,  Prev: Undefining,  Up: Macros
        !          1091: 
        !          1092: Redefining Macros
        !          1093: -----------------
        !          1094: 
        !          1095:    "Redefining" a macro means defining (with `#define') a name that is
        !          1096: already defined as a macro.
        !          1097: 
        !          1098:    A redefinition is trivial if the new definition is transparently
        !          1099: identical to the old one.  You probably wouldn't deliberately write a
        !          1100: trivial redefinition, but they can happen automatically when a header
        !          1101: file is included more than once (*note Header Files::.), so they are
        !          1102: accepted silently and without effect.
        !          1103: 
        !          1104:    Nontrivial redefinition is considered likely to be an error, so it
        !          1105: provokes a warning message from the preprocessor.  However, sometimes it
        !          1106: is useful to change the definition of a macro in mid-compilation.  You
        !          1107: can inhibit the warning by undefining the macro with `#undef' before the
        !          1108: second definition.
        !          1109: 
        !          1110:    In order for a redefinition to be trivial, the new definition must
        !          1111: exactly match the one already in effect, with two possible exceptions:
        !          1112: 
        !          1113:    * Whitespace may be added or deleted at the beginning or the end.
        !          1114: 
        !          1115:    * Whitespace may be changed in the middle (but not inside strings).
        !          1116:      However, it may not be eliminated entirely, and it may not be added
        !          1117:      where there was no whitespace at all.
        !          1118: 
        !          1119:    Recall that a comment counts as whitespace.
        !          1120: 
        !          1121: 
        !          1122: File: cpp.info,  Node: Macro Pitfalls,  Prev: Redefining,  Up: Macros
        !          1123: 
        !          1124: Pitfalls and Subtleties of Macros
        !          1125: ---------------------------------
        !          1126: 
        !          1127:    In this section we describe some special rules that apply to macros
        !          1128: and macro expansion, and point out certain cases in which the rules have
        !          1129: counterintuitive consequences that you must watch out for.
        !          1130: 
        !          1131: * Menu:
        !          1132: 
        !          1133: * Misnesting::        Macros can contain unmatched parentheses.
        !          1134: * Macro Parentheses:: Why apparently superfluous parentheses
        !          1135:                          may be necessary to avoid incorrect grouping.
        !          1136: * Swallow Semicolon:: Macros that look like functions
        !          1137:                          but expand into compound statements.
        !          1138: * Side Effects::      Unsafe macros that cause trouble when
        !          1139:                          arguments contain side effects.
        !          1140: * Self-Reference::    Macros whose definitions use the macros' own names.
        !          1141: * Argument Prescan::  Actual arguments are checked for macro calls
        !          1142:                          before they are substituted.
        !          1143: * Cascaded Macros::   Macros whose definitions use other macros.
        !          1144: * Newlines in Args::  Sometimes line numbers get confused.
        !          1145: 
        !          1146: 
        !          1147: File: cpp.info,  Node: Misnesting,  Next: Macro Parentheses,  Prev: Macro Pitfalls,  Up: Macro Pitfalls
        !          1148: 
        !          1149: Improperly Nested Constructs
        !          1150: ............................
        !          1151: 
        !          1152:    Recall that when a macro is called with arguments, the arguments are
        !          1153: substituted into the macro body and the result is checked, together with
        !          1154: the rest of the input file, for more macro calls.
        !          1155: 
        !          1156:    It is possible to piece together a macro call coming partially from
        !          1157: the macro body and partially from the actual arguments.  For example,
        !          1158: 
        !          1159:      #define double(x) (2*(x))
        !          1160:      #define call_with_1(x) x(1)
        !          1161: 
        !          1162: would expand `call_with_1 (double)' into `(2*(1))'.
        !          1163: 
        !          1164:    Macro definitions do not have to have balanced parentheses.  By
        !          1165: writing an unbalanced open parenthesis in a macro body, it is possible
        !          1166: to create a macro call that begins inside the macro body but ends
        !          1167: outside of it.  For example,
        !          1168: 
        !          1169:      #define strange(file) fprintf (file, "%s %d",
        !          1170:      ...
        !          1171:      strange(stderr) p, 35)
        !          1172: 
        !          1173: This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!
        !          1174: 
        !          1175: 
        !          1176: File: cpp.info,  Node: Macro Parentheses,  Next: Swallow Semicolon,  Prev: Misnesting,  Up: Macro Pitfalls
        !          1177: 
        !          1178: Unintended Grouping of Arithmetic
        !          1179: .................................
        !          1180: 
        !          1181:    You may have noticed that in most of the macro definition examples
        !          1182: shown above, each occurrence of a macro argument name had parentheses
        !          1183: around it.  In addition, another pair of parentheses usually surround
        !          1184: the entire macro definition.  Here is why it is best to write macros
        !          1185: that way.
        !          1186: 
        !          1187:    Suppose you define a macro as follows,
        !          1188: 
        !          1189:      #define ceil_div(x, y) (x + y - 1) / y
        !          1190: 
        !          1191: whose purpose is to divide, rounding up.  (One use for this operation is
        !          1192: to compute how many `int' objects are needed to hold a certain number
        !          1193: of `char' objects.)  Then suppose it is used as follows:
        !          1194: 
        !          1195:      a = ceil_div (b & c, sizeof (int));
        !          1196: 
        !          1197: This expands into
        !          1198: 
        !          1199:      a = (b & c + sizeof (int) - 1) / sizeof (int);
        !          1200: 
        !          1201: which does not do what is intended.  The operator-precedence rules of C
        !          1202: make it equivalent to this:
        !          1203: 
        !          1204:      a = (b & (c + sizeof (int) - 1)) / sizeof (int);
        !          1205: 
        !          1206: But what we want is this:
        !          1207: 
        !          1208:      a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
        !          1209: 
        !          1210: Defining the macro as
        !          1211: 
        !          1212:      #define ceil_div(x, y) ((x) + (y) - 1) / (y)
        !          1213: 
        !          1214: provides the desired result.
        !          1215: 
        !          1216:    However, unintended grouping can result in another way.  Consider
        !          1217: `sizeof ceil_div(1, 2)'.  That has the appearance of a C expression
        !          1218: that would compute the size of the type of `ceil_div (1, 2)', but in
        !          1219: fact it means something very different.  Here is what it expands to:
        !          1220: 
        !          1221:      sizeof ((1) + (2) - 1) / (2)
        !          1222: 
        !          1223: This would take the size of an integer and divide it by two.  The
        !          1224: precedence rules have put the division outside the `sizeof' when it was
        !          1225: intended to be inside.
        !          1226: 
        !          1227:    Parentheses around the entire macro definition can prevent such
        !          1228: problems.  Here, then, is the recommended way to define `ceil_div':
        !          1229: 
        !          1230:      #define ceil_div(x, y) (((x) + (y) - 1) / (y))
        !          1231: 

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