Return to cpp.info-1 CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/cpp.info-1, revision 1.1

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

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