Return to cpp.info-1 CVS log

Up to [GCC 2.x] / gcc

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

1.1.1.2 ! root        1: This is Info file cpp.info, produced by Makeinfo-1.49 from the input
        !             2: file cpp.texi.
1.1       root        3: 
                      4:    This file documents the GNU C Preprocessor.
                      5: 
1.1.1.2 ! root        6:    Copyright (C) 1987, 1989, 1991, 1992 Free Software Foundation, Inc.
1.1       root        7: 
1.1.1.2 ! root        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.
1.1       root       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: 
1.1.1.2 ! root       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.
1.1       root       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
1.1.1.2 ! root       39:      for arbitrary fragments of C code, and then the C preprocessor will
        !            40:      replace the macros with their definitions throughout the program.
1.1       root       41: 
                     42:    * Conditional compilation.  Using special preprocessor commands, you
                     43:      can include or exclude parts of the program according to various
                     44:      conditions.
                     45: 
1.1.1.2 ! root       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.
1.1       root       50: 
1.1.1.2 ! root       51:    C preprocessors vary in some details.  This manual discusses the GNU
        !            52: C preprocessor, the C Compatible Compiler Preprocessor.  The GNU C
1.1       root       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
1.1.1.2 ! root      111: sequence with Backslash-Newline.  For example, you can split `"foo\bar"'
        !           112: between the `\' and the `b' to get
1.1       root      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
1.1.1.2 ! root      120: standard requires it.  (Strict ANSI C does not allow Newlines in string
        !           121: constants, so they do not consider this a problem.)
1.1       root      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: 
1.1.1.2 ! root      129:    * C comments and predefined macro names are never recognized within a
        !           130:      character or string constant.  (Strictly speaking, this is the
1.1       root      131:      rule, not an exception, but it is worth noting here anyway.)
                    132: 
1.1.1.2 ! root      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.
1.1       root      138: 
1.1.1.2 ! root      139:      This exception is relevant only if you use the `-trigraphs' option
        !           140:      to enable trigraph processing.  *Note Invocation::.
1.1       root      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: 
1.1.1.2 ! root      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
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      163: 
                    164:    A preprocessor command cannot be more than one line in normal
1.1.1.2 ! root      165: circumstances. It may be split cosmetically with Backslash-Newline, but
        !           166: that has no effect on its meaning.  Comments containing Newlines can
        !           167: also divide the command into multiple lines, but the comments are
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      186: files.  You request the use of a header file in your program with the C
        !           187: preprocessor command `#include'.
1.1       root      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
1.1.1.2 ! root      213:      are needed in several different source files, it is a good idea to
        !           214:      create a header file for them.
1.1       root      215: 
1.1.1.2 ! root      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
1.1       root      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: 
1.1.1.2 ! root      235:    Both user and system header files are included using the preprocessor
        !           236: command `#include'.  It has three variants:
1.1       root      237: 
                    238: `#include <FILE>'
                    239:      This variant is used for system header files.  It searches for a
1.1.1.2 ! root      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 `#include
        !           249:      <x/*y>' the `/*' does not start a comment and the command
        !           250:      specifies inclusion of a system header file named `x/*y'.  Of
        !           251:      course, a header file with such a name is unlikely to exist on
        !           252:      Unix, where shell wildcard features would make it hard to
1.1       root      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
1.1.1.2 ! root      264:      files that the current input file refers to.  (If the `-I-' option
        !           265:      is used, the special treatment of the current directory is
1.1       root      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
1.1.1.2 ! root      273:      backslashes.  It is not clear why this behavior is ever useful, but
        !           274:      the ANSI standard specifies it.
1.1       root      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
1.1.1.2 ! root      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
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      382: contents of the header file.  `#pragma once' is now obsolete and should
        !           383: not be used at all.
1.1       root      384: 
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      416: a particular system doesn't do what the application program expects. It
        !           417: might be convenient to define a "local" version, perhaps under the name
        !           418: `/usr/local/include/sys/signal.h', to override or add to the one
1.1       root      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: 
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      478: stands for a fragment of code.  Some people refer to these as "manifest
        !           479: constants".
1.1       root      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: 
1.1.1.2 ! root      501:    The use of all upper case for macro names is a standard convention.
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      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
1.1       root      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: 
1.1.1.2 ! root      546:    This is not at all the same as defining `TABLESIZE' to be `1020'.
1.1       root      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
1.1.1.2 ! root      550: of its expansion is checked for more macro names. *Note Cascaded
1.1       root      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: 
1.1.1.2 ! root      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".
1.1       root      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: 
1.1.1.2 ! root      571:    For example, here is a macro that computes the minimum of two numeric
        !           572: values, as it is defined in many C programs:
1.1       root      573: 
                    574:      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
                    575: 
1.1.1.2 ! root      576: (This is not the best way to define a "minimum" macro in GNU C. *Note
1.1       root      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: 
1.1.1.2 ! root      585:    The expansion text of the macro depends on the arguments you use.
1.1       root      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
1.1.1.2 ! root      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:
1.1       root      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: 
1.1.1.2 ! root      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: 
1.1       root      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
1.1.1.2 ! root      651: followed by an open-parenthesis, the macro is not expanded, so you wind
        !           652: up with a call to the function `min'.
1.1       root      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
1.1.1.2 ! root      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
1.1       root      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
1.1.1.2 ! root      663: identifier in parentheses. This rule about spaces makes it possible for
        !           664: you to do either this:
1.1       root      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: 
1.1.1.2 ! root      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.
1.1       root      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
1.1.1.2 ! root      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.
1.1       root      706: 
                    707: `__FILE__'
                    708:      This macro expands to the name of the current input file, in the
1.1.1.2 ! root      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
1.1       root      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
1.1.1.2 ! root      716:      macro, it's a pretty strange macro, since its "definition" changes
        !           717:      with each new line of source code.
1.1       root      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
1.1.1.2 ! root      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').
1.1       root      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
1.1.1.2 ! root      749:      eleven characters and looks like `"Jan 29 1987"' or `"Apr 1 1905"'.
1.1       root      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: `__STRICT_ANSI__'
                    767:      This macro is defined if and only if the `-ansi' switch was
                    768:      specified when GNU C was invoked.  Its definition is the null
1.1.1.2 ! root      769:      string. This macro exists primarily to direct certain GNU header
1.1       root      770:      files not to define certain traditional Unix constructs which are
                    771:      incompatible with ANSI C.
                    772: 
                    773: `__BASE_FILE__'
                    774:      This macro expands to the name of the main input file, in the form
1.1.1.2 ! root      775:      of a C string constant.  This is the source file that was specified
        !           776:      as an argument when the C compiler was invoked.
1.1       root      777: 
                    778: `__VERSION__'
                    779:      This macro expands to a string which describes the version number
                    780:      of GNU C.  The string is normally a sequence of decimal numbers
                    781:      separated by periods, such as `"1.18"'.  The only reasonable use
                    782:      of this macro is to incorporate it into a string constant.
                    783: 
                    784: `__OPTIMIZE__'
                    785:      This macro is defined in optimizing compilations.  It causes
                    786:      certain GNU header files to define alternative macro definitions
                    787:      for some system library functions.  It is unwise to refer to or
                    788:      test the definition of this macro unless you make very sure that
                    789:      programs will execute with the same effect regardless.
                    790: 
                    791: `__CHAR_UNSIGNED__'
                    792:      This macro is defined if and only if the data type `char' is
                    793:      unsigned on the target machine.  It exists to cause the standard
                    794:      header file `limit.h' to work correctly.  It is bad practice to
                    795:      refer to this macro yourself; instead, refer to the standard
                    796:      macros defined in `limit.h'.  The preprocessor uses this macro to
                    797:      determine whether or not to sign-extend large character constants
                    798:      written in octal; see *Note The `#if' Command: #if Command.
                    799: 
                    800: 
                    801: File: cpp.info,  Node: Nonstandard Predefined,  Prev: Standard Predefined,  Up: Predefined
                    802: 
                    803: Nonstandard Predefined Macros
                    804: .............................
                    805: 
                    806:    The C preprocessor normally has several predefined macros that vary
                    807: between machines because their purpose is to indicate what type of
                    808: system and machine is in use.  This manual, being for all systems and
                    809: machines, cannot tell you exactly what their names are; instead, we
                    810: offer a list of some typical ones.  You can use `cpp -dM' to see the
                    811: values of predefined macros; *note Invocation::..
                    812: 
                    813:    Some nonstandard predefined macros describe the operating system in
                    814: use, with more or less specificity.  For example,
                    815: 
                    816: `unix'
                    817:      `unix' is normally predefined on all Unix systems.
                    818: 
                    819: `BSD'
                    820:      `BSD' is predefined on recent versions of Berkeley Unix (perhaps
                    821:      only in version 4.3).
                    822: 
                    823:    Other nonstandard predefined macros describe the kind of CPU, with
                    824: more or less specificity.  For example,
                    825: 
                    826: `vax'
                    827:      `vax' is predefined on Vax computers.
                    828: 
                    829: `mc68000'
                    830:      `mc68000' is predefined on most computers whose CPU is a Motorola
                    831:      68000, 68010 or 68020.
                    832: 
                    833: `m68k'
                    834:      `m68k' is also predefined on most computers whose CPU is a 68000,
                    835:      68010 or 68020; however, some makers use `mc68000' and some use
1.1.1.2 ! root      836:      `m68k'.  Some predefine both names.  What happens in GNU C depends
        !           837:      on the system you are using it on.
1.1       root      838: 
                    839: `M68020'
                    840:      `M68020' has been observed to be predefined on some systems that
                    841:      use 68020 CPUs--in addition to `mc68000' and `m68k', which are
                    842:      less specific.
                    843: 
                    844: `_AM29K'
                    845: `_AM29000'
                    846:      Both `_AM29K' and `_AM29000' are predefined for the AMD 29000 CPU
                    847:      family.
                    848: 
                    849: `ns32000'
                    850:      `ns32000' is predefined on computers which use the National
                    851:      Semiconductor 32000 series CPU.
                    852: 
                    853:    Yet other nonstandard predefined macros describe the manufacturer of
                    854: the system.  For example,
                    855: 
                    856: `sun'
                    857:      `sun' is predefined on all models of Sun computers.
                    858: 
                    859: `pyr'
                    860:      `pyr' is predefined on all models of Pyramid computers.
                    861: 
                    862: `sequent'
                    863:      `sequent' is predefined on all models of Sequent computers.
                    864: 
1.1.1.2 ! root      865:    These predefined symbols are not only nonstandard, they are contrary
        !           866: to the ANSI standard because their names do not start with underscores.
        !           867: Therefore, the option `-ansi' inhibits the definition of these symbols.
        !           868: 
        !           869:    This tends to make `-ansi' useless, since many programs depend on the
        !           870: customary nonstandard predefined symbols.  Even system header files
        !           871: check them and will generate incorrect declarations if they do not find
        !           872: the names that are expected.  You might think that the header files
        !           873: supplied for the Uglix computer would not need to test what machine
        !           874: they are running on, because they can simply assume it is the Uglix;
        !           875: but often they do, and they do so using the customary names.  As a
        !           876: result, very few C programs will compile with `-ansi'.  We intend to
        !           877: avoid such problems on the GNU system.
1.1       root      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
1.1.1.2 ! root      908: macro arguments are substituted into the macro definition.  In the body
        !           909: of the definition, when an argument name appears, the character `#'
        !           910: before the name specifies stringification of the corresponding actual
        !           911: argument when it is substituted at that point in the definition.  The
        !           912: same argument may be substituted in other places in the definition
        !           913: without stringification if the argument name appears in those places
        !           914: with no `#'.
1.1       root      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
1.1.1.2 ! root      935: concatenated as one string constant.  The preprocessor stringifies the
        !           936: actual value of `EXP' into a separate string constant, resulting in
1.1       root      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
1.1.1.2 ! root      953: character constants, in order to get a valid C string constant with the
        !           954: proper contents.  Thus, stringifying `p = "foo\n";' results in `"p =
        !           955: \"foo\\n\";"'.  However, backslashes that are not inside of string or
1.1       root      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
1.1.1.2 ! root      961: whitespace is ignored. Any sequence of whitespace in the middle of the
        !           962: text is converted to a single space in the stringified result.
1.1       root      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
1.1.1.2 ! root      972: into one longer one.  Specifically, an actual argument to the macro can
        !           973: 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 function,
        !           975: variable or type, or a C keyword; it might even be the name of another
        !           976: macro, in which case it will be expanded.
1.1       root      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: 
1.1.1.2 ! root      985:    Consider a C program that interprets named commands.  There probably
        !           986: needs to be a table of commands, perhaps an array of structures
        !           987: declared as follows:
1.1       root      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: 
1.1.1.2 ! root     1032:    Keep in mind that the C preprocessor converts comments to whitespace
        !          1033: before macros are even considered.  Therefore, you cannot create a
        !          1034: comment by concatenating `/' and `*': the `/*' sequence that starts a
        !          1035: comment is not a lexical unit, but rather the beginning of a "long"
        !          1036: space character.  Also, you can freely use comments next to a `##' in a
        !          1037: macro definition, or in actual arguments that will be concatenated,
        !          1038: because the comments will be converted to spaces at first sight, and
        !          1039: concatenation will later discard the spaces.
1.1       root     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
1.1.1.2 ! root     1094: provokes a warning message from the preprocessor.  However, sometimes it
        !          1095: is useful to change the definition of a macro in mid-compilation.  You
        !          1096: can inhibit the warning by undefining the macro with `#undef' before the
        !          1097: second definition.
1.1       root     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: 
1.1.1.2 ! root     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 added
        !          1106:      where there was no whitespace at all.
1.1       root     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
1.1.1.2 ! root     1117: and macro expansion, and point out certain cases in which the rules have
        !          1118: counterintuitive consequences that you must watch out for.
1.1       root     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.
1.1.1.2 ! root     1133: * Newlines in Args::  Sometimes line numbers get confused.
1.1       root     1134: 
                   1135: 
                   1136: File: cpp.info,  Node: Misnesting,  Next: Macro Parentheses,  Prev: Macro Pitfalls,  Up: Macro Pitfalls
                   1137: 
                   1138: Improperly Nested Constructs
                   1139: ............................
                   1140: 
                   1141:    Recall that when a macro is called with arguments, the arguments are
1.1.1.2 ! root     1142: substituted into the macro body and the result is checked, together with
        !          1143: the rest of the input file, for more macro calls.
1.1       root     1144: 
                   1145:    It is possible to piece together a macro call coming partially from
                   1146: the macro body and partially from the actual arguments.  For example,
                   1147: 
                   1148:      #define double(x) (2*(x))
                   1149:      #define call_with_1(x) x(1)
                   1150: 
                   1151: would expand `call_with_1 (double)' into `(2*(1))'.
                   1152: 
                   1153:    Macro definitions do not have to have balanced parentheses.  By
                   1154: writing an unbalanced open parenthesis in a macro body, it is possible
                   1155: to create a macro call that begins inside the macro body but ends
                   1156: outside of it.  For example,
                   1157: 
                   1158:      #define strange(file) fprintf (file, "%s %d",
                   1159:      ...
                   1160:      strange(stderr) p, 35)
                   1161: 
                   1162: This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!
                   1163: 
                   1164: 
                   1165: File: cpp.info,  Node: Macro Parentheses,  Next: Swallow Semicolon,  Prev: Misnesting,  Up: Macro Pitfalls
                   1166: 
                   1167: Unintended Grouping of Arithmetic
                   1168: .................................
                   1169: 
                   1170:    You may have noticed that in most of the macro definition examples
                   1171: shown above, each occurrence of a macro argument name had parentheses
1.1.1.2 ! root     1172: around it. In addition, another pair of parentheses usually surround
1.1       root     1173: the entire macro definition.  Here is why it is best to write macros
                   1174: that way.
                   1175: 
                   1176:    Suppose you define a macro as follows,
                   1177: 
                   1178:      #define ceil_div(x, y) (x + y - 1) / y
                   1179: 
1.1.1.2 ! root     1180: whose purpose is to divide, rounding up.  (One use for this operation is
        !          1181: to compute how many `int' objects are needed to hold a certain number
        !          1182: of `char' objects.)  Then suppose it is used as follows:
1.1       root     1183: 
                   1184:      a = ceil_div (b & c, sizeof (int));
                   1185: 
                   1186: This expands into
                   1187: 
                   1188:      a = (b & c + sizeof (int) - 1) / sizeof (int);
                   1189: 
1.1.1.2 ! root     1190: which does not do what is intended.  The operator-precedence rules of C
        !          1191: make it equivalent to this:
1.1       root     1192: 
                   1193:      a = (b & (c + sizeof (int) - 1)) / sizeof (int);
                   1194: 
                   1195: But what we want is this:
                   1196: 
                   1197:      a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
                   1198: 
                   1199: Defining the macro as
                   1200: 
                   1201:      #define ceil_div(x, y) ((x) + (y) - 1) / (y)
                   1202: 
                   1203: provides the desired result.
                   1204: 
                   1205:    However, unintended grouping can result in another way.  Consider
                   1206: `sizeof ceil_div(1, 2)'.  That has the appearance of a C expression
                   1207: that would compute the size of the type of `ceil_div (1, 2)', but in
                   1208: fact it means something very different.  Here is what it expands to:
                   1209: 
                   1210:      sizeof ((1) + (2) - 1) / (2)
                   1211: 
                   1212: This would take the size of an integer and divide it by two.  The
1.1.1.2 ! root     1213: precedence rules have put the division outside the `sizeof' when it was
        !          1214: intended to be inside.
1.1       root     1215: 
                   1216:    Parentheses around the entire macro definition can prevent such
1.1.1.2 ! root     1217: problems. Here, then, is the recommended way to define `ceil_div':
1.1       root     1218: 
                   1219:      #define ceil_div(x, y) (((x) + (y) - 1) / (y))
                   1220: 
                   1221: 

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