![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to cpp.info CVS log | Up to [GCC 1.x] / gcc |
1.1.1.2 ! root 1: Info file cpp.info, produced by texinfo-format-buffer -*-Text-*- 1.1 root 2: from file cpp.texinfo 3: 4: This file documents the GNU C Preprocessor. 5: 6: Copyright (C) 1987 Richard M. Stallman. 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 this 13: manual under the conditions for verbatim copying, provided also that 14: the entire resulting derived work is distributed under the terms of a 15: permission notice identical to this one. 16: 17: Permission is granted to copy and distribute translations of this manual 18: into another language, under the above conditions for modified versions. 19: 20: 21: 1.1.1.2 ! root 22: File: cpp.info Node: Top, Up: (DIR), Next: Global Actions 1.1 root 23: 24: The C Preprocessor 25: ****************** 26: 27: The C preprocessor is a "macro processor" that is used automatically by 28: the C compiler to transform your program before actual compilation. It is 29: called a macro processor because it allows you to define "macros", 30: which are brief abbreviations for longer constructs. 31: 32: The C preprocessor provides four separate facilities that you can use as 33: you see fit: 34: 35: * Inclusion of header files. These are files of declarations that can be 36: substituted into your program. 37: 38: * Macro expansion. You can define "macros", which are abbreviations 39: for arbitrary fragments of C code, and then the C preprocessor will 40: replace the macros with their definitions throughout the program. 41: 42: * Conditional compilation. Using special preprocessor commands, you 43: can include or exclude parts of the program according to various 44: conditions. 45: 46: * Line control. If you use a program to combine or rearrange source files into 47: an intermediate file which is then compiled, you can use line control 48: to inform the compiler of where each source line originally came from. 49: 50: C preprocessors vary in some details. This manual discusses the GNU C 51: preprocessor, the C Compatible Compiler Preprocessor. The GNU C 52: preprocessor provides a superset of the features of ANSI Standard C. 53: 54: ANSI Standard C requires the rejection of many harmless constructs commonly 55: used by today's C programs. Such incompatibility would be inconvenient for 56: users, so the GNU C preprocessor is configured to accept these constructs 57: by default. Strictly speaking, to get ANSI Standard C, you must use the 1.1.1.2 ! root 58: options `-T', `-undef' and `-pedantic', but in practice the 1.1 root 59: consequences of having strict ANSI Standard C make it undesirable to do 60: this. *Note Invocation::. 61: 62: * Menu: 63: 64: * Global Actions:: Actions made uniformly on all input files. 65: * Commands:: General syntax of preprocessor commands. 66: * Header Files:: How and why to use header files. 67: * Macros:: How and why to use macros. 68: * Conditionals:: How and why to use conditionals. 69: * Combining Sources:: Use of line control when you combine source files. 70: * Other Commands:: Miscellaneous preprocessor commands. 71: * Output:: Format of output from the C preprocessor. 1.1.1.2 ! root 72: * Invocation:: How to invoke the preprocessor; command options. 1.1 root 73: * Concept Index:: Index of concepts and terms. 1.1.1.2 ! root 74: * Index:: Index of commands, predefined macros and options. 1.1 root 75: 76: 1.1.1.2 ! root 77: File: cpp.info Node: Global Actions, Prev: Top, Up: Top, Next: Commands 1.1 root 78: 79: Transformations Made Globally 80: ============================= 81: 82: Most C preprocessor features are inactive unless you give specific commands 83: to request their use. (Preprocessor commands are lines starting with 84: `#'; *Note Commands::). But there are three transformations that the 85: preprocessor always makes on all the input it receives, even in the absence 86: of commands. 87: 88: * All C comments are replaced with single spaces. 89: 90: * Backslash-Newline sequences are deleted, no matter where. This 91: feature allows you to break long lines for cosmetic purposes without 92: changing their meaning. 93: 94: * Predefined macro names are replaced with their expansions 95: (*Note Predefined::). 96: 97: The first two transformations are done *before* nearly all other parsing 98: and before preprocessor commands are recognized. Thus, for example, you 1.1.1.2 ! root 99: can split a line cosmetically with Backslash-Newline anywhere (except ! 100: when trigraphs are in use; see below). 1.1 root 101: 1.1.1.2 ! root 102: /* ! 103: */ # /* ! 104: */ defi\ 1.1 root 105: ne FO\ 106: O 10\ 107: 20 108: 1.1.1.2 ! root 109: is equivalent into `#define FOO 1020'. You can split even an escape ! 110: sequence with Backslash-Newline. For example, you can split `"foo\bar"' ! 111: between the `\' and the `b' to get ! 112: ! 113: "foo\\ ! 114: bar" ! 115: ! 116: This behavior is unclean: in all other contexts, a Backslash can be ! 117: inserted in a string constant as an ordinary character by writing a double ! 118: Backslash, and this creates an exception. But the ANSI C standard requires ! 119: it. (Strict ANSI C does not allow Newlines in string constants, so they ! 120: do not consider this a problem.) 1.1 root 121: 1.1.1.2 ! root 122: But there are a few exceptions to all three transformations. 1.1 root 123: 124: * C comments and predefined macro names are not recognized inside a 125: `#include' command in which the file name is delimited with 126: `<' and `>'. 127: 128: * C comments and predefined macro names are never recognized within a 129: character or string constant. (Strictly speaking, this is the rule, 130: not an exception, but it is worth noting here anyway.) 131: 1.1.1.2 ! root 132: * Backslash-Newline may not safely be used within an ANSI "trigraph". ! 133: Trigraphs are converted before Backslash-Newline is deleted. If you ! 134: write what looks like a trigraph with a Backslash-Newline inside, the ! 135: Backslash-Newline is deleted as usual, but it is then too late to ! 136: recognize the trigraph. 1.1 root 137: 1.1.1.2 ! root 138: This exception is relevant only if you use the `-T' option to ! 139: enable trigraph processing. *Note Invocation::. 1.1 root 140: 141: 1.1.1.2 ! root 142: File: cpp.info Node: Commands, Prev: Global Actions, Up: Top, Next: Header Files 1.1 root 143: 144: Preprocessor Commands 145: ===================== 146: 147: Most preprocessor features are active only if you use preprocessor commands 148: to request their use. 149: 150: Preprocessor commands are lines in your program that start with `#'. 151: The `#' is followed by an identifier that is the "command name". 152: For example, `#define' is the command that defines a macro. 153: Whitespace is also allowed before and after the `#'. 154: 155: The set of valid command names is fixed. Programs cannot define new 156: preprocessor commands. 157: 158: Some command names require arguments; these make up the rest of the command 159: line and must be separated from the command name by whitespace. For example, 160: `#define' must be followed by a macro name and the intended expansion 161: of the macro. 162: 163: A preprocessor command cannot be more than one line in normal circumstances. 164: It may be split cosmetically with Backslash-Newline, but that has no effect 165: on its meaning. Comments containing Newlines can also divide the command into 166: multiple lines, but the comments are changed to Spaces before the command 167: is interpreted. The only way a significant Newline can occur in a preprocessor 168: command is within a string constant or character constant. Note that 169: most C compilers that might be applied to the output from the preprocessor 170: do not accept string or character constants containing Newlines. 171: 172: The `#' and the command name cannot come from a macro expansion. For 173: example, if `foo' is defined as a macro expanding to `define', 174: that does not make `#foo' a valid preprocessor command. 175: 176: 1.1.1.2 ! root 177: File: cpp.info Node: Header Files, Prev: Commands, Up: Top, Next: Macros 1.1 root 178: 179: Header Files 180: ============ 181: 182: A header file is a file containing C declarations and macro definitions 183: (*Note Macros::) to be shared between several source files. You request 184: the use of a header file in your program with the C preprocessor command 185: `#include'. 186: 187: 1.1.1.2 ! root 188: File: cpp.info Node: Header Uses, Prev: Header Files, Up: Header Files, Next: Include Syntax 1.1 root 189: 190: Uses of Header Files 191: -------------------- 192: 193: Header files serve two kinds of purposes. 194: 195: * System header files declare the interfaces to parts of the operating 196: system. You include them in your program to supply the definitions 197: you need to invoke system calls and libraries. 198: 199: * Your own header files contain declarations for interfaces between the 200: source files of your program. Each time you have a group of related 201: declarations and macro definitions all or most of which are needed in 202: several different source files, it is a good idea to create a header 203: file for them. 204: 205: Including a header file produces the same results in C compilation as 206: copying the header file into each source file that needs it. But such 207: copying would be time-consuming and error-prone. With a header file, the 208: related declarations appear in only one place. If they need to be changed, 209: they can be changed in one place, and programs that include the header file 210: will automatically use the new version when next recompiled. The header 211: file eliminates the labor of finding and changing all the copies as well as 212: the risk that a failure to find one copy will result in inconsistencies 213: within a program. 214: 215: The usual convention is to give header files names that end with `.h'. 216: 217: 1.1.1.2 ! root 218: File: cpp.info Node: Include Syntax, Prev: Header Uses, Up: Header Files, Next: Include Operation 1.1 root 219: 220: The `#include' Command 221: ---------------------- 222: 223: Both user and system header files are included using the preprocessor 224: command `#include'. It has three variants: 225: 226: `#include <FILE>' 227: This variant is used for system header files. It searches for a file 1.1.1.2 ! root 228: named FILE in a list of directories specified by you, then in a ! 229: standard list of system directories. You specify directories to ! 230: search for header files with the command option `-I' ! 231: (*Note Invocation::). ! 232: ! 233: The parsing of this form of `#include' is slightly special because ! 234: comments are not recognized within the `<...>'. Thus, in `#include ! 235: <x/*y>' the `/*' does not start a comment and the command specifies ! 236: inclusion of a system header file named `x/*y'. Of course, a header ! 237: file with such a name is unlikely to exist on Unix, where shell ! 238: wildcard features would make it hard to manipulate. 1.1 root 239: 1.1.1.2 ! root 240: The argument FILE may not contain a `>' character. It may, ! 241: however, contain a `<' character. 1.1 root 242: 243: `#include "FILE"' 244: This variant is used for header files of your own program. It 245: searches for a file named FILE first in the current working 1.1.1.2 ! root 246: directory, then in the same directories used for system header 1.1 root 247: files. The current working directory is tried first because it is 248: presumed to be the location of the files of the program being 1.1.1.2 ! root 249: compiled. 1.1 root 250: 1.1.1.2 ! root 251: The argument FILE may not contain `"' characters. If ! 252: backslashes occur within FILE, they are considered ordinary text ! 253: characters, not escape characters. None of the character escape ! 254: sequences appropriate to string constants in C are processed. Thus, ! 255: `#include "x\n\\y"' specifies a filename containing three ! 256: backslashes. It is not clear why this behavior is ever useful, but ! 257: the ANSI standard specifies it. 1.1 root 258: 259: `#include ANYTHING ELSE' 260: This variant is called a "computed #include". Any `#include' 261: command whose argument does not fit the above two forms is a computed 1.1.1.2 ! root 262: include. The text ANYTHING ELSE is checked for macro calls, ! 263: which are expanded (*Note Macros::). When this is done, the result ! 264: must fit one of the above two variants. 1.1 root 265: 266: This feature allows you to define a macro which controls the file name 267: to be used at a later point in the program. One application of this 268: is to allow a site-configuration file for your program to specify the 269: names of the system include files to be used. This can help in 270: porting the program to various operating systems in which the 271: necessary system header files are found in different places. 272: 273: 1.1.1.2 ! root 274: File: cpp.info Node: Include Operation, Prev: Include Syntax, Up: Header Files 1.1 root 275: 276: How `#include' Works 277: -------------------- 278: 279: The `#include' command works by directing the C preprocessor to scan 280: the specified file as input before continuing with the rest of the current 281: file. The output from the preprocessor contains the output already 282: generated, followed by the output resulting from the included file, 283: followed by the output that comes from the text after the `#include' 284: command. For example, given two files as follows: 285: 286: /* File program.c */ 287: int x; 288: #include "header.h" 289: 290: main () 291: { 292: printf (test ()); 293: } 294: 295: 296: /* File header.h */ 297: char *test (); 298: 299: the output generated by the C preprocessor for `program.c' as input 300: would be 301: 302: int x; 303: char *test (); 304: 305: main () 306: { 307: printf (test ()); 308: } 309: 310: Included files are not limited to declarations and macro definitions; they 311: are merely the typical use. Any fragment of a C program can be included 312: from another file. The include file could even contain the beginning of a 313: statement that is concluded in the containing file, or the end of a 314: statement that was started in the including file. However, a comment or a 315: string or character constant may not start in the included file and finish 316: in the including file. An unterminated comment, string constant or 317: character constant in an included file is considered to end (with an error 318: message) at the end of the file. 319: 320: The line following the `#include' command is always treated as a 321: separate line by the C preprocessor even if the included file lacks a final 322: newline. 323: 324: 1.1.1.2 ! root 325: File: cpp.info Node: Macros, Prev: Header Files, Up: Top, Next: Conditionals 1.1 root 326: 327: Macros 328: ====== 329: 330: A macro is a sort of abbreviation which you can define once and then 331: use later. There are many complicated features associated with macros 332: in the C preprocessor. 333: 334: * Menu: 335: 336: * Simple Macros:: Macros that always expand the same way. 337: * Argument Macros:: Macros that accept arguments that are substituted 338: into the macro expansion. 339: * Predefined:: Predefined macros that are always available. 340: * Stringification:: Macro arguments converted into string constants. 341: * Concatenation:: Building tokens from parts taken from macro arguments. 342: * Undefining:: Cancelling a macro's definition. 343: * Redefining:: Changing a macro's definition. 344: * Macro Pitfalls:: Macros can confuse the unwary. Here we explain 345: several common problems and strange features. 346: 347: 1.1.1.2 ! root 348: File: cpp.info Node: Simple Macros, Prev: Macros, Up: Macros, Next: Argument Macros 1.1 root 349: 350: Simple Macros 351: ------------- 352: 353: A "simple macro" is a kind of abbreviation. It is a name which stands 354: for a fragment of code. 355: 356: Before you can use a macro, you must "define" it explicitly with the 357: `#define' command. `#define' is followed by the name of the 358: macro and then the code it should be an abbreviation for. For example, 359: 360: #define BUFFER_SIZE 1020 361: 362: defines a macro named `BUFFER_SIZE' as an abbreviation for the text 363: `1020'. Therefore, if somewhere after this `#define' command 364: there comes a C statement of the form 365: 366: foo = (char *) xmalloc (BUFFER_SIZE); 367: 368: then the C preprocessor will recognize and "expand" the macro 369: `BUFFER_SIZE', resulting in 370: 371: foo = (char *) xmalloc (1020); 372: 373: the definition must be a single line; however, it may not end in the 374: middle of a multi-line string constant or character constant. 375: 376: The use of all upper case for macro names is a standard convention. 377: Programs are easier to read when it is possible to tell at a glance which 378: names are macros. 379: 380: Normally, a macro definition must be a single line, like all C preprocessor 381: commands. (You can split a long macro definition cosmetically with 382: Backslash-Newline.) There is one exception: Newlines can be included in 383: the macro definition if within a string or character constant. By the same 384: token, it is not possible for a macro definition to contain an unbalanced 385: quote character; the definition automatically extends to include the 386: matching quote character that ends the string or character constant. 387: Comments within a macro definition may contain Newlines, which make no 388: difference since the comments are entirely replaced with Spaces regardless 389: of their contents. 390: 391: Aside from the above, there is no restriction on what can go in a macro 392: body. Parentheses need not balance. The body need not resemble valid C 393: code. (Of course, you might get error messages from the C compiler when 394: you use the macro.) 395: 396: The C preprocessor scans your program sequentially, so macro definitions 397: take effect at the place you write them. Therefore, the following input to 398: the C preprocessor 399: 400: foo = X; 401: #define X 4 402: bar = X; 403: 404: produces as output 405: 406: foo = X; 407: 408: bar = 4; 409: 410: After the preprocessor expands a macro name, the macro's definition body is 411: appended to the front of the remaining input, and the check for macro calls 412: continues. Therefore, the macro body can contain calls to other macros. 413: For example, after 414: 415: #define BUFSIZE 1020 416: #define TABLESIZE BUFSIZE 417: 418: the name `TABLESIZE' when used in the program would go through two 419: stages of expansion, resulting ultimately in `1020'. 420: 421: This is not at all the same as defining `TABLESIZE' to be `1020'. 422: The `#define' for `TABLESIZE' uses exactly the body you 423: specify---in this case, `BUFSIZE'---and does not check to see whether 424: it too is the name of a macro. It's only when you *use* `TABLESIZE' 425: that the result of its expansion is checked for more macro names. 426: *Note Cascaded Macros::. 427: 428: 1.1.1.2 ! root 429: File: cpp.info Node: Argument Macros, Prev: Simple Macros, Up: Macros, Next: Predefined 1.1 root 430: 431: Macros with Arguments 432: --------------------- 433: 434: A simple macro always stands for exactly the same text, each time it is 435: used. Macros can be more flexible when they accept "arguments". 436: Arguments are fragments of code that you supply each time the macro is 437: used. These fragments are included in the expansion of the macro according 438: to the directions in the macro definition. 439: 440: To define a macro that uses arguments, you write a `#define' command 441: with a list of "argument names" in parentheses after the name of the 442: macro. The argument names may be any valid C identifiers, separated by 443: commas and optionally whitespace. The open-parenthesis must follow the 444: macro name immediately, with no space in between. 445: 446: For example, here is a macro that computes the minimum of two numeric 1.1.1.2 ! root 447: values, as it is defined in many C programs: 1.1 root 448: 449: #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 450: 1.1.1.2 ! root 451: (This is not the best way to define a "minimum" macro in GNU C. ! 452: *Note Side Effects::, for more information.) ! 453: 1.1 root 454: To use a macro that expects arguments, you write the name of the macro 455: followed by a list of "actual arguments" in parentheses. separated by 456: commas. The number of actual arguments you give must match the number of 457: arguments the macro expects. Examples of use of the macro `min' 458: include `min (1, 2)' and `min (x + 28, *p)'. 459: 460: The expansion text of the macro depends on the arguments you use. 461: Each of the argument names of the macro is replaced, throughout the 462: macro definition, with the corresponding actual argument. Using the 463: same macro `min' defined above, `min (1, 2)' expands into 464: 465: ((1) < (2) ? (1) : (2)) 466: 467: where `1' has been substituted for `X' and `2' for `Y'. 468: 469: Likewise, `min (x + 28, *p)' expands into 470: 471: ((x + 28) < (*p) ? (x + 28) : (*p)) 472: 473: Parentheses in the actual arguments must balance; a comma within 474: parentheses does not end an argument. However, there is no requirement for 475: brackets or braces to balance; thus, if you want to supply `array[x = 476: y, x + 1]' as an argument, you must write it as `array[(x = y, x + 477: 1)]', which is equivalent C code. 478: 479: After the actual arguments are substituted into the macro body, the entire 480: result is appended to the front of the remaining input, and the check for 481: macro calls continues. Therefore, the actual arguments can contain calls 482: to other macros, either with or without arguments, or even to the same 483: macro. The macro body can also contain calls to other macros. For 484: example, `min (min (a, b), c)' expands into 485: 486: ((((a) < (b) ? (a) : (b))) < (c) 487: ? (((a) < (b) ? (a) : (b))) 488: : (c)) 489: 490: (Line breaks shown here for clarity would not actually be generated.) 491: 492: If you use the macro name followed by something other than an 1.1.1.2 ! root 493: open-parenthesis (after ignoring any spaces, tabs and comments that ! 494: follow), it is not a call to the macro, and the preprocessor does not ! 495: change what you have written. Therefore, it is possible for the same name ! 496: to be a variable or function in your program as well as a macro, and you ! 497: can choose in each instance whether to refer to the macro (if an actual ! 498: argument list follows) or the variable or function (if an argument list ! 499: does not follow). 1.1 root 500: 501: Such dual use of one name could be confusing and should be avoided 502: except when the two meanings are effectively synonymous: that is, when the 503: name is both a macro and a function and the two have similar effects. You 1.1.1.2 ! root 504: can think of the name simply as a function; use of the name for purposes 1.1 root 505: other than calling it (such as, to take the address) will refer to the 506: function, while calls will expand the macro and generate better but 507: equivalent code. For example, you can use a function named `min' in 508: the same source file that defines the macro. If you write `&min' with 509: no argument list, you refer to the function. If you write `min (x, 510: bb)', with an argument list, the macro is expanded. If you write 511: `(min) (a, bb)', where the name `min' is not followed by an 512: open-parenthesis, the macro is not expanded, so you wind up with a call to 513: the function `min'. 514: 515: It is not allowed to define the same name as both a simple macro and 516: a macro with arguments. 517: 518: In the definition of a macro with arguments, the list of argument names 519: must follow the macro name immediately with no space in between. If there 520: is a space after the macro name, the macro is defined as taking no 1.1.1.2 ! root 521: arguments, and all the rest of the name is taken to be the expansion. The ! 522: reason for this is that it is often useful to define a macro that takes no ! 523: arguments and whose definition begins with an identifier in parentheses. ! 524: This rule about spaces makes it possible for you to do either this: 1.1 root 525: 526: #define FOO(x) - 1 / (x) 527: 1.1.1.2 ! root 528: (which defines `FOO' to take an argument and expand into minus the ! 529: reciprocal of that argument) or this: 1.1 root 530: 531: #define BAR (x) - 1 / (x) 532: 1.1.1.2 ! root 533: (which defines `BAR' to take no argument and always expand into ! 534: `(x) - 1 / (x)'). ! 535: ! 536: Note that the *uses* of a macro with arguments can have spaces before ! 537: the left parenthesis; it's the *definition* where it matters whether ! 538: there is a space. 1.1 root 539: 540: 1.1.1.2 ! root 541: File: cpp.info Node: Predefined, Prev: Argument Macros, Up: Macros, Next: Stringification 1.1 root 542: 543: Predefined Macros 544: ----------------- 545: 546: Several simple macros are predefined. You can use them without giving 547: definitions for them. They fall into two classes: standard macros and 548: system-specific macros. 549: 550: * Menu: 551: 552: * Standard Predefined:: Standard predefined macros. 553: * Nonstandard Predefined:: Nonstandard predefined macros. 554: 555: 1.1.1.2 ! root 556: File: cpp.info Node: Standard Predefined, Prev: Predefined, Up: Predefined, Next: Nonstandard Predefined 1.1 root 557: 558: Standard Predefined Macros 559: .......................... 560: 1.1.1.2 ! root 561: The standard predefined macros are available with the same meanings ! 562: regardless of the machine or operating system on which you are using GNU C. ! 563: Their names all start and end with double underscores. Those preceding ! 564: `__GNUC__' in this table are standardized by ANSI C; the rest are ! 565: GNU C extensions. 1.1 root 566: 567: `__FILE__' 568: This macro expands to the name of the current input file, in the form 569: of a C string constant. 570: 571: `__LINE__' 572: This macro expands to the current input line number, in the form of a 573: decimal integer constant. While we call it a predefined macro, it's 574: a pretty strange macro, since its "definition" changes with each 575: new line of source code. 576: 577: This and `__FILE__' are useful in generating an error message to 578: report an inconsistency detected by the program; the message can state 579: the source line at which the inconsistency was detected. For example, 580: 581: fprintf (stderr, "Internal error: negative string length " 582: "%d at %s, line %d.", 583: length, __FILE__, __LINE__); 584: 585: A `#include' command changes the expansions of `__FILE__' 586: and `__LINE__' to correspond to the included file. At the end of 587: that file, when processing resumes on the input file that contained 588: the `#include' command, the expansions of `__FILE__' and 589: `__LINE__' revert to the values they had before the 590: `#include' (but `__LINE__' is then incremented by one as 591: processing moves to the line after the `#include'). 592: 593: The expansions of both `__FILE__' and `__LINE__' are altered 594: if a `#line' command is used. *Note Combining Sources::. 595: 596: `__DATE__' 597: This macro expands to a string constant that describes the date on 598: which the preprocessor is being run. The string constant contains 599: eleven characters and looks like `"Jan 29 1987"' or `"Apr 600: 1 1905"'. 601: 602: `__TIME__' 603: This macro expands to a string constant that describes the time at 604: which the preprocessor is being run. The string constant contains 605: eight characters and looks like `"23:59:01"'. 606: 607: `__STDC__' 608: This macro expands to the constant 1, to signify that this is ANSI 609: Standard C. (Whether that is actually true depends on what C compiler 610: will operate on the output from the preprocessor.) 1.1.1.2 ! root 611: ! 612: `__GNUC__' ! 613: This macro is defined if and only if this is GNU C. This macro is ! 614: defined only when the entire GNU C compiler is in use; if you invoke ! 615: the preprocessor directly, `__GNUC__' is undefined. ! 616: ! 617: `__STRICT_ANSI__' ! 618: This macro is defined if and only if the `-ansi' switch was ! 619: specified when GNU C was invoked. Its definition is the null string. ! 620: This macro exists primarily to direct certain GNU header files not to ! 621: define certain traditional Unix constructs which are incompatible with ! 622: ANSI C. ! 623: ! 624: `__VERSION__' ! 625: This macro expands to a string which describes the version number of ! 626: GNU C. The string is normally a sequence of decimal numbers separated ! 627: by periods, such as `"1.18"'. The only reasonable use of this ! 628: macro is to incorporate it into a string constant. ! 629: ! 630: `__OPTIMIZE__' ! 631: This macro is defined in optimizing compilations. It causes certain ! 632: GNU header files to define alternative macro definitions for some ! 633: system library functions. It is unwise to refer to or test the ! 634: definition of this macro unless you make very sure that programs will ! 635: execute with the same effect regardless. ! 636: ! 637: `__CHAR_UNSIGNED__' ! 638: This macro is defined if and only if the data type `char' is ! 639: unsigned on the target machine. It exists to cause the standard ! 640: header file `limit.h' to work correctly. It is bad practice ! 641: to refer to this macro yourself; instead, refer to the standard ! 642: macros defined in `limit.h'. 1.1 root 643: 644: 1.1.1.2 ! root 645: File: cpp.info Node: Nonstandard Predefined, Prev: Standard Predefined, Up: Predefined 1.1 root 646: 647: Nonstandard Predefined Macros 648: ............................. 649: 650: The C preprocessor normally has several predefined macros that vary between 651: machines because their purpose is to indicate what type of system and 652: machine is in use. This manual, being for all systems and machines, cannot 653: tell you exactly what their names are; instead, we offer a list of some 654: typical ones. 655: 656: Some nonstandard predefined macros describe the operating system in use, 657: with more or less specificity. For example, 658: 659: `unix' 660: `unix' is normally predefined on all Unix systems. 661: 662: `BSD' 663: `BSD' is predefined on recent versions of Berkeley Unix 664: (perhaps only in version 4.3). 665: 666: Other nonstandard predefined macros describe the kind of CPU, with more or 667: less specificity. For example, 668: 669: `vax' 670: `vax' is predefined on Vax computers. 671: 672: `mc68000' 1.1.1.2 ! root 673: `mc68000' is predefined on most computers whose CPU is a Motorola ! 674: 68000, 68010 or 68020. 1.1 root 675: 676: `m68k' 1.1.1.2 ! root 677: `m68k' is also predefined on most computers whose CPU is a 68000, 1.1 root 678: 68010 or 68020; however, some makers use `mc68000' and some use 1.1.1.2 ! root 679: `m68k'. Some predefine both names. What happens in GNU C ! 680: depends on the system you are using it on. 1.1 root 681: 682: `M68020' 683: `M68020' has been observed to be predefined on some systems that 684: use 68020 CPUs---in addition to `mc68000' and `m68k' that 685: are less specific. 1.1.1.2 ! root 686: ! 687: `ns32000' ! 688: `ns32000' is predefined on computers which use the National ! 689: Semiconductor 32000 series CPU. 1.1 root 690: 691: Yet other nonstandard predefined macros describe the manufacturer of 692: the system. For example, 693: 694: `sun' 695: `sun' is predefined on all models of Sun computers. 696: 697: `pyr' 1.1.1.2 ! root 698: `pyr' is predefined on all models of Pyramid computers. ! 699: ! 700: `sequent' ! 701: `sequent' is predefined on all models of Sequent computers. 1.1 root 702: 703: These predefined symbols are not only nonstandard, they are contrary to the 704: ANSI standard because their names do not start with underscores. However, 705: the GNU C preprocessor would be useless if it did not predefine the same 706: names that are normally predefined on the system and machine you are using. 707: Even system header files check the predefined names and will generate 708: incorrect declarations if they do not find the names that are expected. 709: 1.1.1.2 ! root 710: The set of nonstandard predefined names in the GNU C preprocessor is ! 711: controlled by the macro `CPP_PREDEFINES', which should be a string ! 712: containing `-D' options, separated by spaces. For example, on the Sun, ! 713: the definition ! 714: ! 715: #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" ! 716: ! 717: is used. ! 718: ! 719: The `-ansi' option which requests complete support for ANSI C ! 720: inhibits the definition of these predefined symbols. 1.1 root 721: 722: 1.1.1.2 ! root 723: File: cpp.info Node: Stringification, Prev: Predefined, Up: Macros, Next: Concatenation 1.1 root 724: 725: Stringification 726: --------------- 727: 1.1.1.2 ! root 728: "Stringification" means turning a code fragment into a string constant 1.1 root 729: whose contents are the text for the code fragment. For example, 730: stringifying `foo (z)' results in `"foo (z)"'. 731: 732: In the C preprocessor, stringification is an option available when macro 733: arguments are substituted into the macro definition. In the body of the 734: definition, when an argument name appears, the character `#' before 735: the name specifies stringification of the corresponding actual argument 736: when it is substituted at that point in the definition. The same argument 737: may be substituted in other places in the definition without 738: stringification if the argument name appears in those places with no 739: `#'. 740: 741: Here is an example of a macro definition that uses stringification: 742: 743: #define WARN_IF(EXP) \ 744: do { if (EXP) fprintf (stderr, "Warning: " #EXP "\n"); } while (0) 745: 746: Here the actual argument for `EXP' is substituted once as given, 747: into the `if' statement, and once as stringified, into the 748: argument to `fprintf'. The `do' and `while (0)' are 749: a kludge to make it possible to write `WARN_IF (ARG);', 750: which the resemblance of `WARN_IF' to a function would make 751: C programmers want to do; *Note Swallow Semicolon::). 752: 753: The stringification feature is limited to transforming one macro argument 754: into one string constant: there is no way to combine the argument with 755: other text and then stringify it all together. But the example above shows 756: how an equivalent result can be obtained in ANSI Standard C using the 757: feature that adjacent string constants are concatenated as one string 758: constant. The preprocessor stringifies `EXP''s actual argument 759: into a separate string constant, resulting in text like 760: 761: do { if (x == 0) fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0) 762: 763: but the C compiler then sees three consecutive string constants and 764: concatenates them into one, producing effectively 765: 766: do { if (x == 0) fprintf (stderr, "Warning: x == 0\n"); } while (0) 767: 768: Stringification in C involves more than putting doublequote characters 769: around the fragment; it is necessary to put backslashes in front of all 770: doublequote characters, and all backslashes in string and character 771: constants, in order to get a valid C string constant with the proper 772: contents. Thus, stringifying `p = "foo\n";' results in `"p = 773: \"foo\\n\";"'. However, backslashes that are not inside of string or 774: character constants are not duplicated: `\n' by itself stringifies to 775: `"\n"'. 776: 777: Whitespace (including comments) in the text being stringified is handled 778: according to precise rules. All leading and trailing whitespace is ignored. 779: Any sequence of whitespace in the middle of the text is converted to 780: a single space in the stringified result. 781: 782: 1.1.1.2 ! root 783: File: cpp.info Node: Concatenation, Prev: Stringification, Up: Macros, Next: Undefining 1.1 root 784: 785: Concatenation 786: ------------- 787: 788: "Concatenation" means joining two strings into one. In the context 789: of macro expansion, concatenation refers to joining two lexical units 790: into one longer one. Specifically, an actual argument to the macro can be 791: concatenated with another actual argument or with fixed text to produce 792: a longer name. The longer name might be the name of a function, 793: variable or type, or a C keyword; it might even be the name of another 794: macro, in which case it will be expanded. 795: 796: When you define a macro, you request concatenation with the special 797: operator `##' in the macro body. When the macro is called, 798: after actual arguments are substituted, all `##' operators are 799: deleted, and so is any whitespace next to them (including whitespace 800: that was part of an actual argument). The result is to concatenate 801: the syntactic tokens on either side of the `##'. 802: 803: Consider a C program that interprets named commands. There probably needs 804: to be a table of commands, perhaps an array of structures declared as 805: follows: 806: 807: struct command 808: { 809: char *name; 810: void (*function) (); 811: }; 812: 813: struct command commands[] = 814: { 815: { "quit", quit_command}, 816: { "help", help_command}, 817: ... 818: }; 819: 820: It would be cleaner not to have to give each command name twice, once in 821: the string constant and once in the function name. A macro which takes the 822: name of a command as an argument can make this unnecessary. The string 823: constant can be created with stringification, and the function name by 824: concatenating the argument with `_command'. Here is how it is done: 825: 826: #define COMMAND(NAME) { #NAME, NAME ## _command } 827: 828: struct command commands[] = 829: { 830: COMMAND (quit), 831: COMMAND (help), 832: ... 833: }; 834: 835: The usual case of concatenation is concatenating two names (or a name and a 836: number) into a longer name. But this isn't the only valid case. It is 837: also possible to concatenate two numbers (or a number and a name, such as 838: `1.5' and `e3') into a number. Also, multi-character operators 839: such as `+=' can be formed by concatenation. In some cases it is even 840: possible to piece together a string constant. However, two pieces of text 841: that don't together form a valid lexical unit cannot be concatenated. For 842: example, concatenation with `x' on one side and `+' on the other 843: is not meaningful because those two characters can't fit together in any 844: lexical unit of C. The ANSI standard says that such attempts at 845: concatenation are undefined, but in the GNU C preprocessor it is well 846: defined: it puts the `x' and `+' side by side with no particular 847: special results. 848: 849: Keep in mind that the C preprocessor converts comments to whitespace before 850: macros are even considered. Therefore, you cannot create a comment by 851: concatenating `/' and `*': the `/*' sequence that starts a 852: comment is not a lexical unit, but rather the beginning of a "long" space 853: character. Also, you can freely use comments next to a `##' in a 854: macro definition, or in actual arguments that will be concatenated, because 855: the comments will be converted to spaces at first sight, and concatenation 856: will later discard the spaces. 857: 858: 1.1.1.2 ! root 859: File: cpp.info Node: Undefining, Prev: Concatenation, Up: Macros, Next: Redefining 1.1 root 860: 861: Undefining Macros 862: ----------------- 863: 864: To "undefine" a macro means to cancel its definition. This is done 865: with the `#undef' command. `#undef' is followed by the macro 866: name to be undefined. 867: 868: Like definition, undefinition occurs at a specific point in the source 869: file, and it applies starting from that point. The name ceases to be a 870: macro name, and from that point on it is treated by the preprocessor as if 871: it had never been a macro name. 872: 873: For example, 874: 875: #define FOO 4 876: x = FOO; 877: #undef FOO 878: x = FOO; 879: 880: expands into 881: 882: x = 4; 883: 884: x = FOO; 885: 886: In this example, `FOO' had better be a variable or function as well 887: as (temporarily) a macro, in order for the result of the expansion to be 888: valid C code. 889: 890: The same form of `#undef' command will cancel definitions with 891: arguments or definitions that don't expect arguments. The `#undef' 892: command has no effect when used on a name not currently defined as a macro. 893: 894: 1.1.1.2 ! root 895: File: cpp.info Node: Redefining, Prev: Undefining, Up: Macros, Next: Macro Pitfalls 1.1 root 896: 897: Redefining Macros 898: ----------------- 899: 900: "Redefining" a macro means defining (with `#define') a name that 901: is already defined as a macro. 902: 903: A redefinition is trivial if the new definition is transparently identical 904: to the old one. You probably wouldn't deliberately write a trivial 905: redefinition, but they can happen automatically when a header file is 906: included more than once (*Note Header Files::), so they are accepted 907: silently and without effect. 908: 909: Nontrivial redefinition is considered likely to be an error, so 910: it provokes a warning message from the preprocessor. However, sometimes it 911: is useful to change the definition of a macro in mid-compilation. You can 912: inhibit the warning by undefining the macro with `#undef' before the 913: second definition. 914: 915: In order for a reefinition to be trivial, the new definition must exactly match 916: the one already in effect, with two possible exceptions: 917: 918: * Whitespace may be added or deleted at the beginning or the end. 919: 920: * Whitespace may be changed in the middle (but not inside strings). 921: However, it may not be eliminated entirely, and it may not be added 922: where there was no whitespace at all. 923: 924: Recall that a comment counts as whitespace. 925: 926: 1.1.1.2 ! root 927: File: cpp.info Node: Macro Pitfalls, Prev: Redefining, Up: Macros 1.1 root 928: 929: Pitfalls and Subtleties of Macros 930: --------------------------------- 931: 932: In this section we describe some special rules that apply to macros and 933: macro expansion, and point out certain cases in which the rules have 934: counterintuitive consequences that you must watch out for. 935: 936: * Menu: 937: 938: * Misnesting:: Macros can contain unmatched parentheses. 939: * Macro Parentheses:: Why apparently superfluous parentheses 940: may be necessary to avoid incorrect grouping. 941: * Swallow Semicolon:: Macros that look like functions 942: but expand into compound statements. 943: * Side Effects:: Unsafe macros that cause trouble when 944: arguments contain side effects. 945: * Self-Reference:: Macros whose definitions use the macros' own names. 946: * Argument Prescan:: Actual arguments are checked for macro calls 947: before they are substituted. 948: * Cascaded Macros:: Macros whose definitions use other macros. 949: 950: 1.1.1.2 ! root 951: File: cpp.info Node: Misnesting, Prev: Macro Pitfalls, Up: Macro Pitfalls, Next: Macro Parentheses 1.1 root 952: 953: Improperly Nested Constructs 954: ............................ 955: 956: Recall that when a macro is called with arguments, the arguments are 957: substituted into the macro body and the result is checked, together with 958: the rest of the input file, for more macro calls. 959: 960: It is possible to piece together a macro call coming partially from the 961: macro body and partially from the actual arguments. For example, 962: 963: #define double(x) (2*(x)) 964: #define call_with_1(x) x(1) 965: 966: would expand `call_with_1 (double)' into `(2*(1))'. 967: 968: Macro definitions do not have to have balanced parentheses. By writing an 969: unbalanced open parenthesis in a macro body, it is possible to create a 970: macro call that begins inside the macro body but ends outside of it. For 971: example, 972: 973: #define strange(file) fprintf (file, "%s %d", 974: ... 975: strange(stderr) p, 35) 976: 977: This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'! 978: 979: 1.1.1.2 ! root 980: File: cpp.info Node: Macro Parentheses, Prev: Misnesting, Up: Macro Pitfalls, Next: Swallow Semicolon 1.1 root 981: 982: Unintended Grouping of Arithmetic 983: ................................. 984: 985: You may have noticed that in most of the macro definition examples shown 986: above, each occurrence of a macro argument name had parentheses around it. 987: In addition, another pair of parentheses usually surround the entire macro 988: definition. Here is why it is best to write macros that way. 989: 990: Suppose you define a macro as follows 991: 992: #define ceil_div(x, y) (x + y - 1) / y 993: 994: whose purpose is to divide, rounding up. (One use for this 995: operation is to compute how many `int''s are needed to hold 996: a certain number of `char''s.) Then suppose it is used as follows: 997: 998: a = ceil_div (b & c, sizeof (int)); 999: 1000: This expands into 1001: 1002: a = (b & c + sizeof (int) - 1) / sizeof (int); 1003: 1.1.1.2 ! root 1004: which does not do what is intended. The operator-precedence rules of ! 1005: C make it equivalent to this: 1.1 root 1006: 1007: a = (b & (c + sizeof (int) - 1)) / sizeof (int); 1008: 1.1.1.2 ! root 1009: But what we want is this: 1.1 root 1010: 1011: a = ((b & c) + sizeof (int) - 1)) / sizeof (int); 1012: 1013: Defining the macro as 1014: 1015: #define ceil_div(x, y) ((x) + (y) - 1) / (y) 1016: 1017: provides the desired result. 1018: 1019: However, unintended grouping can result in another way. Consider 1020: `sizeof ceil_div(1, 2)'. That has the appearance of a C expression 1021: that would compute the size of the type of `ceil_div (1, 2)', but in 1022: fact it means something very different. Here is what it expands to: 1023: 1024: sizeof ((1) + (2) - 1) / (2) 1025: 1026: This would take the size of an integer and divide it by two. The precedence 1027: rules have put the division outside the `sizeof' when it was intended 1028: to be inside. 1029: 1030: Parentheses around the entire macro definition can prevent such problems. 1031: Here, then, is the recommended way to define `ceil_div': 1032: 1033: #define ceil_div(x, y) (((x) + (y) - 1) / (y)) 1034: 1035: 1.1.1.2 ! root 1036: File: cpp.info Node: Swallow Semicolon, Prev: Macro Parentheses, Up: Macro Pitfalls, Next: Side Effects 1.1 root 1037: 1038: Swallowing the Semicolon 1039: ........................ 1040: 1041: Often it is desirable to define a macro that expands into a compound 1042: statement. Consider, for example, the following macro, that advances a 1043: pointer (the argument `p' says where to find it) across whitespace 1044: characters: 1045: 1046: #define SKIP_SPACES (p, limit) \ 1047: { register char *lim = (limit); \ 1048: while (p != lim) { \ 1049: if (*p++ != ' ') { \ 1050: p--; break; }}} 1051: 1052: Here Backslash-Newline is used to split the macro definition, which must 1053: be a single line, so that it resembles the way such C code would be 1054: layed out if not part of a macro definition. 1055: 1056: A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly 1057: speaking, the call expands to a compound statement, which is a complete 1058: statement with no need for a semicolon to end it. But it looks like a 1059: function call. So it minimizes confusion if you can use it like a function 1060: call, writing a semicolon afterward, as in `SKIP_SPACES (p, lim);' 1061: 1062: But this can cause trouble before `else' statements, because the 1063: semicolon is actually a null statement. Suppose you write 1064: 1065: if (*p != 0) 1066: SKIP_SPACES (p, lim); 1067: else ... 1068: 1069: The presence of two statements---the compound statement and a null 1070: statement---in between the `if' condition and the `else' 1071: makes invalid C code. 1072: 1073: The definition of the macro `SKIP_SPACES' can be altered to solve 1074: this problem, using a `do ... while' statement. Here is how: 1075: 1076: #define SKIP_SPACES (p, limit) \ 1077: do { register char *lim = (limit); \ 1078: while (p != lim) { \ 1079: if (*p++ != ' ') { \ 1080: p--; break; }}} \ 1081: while (0) 1082: 1083: Now `SKIP_SPACES (p, lim);' expands into 1084: 1085: do {...} while (0); 1086: 1087: which is one statement. 1088: 1089: 1.1.1.2 ! root 1090: File: cpp.info Node: Side Effects, Prev: Swallow Semicolon, Up: Macro Pitfalls, Next: Self-Reference 1.1 root 1091: 1092: Duplication of Side Effects 1093: ........................... 1094: 1.1.1.2 ! root 1095: Many C programs define a macro `min', for "minimum", like this: 1.1 root 1096: 1097: #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1.1.1.2 ! root 1098: ! 1099: When you use this macro with an argument containing a side effect, ! 1100: as shown here, ! 1101: 1.1 root 1102: next = min (x + y, foo (z)); 1103: 1.1.1.2 ! root 1104: it expands as follows: 1.1 root 1105: 1106: next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 1107: 1108: where `x + y' has been substituted for `X' and `foo (z)' 1109: for `Y'. 1110: 1111: The function `foo' is used only once in the statement as it appears 1112: in the program, but the expression `foo (z)' has been substituted 1113: twice into the macro expansion. As a result, `foo' might be called 1114: two times when the statement is executed. If it has side effects or 1115: if it takes a long time to compute, the results might not be what you 1116: intended. We say that `min' is an "unsafe" macro. 1117: 1.1.1.2 ! root 1118: The best solution to this problem is to define `min' in a way that ! 1119: computes the value of `foo (z)' only once. The C language offers no ! 1120: way standard way to do this, but it can be done with GNU C extensions as ! 1121: follows: ! 1122: ! 1123: #define min(X, Y) \ ! 1124: ({ typeof (X) __x = (X), __y = (Y); \ ! 1125: (__x < __y) ? __x : __y; }) ! 1126: ! 1127: If you do not wish to use GNU C extensions, the only solution is to be ! 1128: careful when *using* the macro `min'. For example, you can ! 1129: calculate the value of `foo (z)', save it in a variable, and use that ! 1130: variable in `min': 1.1 root 1131: 1132: #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1133: ... 1134: { 1135: int tem = foo (z); 1136: next = min (x + y, tem); 1137: } 1138: 1139: (where I assume that `foo' returns type `int'). 1140: 1141: 1.1.1.2 ! root 1142: File: cpp.info Node: Self-Reference, Prev: Side Effects, Up: Macro Pitfalls, Next: Argument Prescan 1.1 root 1143: 1144: Self-Referential Macros 1145: ....................... 1146: 1147: A "self-referential" macro is one whose name appears in its definition. 1148: A special feature of ANSI Standard C is that the self-reference is not 1149: considered a macro call. It is passed into the preprocessor output 1150: unchanged. 1151: 1152: Let's consider an example: 1153: 1154: #define foo (4 + foo) 1155: 1156: where `foo' is also a variable in your program. 1157: 1158: Following the ordinary rules, each reference to `foo' will expand into 1159: `(4 + foo)'; then this will be rescanned and will expand into `(4 1160: + (4 + foo))'; and so on until it causes a fatal error (memory full) in the 1161: preprocessor. 1162: 1163: However, the special rule about self-reference cuts this process short 1164: after one step, at `(4 + foo)'. Therefore, this macro definition 1165: has the possibly useful effect of causing the program to add 4 to 1166: the value of `foo' wherever `foo' is referred to. 1167: 1168: In most cases, it is a bad idea to take advantage of this feature. 1169: A person reading the program who sees that `foo' is a variable will 1170: not expect that it is a macro as well. The reader will come across a 1171: the identifier `foo' in the program and think its value should be 1172: that of the variable `foo', whereas in fact the value is four 1173: greater. 1174: 1175: The special rule for self-reference applies also to "indirect" 1176: self-reference. This is the case where a macro X expands to use a 1177: macro `y', and `y''s expansion refers to the macro `x'. The 1178: resulting reference to `x' comes indirectly from the expansion of 1179: `x', so it is a self-reference and is not further expanded. Thus, 1180: after 1181: 1182: #define x (4 + y) 1183: #define y (2 * x) 1184: 1185: `x' would expand into `(4 + (2 * x))'. Clear? 1186: 1187: But suppose `y' is used elsewhere, not from the definition of `x'. 1188: Then the use of `x' in the expansion of `y' is not a self-reference 1189: because `x' is not "in progress". So it does expand. However, 1190: the expansion of `x' contains a reference to `y', and that 1191: is an indirect self-reference now because `y' is "in progress". 1192: The result is that `y' expands to `(2 * (4 + y))'. 1193: 1194: It is not clear that this behavior would ever be useful, but it is specified 1195: by the ANSI C standard, so you need to understand it. 1196: 1197: 1.1.1.2 ! root 1198: File: cpp.info Node: Argument Prescan, Prev: Self-Reference, Up: Macro Pitfalls, Next: Cascaded Macros 1.1 root 1199: 1200: Separate Expansion of Macro Arguments 1201: ..................................... 1202: 1203: We have explained that the expansion of a macro, including the substituted 1204: actual arguments, is scanned over again for macro calls to be expanded. 1205: 1206: What really happens is more subtle: first each actual argument text is scanned 1207: separately for macro calls. Then the results of this are substituted into 1208: the macro body to produce the macro expansion, and the macro expansion 1209: is scanned again for macros to expand. 1210: 1211: The result is that the actual arguments are scanned *twice* to expand 1212: macro calls in them. 1213: 1214: Most of the time, this has no effect. If the actual argument contained 1215: any macro calls, they are expanded during the first scan. The result 1216: therefore contains no macro calls, so the second scan does not change it. 1217: If the actual argument were substituted as given, with no prescan, 1218: the single remaining scan would find the same macro calls and produce 1219: the same results. 1220: 1221: You might expect the double scan to change the results when a 1222: self-referential macro is used in an actual argument of another macro 1223: (*Note Self-Reference::): the self-referential macro would be expanded once 1224: in the first scan, and a second time in the second scan. But this is not 1225: what happens. The self-references that do not expand in the first scan are 1226: marked so that they will not expand in the second scan either. 1227: 1228: The prescan is not done when an argument is stringified or concatenated. 1229: (More precisely, stringification and concatenation use the argument as 1230: written, in un-prescanned form. The same actual argument would be used in 1231: prescanned form if it is substituted elsewhere without stringification or 1232: concatenation.) Thus, 1233: 1234: #define str(s) #s 1235: #define foo 4 1236: str (foo) 1237: 1238: expands to `"foo"'. Once more, prescan has been prevented from 1239: having any noticeable effect. 1240: 1241: You might now ask, "Why mention the prescan, if it makes no difference? 1242: Why not skip it and make the preprocessor faster?" The answer is that the 1243: prescan does make a difference in two special cases: 1244: 1245: * Nested calls to a macro. 1246: 1247: * Macros that call other macros that stringify or concatenate. 1248: 1249: We say that "nested" calls to a macro occur when a macro's actual 1250: argument contains a call to that very macro. For example, if `f' 1251: is a macro that expects one argument, `f (f (1))' is a nested 1252: pair of calls to `f'. The desired expansion is made by 1253: expanding `f (1)' and substituting that into the definition of 1254: `f'. The prescan causes the expected result to happen. 1255: Without the prescan, `f (1)' itself would be substituted as 1256: an actual argument, and the inner use of `f' would appear 1257: during the main scan as an indirect self-reference and would not 1258: be expanded. Here, the prescan cancels an undesirable side effect 1259: (in the medical, not computational, sense of the term) of the special 1260: rule for self-referential macros. 1261: 1262: There is also one case where prescan is useful. It is possible 1263: to use prescan to expand an argument and then stringify it---if you use 1264: two levels of macros. Let's add a new macro `xstr' to the 1265: example shown above: 1266: 1267: #define xstr(s) str(s) 1268: #define str(s) #s 1269: #define foo 4 1270: xstr (foo) 1271: 1272: This expands into `"4"', not `"foo"'. The reason for the 1273: difference is that the argument of `xstr' is expanded at prescan 1274: (because `xstr' does not specify stringification or concatenation of 1275: the argument). The result of prescan then forms the actual argument for 1276: `str'. `str' uses its argument without prescan because it 1277: performs strigification; but it cannot prevent or undo the prescanning 1278: already done by `xstr'. 1279: 1280: 1.1.1.2 ! root 1281: File: cpp.info Node: Cascaded Macros, Prev: Argument Prescan, Up: Macro Pitfalls 1.1 root 1282: 1283: Cascaded Use of Macros 1284: ...................... 1285: 1286: A "cascade" of macros is when one macro's body contains a reference 1287: to another macro. This is very common practice. For example, 1288: 1289: #define BUFSIZE 1020 1290: #define TABLESIZE BUFSIZE 1291: 1292: This is not at all the same as defining `TABLESIZE' to be `1020'. 1293: The `#define' for `TABLESIZE' uses exactly the body you 1294: specify---in this case, `BUFSIZE'---and does not check to see whether 1295: it too is the name of a macro. 1296: 1297: It's only when you *use* `TABLESIZE' that the result of its expansion 1298: is checked for more macro names. 1299: 1300: This makes a difference if you change the definition of `BUFSIZE' 1301: at some point in the source file. `TABLESIZE', defined as shown, 1302: will always expand using the definition of `BUFSIZE' that is 1303: currently in effect: 1304: 1305: #define BUFSIZE 1020 1306: #define TABLESIZE BUFSIZE 1307: #undef BUFSIZE 1308: #define BUFSIZE 37 1309: 1310: Now `TABLESIZE' expands (in two stages) to `37'. 1311: 1312: 1.1.1.2 ! root 1313: File: cpp.info Node: Conditionals, Prev: Macros, Up: Top, Next: Combining Sources 1.1 root 1314: 1315: Conditionals 1316: ============ 1317: 1318: In a macro processor, a "conditional" is a command that allows a part 1319: of the program to be ignored during compilation, on some conditions. 1320: In the C preprocessor, a conditional can test either an arithmetic expression 1321: or whether a name is defined as a macro. 1322: 1323: A conditional in the C preprocessor resembles in some ways an `if' 1324: statement in C, but it is important to understand the difference between 1325: them. The condition in an `if' statement is tested during the execution 1326: of your program. Its purpose is to allow your program to behave differently 1327: from run to run, depending on the data it is operating on. The condition 1328: in a preprocessor conditional command is tested when your program is compiled. 1329: Its purpose is to allow different code to be included in the program depending 1330: on the situation at the time of compilation. 1331: 1332: * Menu: 1333: 1334: * Uses: Conditional Uses. What conditionals are for. 1335: * Syntax: Conditional Syntax. How conditionals are written. 1336: * Deletion: Deleted Code. Making code into a comment. 1337: * Macros: Conditionals-Macros. Why conditionals are used with macros. 1338: * Errors: #error Command. Detecting inconsistent compilation parameters. 1339: 1340: 1.1.1.2 ! root 1341: File: cpp.info Node: Conditional Uses, Prev: Conditionals, Up: Conditionals, Next: Conditional Syntax 1.1 root 1342: Generally there are three kinds of reason to use a conditional. 1343: 1344: * A program may need to use different code depending on the machine or 1345: operating system it is to run on. In some cases the code for one 1346: operating system may be erroneous on another operating system; for 1347: example, it might refer to library routines that do not exist on the 1348: other system. When this happens, it is not enough to avoid executing 1349: the invalid code: merely having it in the program makes it impossible 1350: to link the program and run it. With a preprocessor conditional, the 1351: offending code can be effectively excised from the program when it is 1352: not valid. 1353: 1354: * You may want to be able to compile the same source file into two 1355: different programs. Sometimes the difference between the programs is 1356: that one makes frequent time-consuming consistency checks on its 1357: intermediate data while the other does not. 1358: 1359: * A conditional whose condition is always false is a good way to exclude 1360: code from the program but keep it as a sort of comment for future 1361: reference. 1362: 1363: Most simple programs that are intended to run on only one machine will 1364: not need to use preprocessor conditionals. 1365: 1366: 1.1.1.2 ! root 1367: File: cpp.info Node: Conditional Syntax, Prev: Conditional Uses, Up: Conditionals, Next: Conditionals-Macros 1.1 root 1368: 1369: Syntax of Conditionals 1370: ---------------------- 1371: 1372: A conditional in the C preprocessor begins with a "conditional 1373: command": `#if', `#ifdef' or `#ifndef'.*Note Conditionals::, 1374: for info on `#ifdef' and `#ifndef'; only `#if' is explained 1375: here. 1376: 1377: * Menu: 1378: 1379: * If: #if Command. Basic conditionals using `#if' and `#endif'. 1380: * Else: #else Command. Including some text if the condition fails. 1381: * Elif: #elif Command. Testing several alternative possibilities. 1382: 1383: 1.1.1.2 ! root 1384: File: cpp.info Node: #if Command, Prev: Conditional Syntax, Up: Conditional Syntax, Next: #else Command 1.1 root 1385: 1386: The `#if' Command 1387: ................. 1388: 1389: The `#if' command in its simplest form consists of 1390: 1391: #if EXPRESSION 1392: CONTROLLED TEXT 1393: #endif /* EXPRESSION */ 1394: 1395: The comment following the `#endif' is not required, but it is a good 1396: practice because it helps people match the `#endif' to the 1397: corresponding `#if'. Such comments should always be used, except in 1398: short conditionals that are not nested. In fact, you can put anything at 1399: all after the `#endif' and it will be ignored by the GNU C preprocessor, 1400: but only comments are acceptable in ANSI Standard C. 1401: 1402: EXPRESSION is a C expression of integer type, subject to stringent 1403: restrictions. It may contain 1404: 1405: * Integer constants, which are all regarded as `long' or 1406: `unsigned long'. 1407: 1408: * Character constants, which are interpreted according to the character 1409: set and conventions of the machine and operating system on which the 1410: preprocessor is running. The GNU C preprocessor uses the C data type 1411: `char' for these character constants; therefore, whether some 1412: character codes are negative is determined by the C compiler used to 1413: compile the preprocessor. If it treats `char' as signed, then 1414: character codes large enough to set the sign bit will be considered 1415: negative; otherwise, no character code is considered negative. 1416: 1417: * Arithmetic operators for addition, subtraction, multiplication, 1418: division, bitwise operations, shifts, comparisons, and `&&' and 1419: `||'. 1420: 1421: * Identifiers that are not macros, which are all treated as zero(!). 1422: 1423: * Macro calls. All macro calls in the expression are expanded before 1424: actual computation of the expression's value begins. 1425: 1426: Note that `sizeof' operators and `enum'-type values are not allowed. 1427: `enum'-type values, like all other identifiers that are not taken 1428: as macro calls and expanded, are treated as zero. 1429: 1430: The text inside of a conditional can include preprocessor commands. Then 1431: the commands inside the conditional are obeyed only if that branch of the 1432: conditional succeeds. The text can also contain other conditional groups. 1433: However, the `#if''s and `#endif''s must balance. 1434: 1435: 1.1.1.2 ! root 1436: File: cpp.info Node: #else Command, Prev: #if Command, Up: Conditional Syntax, Next: #elif Command 1.1 root 1437: 1438: The `#else' Command 1439: ................... 1440: 1441: The `#else' command can be added a conditional to provide alternative 1442: text to be used if the condition is false. This looks like 1443: 1444: #if EXPRESSION 1445: TEXT-IF-TRUE 1446: #else /* Not EXPRESSION */ 1447: TEXT-IF-FALSE 1448: #endif /* Not EXPRESSION */ 1449: 1450: If EXPRESSION is nonzero, and the TEXT-IF-TRUE is considered 1451: included, then `#else' acts like a failing conditional and the 1452: TEXT-IF-FALSE is ignored. Contrariwise, if the `#if' 1453: conditional fails, the TEXT-IF-FALSE is considered included. 1454: 1455: 1.1.1.2 ! root 1456: File: cpp.info Node: #elif Command, Prev: #else Command, Up: Conditional Syntax 1.1 root 1457: 1458: The `#elif' Command 1459: ................... 1460: 1461: One common case of nested conditionals is used to check for more than two 1462: possible alternatives. For example, you might have 1463: 1464: #if X == 1 1465: ... 1466: #else /* X != 1 */ 1467: #if X == 2 1468: ... 1469: #else /* X != 2 */ 1470: ... 1471: #endif /* X != 2 */ 1472: #endif /* X != 1 */ 1473: 1474: Another conditional command, `#elif', allows this to be abbreviated 1475: as follows: 1476: 1477: #if X == 1 1478: ... 1479: #elif X == 2 1480: ... 1481: #else /* X != 2 and X != 1*/ 1482: ... 1483: #endif /* X != 2 and X != 1*/ 1484: 1485: `#elif' stands for "else if". Like `#else', it goes in the 1486: middle of a `#if'-`#endif' pair and subdivides it; it does not 1487: require a matching `#endif' of its own. Like `#if', the 1488: `#elif' command includes an expression to be tested. 1489: 1490: The text following the `#elif' is processed only if the original 1491: `#if'-condition failed and the `#elif' condition succeeeds. More 1492: than one `#elif' can go in the same `#if'-`#endif' group. 1493: Then the text after each `#elif' is processed only if the `#elif' 1494: condition succeeds after the original `#if' and any previous 1495: `#elif''s within it have failed. `#else' is equivalent to 1496: `#elif 1', and `#else' is allowed after any number of 1497: `#elif''s, but `#elif' may not follow a `#else'. 1498: 1499: 1.1.1.2 ! root 1500: File: cpp.info Node: Deleted Code, Prev: Conditional Syntax, Up: Conditionals, Next: Conditionals-Macros 1.1 root 1501: 1502: Keeping Deleted Code for Future Reference 1503: ----------------------------------------- 1504: 1505: If you replace or delete a part of the program but want to keep the old 1506: code around as a comment for future reference, the easy way to do this is 1507: to put `#if 0' before it and `#endif' after it. 1508: 1509: This works even if the code being turned off contains conditionals, but 1510: they must be entire conditionals (balanced `#if' and `#endif'). 1511: 1512: 1.1.1.2 ! root 1513: File: cpp.info Node: Conditionals-Macros, Prev: Deleted Code, Up: Conditionals, Next: #error Command 1.1 root 1514: 1515: Conditionals and Macros 1516: ----------------------- 1517: 1518: Conditionals are rarely useful except in connection with macros. A 1519: `#if' command whose expression uses no macros is equivalent to 1520: `#if 1' or `#if 0'; you might as well determine which one, by 1521: computing the value of the expression yourself, and then simplify the 1522: program. But when the expression uses macros, its value can vary from 1523: compilation to compilation. 1524: 1525: For example, here is a conditional that tests the expression 1526: `BUFSIZE == 1020', where `BUFSIZE' must be a macro. 1527: 1528: #if BUFSIZE == 1020 1529: printf ("Large buffers!\n"); 1530: #endif /* BUFSIZE is large */ 1531: 1.1.1.2 ! root 1532: The special operator `defined' may be used in `#if' expressions to test ! 1533: whether a certain name is defined as a macro. Either `defined NAME' or ! 1534: `defined (NAME)' is an expression whose value is 1 if NAME is defined as ! 1535: macro at the current point in the program, and 0 otherwise. For the ! 1536: `defined' operator it makes no difference what the definition of the macro ! 1537: is; all that matters is whether there is a definition. Thus, for example, 1.1 root 1538: 1539: #if defined (vax) || defined (ns16000) 1540: 1541: would include the following code if either of the names `vax' and 1542: `ns16000' is defined as a macro. 1543: 1544: If a macro is defined and later undefined with `#undef', 1545: subsequent use of the `defined' operator will return 0, because 1546: the name is no longer defined. If the macro is defined again with 1547: another `#define', `defined' will recommence returning 1. 1548: 1549: Conditionals that test just the definedness of one name are very common, so 1550: there are two special short conditional commands for this case. They are 1551: 1552: `#ifdef NAME' 1553: is equivalent to `#if defined (NAME)'. 1554: 1555: `#ifndef NAME' 1556: is equivalent to `#if ! defined (NAME)'. 1557: 1558: Macro definitions can vary between compilations for several reasons. 1559: 1560: * Some macros are predefined on each kind of machine. For example, on a 1561: Vax, the name `vax' is a predefined macro. On other machines, it 1562: would not be defined. 1563: 1564: * Many more macros are defined by system header files. Different 1565: systems and machines define different macros, or give them different 1566: values. It is useful to test these macros with conditionals to avoid 1567: using a system feature on a machine where it is not implemented. 1568: 1569: * Macros are a common way of allowing users to customize a program for 1570: different machines or applications. For example, the macro 1571: `BUFSIZE' might be defined in a configuration file for your 1572: program that is included as a header file in each source file. You 1573: would use `BUFSIZE' in a preprocessor conditional in order to 1574: generate different code depending on the chosen configuration. 1575: 1576: * Macros can be defined or undefined with `-D' and `-U' 1.1.1.2 ! root 1577: command options when you compile the program. You can arrange to 1.1 root 1578: compile the same source file into two different programs by choosing 1579: a macro name to specify which program you want, writing conditionals 1580: to test whether or how this macro is defined, and then controlling 1.1.1.2 ! root 1581: the state of the macro with compiler command options. 1.1 root 1582: *Note Invocation::. 1583: 1584: 1.1.1.2 ! root 1585: File: cpp.info Node: #error Command, Prev: Conditionals-Macros, Up: Conditionals 1.1 root 1586: 1587: The `#error' Command 1588: -------------------- 1589: 1590: The command `#error' causes the preprocessor to report a fatal 1591: error. The rest of the line that follows `#error' is used as the 1592: error message. 1593: 1594: You would use `#error' inside of a conditional that detects a 1595: combination of parameters which you know the program does not properly 1596: support. For example, if you know that the program will not run 1597: properly on a Vax, you might write 1598: 1599: #ifdef vax 1600: #error Won't work on Vaxen. See comments at get_last_object. 1601: #endif 1602: 1603: *Note Nonstandard Predefined::, for why this works. 1604: 1605: If you have several configuration parameters that must be set up by 1606: the installation in a consistent way, you can use conditionals to detect 1607: an inconsistency and report it with `#error'. For example, 1608: 1609: #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ 1610: || HASH_TABLE_SIZE % 5 == 0 1611: #error HASH_TABLE_SIZE should not be divisible by a small prime 1612: #endif 1613: 1614: 1.1.1.2 ! root 1615: File: cpp.info Node: Combining Sources, Prev: Conditionals, Up: Top, Next: Other Commands 1.1 root 1616: 1617: Combining Source Files 1618: ====================== 1619: 1620: One of the jobs of the C preprocessor is to inform the C compiler of where 1621: each line of C code came from: which source file and which line number. 1622: 1623: C code can come from multiple source files if you use `#include'; 1624: both `#include' and the use of conditionals and macros can cause 1625: the line number of a line in the preprocessor output to be different 1626: from the line's number in the original source file. You will appreciate 1627: the value of making both the C compiler (in error messages) and symbolic 1628: debuggers such as GDB use the line numbers in your source file. 1629: 1630: The C preprocessor builds on this feature by offering a command by which 1631: you can control the feature explicitly. This is useful when a file for 1632: input to the C preprocessor is the output from another program such as the 1633: `bison' parser generator, which operates on another file that is the 1634: true source file. Parts of the output from `bison' are generated from 1635: scratch, other parts come from a standard parser file. The rest are copied 1636: nearly verbatim from the source file, but their line numbers in the 1637: `bison' output are not the same as their original line numbers. 1638: Naturally you would like compiler error messages and symbolic debuggers to 1639: know the original source file and line number of each line in the 1640: `bison' output. 1641: 1642: `bison' arranges this by writing `#line' commands into the output 1643: file. `#line' is a command that specifies the original line number 1644: and source file name for subsequent input in the current preprocessor input 1645: file. `#line' has three variants: 1646: 1647: `#line LINENUM' 1648: Here LINENUM is a decimal integer constant. This specifies that 1649: the line number of the following line of input, in its original source file, 1650: was LINENUM. 1651: 1652: `#line LINENUM FILENAME' 1653: Here LINENUM is a decimal integer constant and FILENAME 1654: is a string constant. This specifies that the following line of input 1655: came originally from source file FILENAME and its line number there 1656: was LINENUM. Keep in mind that FILENAME is not just a 1.1.1.2 ! root 1657: file name; it is surrounded by doublequote characters so that it looks ! 1658: like a string constant. 1.1 root 1659: 1660: `#line ANYTHING ELSE' 1661: ANYTHING ELSE is checked for macro calls, which are expanded. 1662: The result should be a decimal integer constant followed optionally 1663: by a string constant, as described above. 1664: 1665: `#line' commands alter the results of the `__FILE__' and 1666: `__LINE__' predefined macros from that point on. *Note Standard Predefined::. 1667: 1668: 1.1.1.2 ! root 1669: File: cpp.info Node: Other Commands, Prev: Combining Sources, Up: Top, Next: Output 1.1 root 1670: 1671: Miscellaneous Preprocessor Commands 1672: =================================== 1673: 1674: This section describes two additional preprocesor commands. They are 1675: not very useful, but are mentioned for completeness. 1676: 1677: The "null command" consists of a `#' followed by a Newline, with 1678: only whitespace (including comments) in between. A null command is 1679: understood as a preprocessor command but has no effect on the preprocessor 1680: output. The primary significance of the existence of the null command is 1681: that an input line consisting of just a `#' will produce no output, 1682: rather than a line of output containing just a `#'. Supposedly 1683: some old C programs contain such lines. 1684: 1685: The `#pragma' command is specified in the ANSI standard to have an 1686: arbitrary implementation-defined effect. In the GNU C preprocessor, 1687: `#pragma' first attempts to run the game `rogue'; if that fails, 1688: it tries to run the game `hack'; if that fails, it tries to run 1689: GNU Emacs displaying the Tower of Hanoi; if that fails, it reports a 1690: fatal error. In any case, preprocessing does not continue. 1691: 1692: 1.1.1.2 ! root 1693: File: cpp.info Node: Output, Prev: Other Commands, Up: Top, Next: Invocation 1.1 root 1694: 1695: C Preprocessor Output 1696: ===================== 1697: 1698: The output from the C preprocessor looks much like the input, except 1699: that all preprocessor command lines have been replaced with blank lines 1700: and all comments with spaces. Whitespace within a line is not altered; 1701: however, a space is inserted after the expansions of most macro calls. 1702: 1703: Source file name and line number information is conveyed by lines of 1704: the form 1705: 1706: # LINENUM FILENAME 1707: 1708: which are inserted as needed into the middle of the input (but never within 1709: a string or character constant). Such a line means that the following line 1710: originated in file FILENAME at line LINENUM. 1711: 1712: 1.1.1.2 ! root 1713: File: cpp.info Node: Invocation, Prev: Output, Up: Top 1.1 root 1714: 1715: Invoking the C Preprocessor 1716: =========================== 1717: 1718: Most often when you use the C preprocessor you will not have to invoke it 1719: explicitly: the C compiler will do so automatically. However, the 1720: preprocessor is sometimes useful individually. 1721: 1722: The C preprocessor expects two file names as arguments, INFILE and 1723: OUTFILE. The preprocessor reads INFILE together with any other 1724: files it specifies with `#include'. All the output generated by the 1725: combined input files is written in OUTFILE. 1726: 1727: Either INFILE or OUTFILE may be `-', which as INFILE 1728: means to read from standard input and as OUTFILE means to write to 1729: standard output. Also, if OUTFILE or both file names are omitted, 1730: the standard output and standard input are used for the omitted file names. 1731: 1.1.1.2 ! root 1732: Here is a table of command options accepted by the C preprocessor. Most 1.1 root 1733: of them can also be given when compiling a C program; they are passed along 1734: automatically to the preprocessor when it is invoked by the compiler. 1735: 1736: `-P' 1737: Inhibit generation of `#'-lines with line-number information in 1738: the output from the preprocessor (*Note Output::). This might be 1739: useful when running the preprocessor on something that is not C code 1740: and will be sent to a program which might be confused by the 1741: `#'-lines 1742: 1743: `-C' 1744: Do not discard comments: pass them through to the output file. 1745: Comments appearing in arguments of a macro call will be copied to the 1746: output before the expansion of the macro call. 1747: 1748: `-T' 1749: Process ANSI standard trigraph sequences. These are three-character 1750: sequences, all starting with `??', that are defined by ANSI C to 1751: stand for single characters. For example, `??/' stands for 1752: `\', so `'??/n'' is a character constant for Newline. 1753: Strictly speaking, the GNU C preprocessor does not support all 1.1.1.2 ! root 1754: programs in ANSI Standard C unless `-T' is used, but if you 1.1 root 1755: ever notice the difference it will be with relief. 1756: 1757: You don't want to know any more about trigraphs. 1758: 1759: `-pedantic' 1760: Issue warnings required by the ANSI C standard in certain cases such 1761: as when text other than a comment follows `#else' or `#endif'. 1762: 1763: `-I DIRECTORY' 1764: Add the directory DIRECTORY to the end of the list of 1.1.1.2 ! root 1765: directories to be searched for header files (*Note Include Syntax::). ! 1766: This can be used to override a system header file, substituting your ! 1767: own version, since these directories are searched before the system ! 1768: header file directories. If you use more than one `-I' option, ! 1769: the directories are scanned in left-to-right order; the standard ! 1770: system directories come after. 1.1 root 1771: 1772: `-D NAME' 1773: Predefine NAME as a macro, with definition `1'. 1774: 1775: `-D NAME=DEFINITION' 1776: Predefine NAME as a macro, with definition DEFINITION. 1777: There are no restrictions on the contents of DEFINITION, but if 1778: you are invoking the preprocessor from a shell or shell-like program 1779: you may need to use the shell's quoting syntax to protect characters 1780: such as spaces that have a meaning in the shell syntax. 1781: 1782: `-U NAME' 1783: Do not predefine NAME. If both `-U' and `-D' are 1784: specified for one name, the `-U' beats the `-D' and the name 1785: is not predefined. 1786: 1787: `-undef' 1788: Do not predefine any nonstandard macros. 1789: 1790: `-d' 1791: Instead of outputting the result of preprocessing, output a list of 1792: `#define' commands for all the macros defined during the 1793: execution of the preprocessor. 1794: 1.1.1.2 ! root 1795: `-M' ! 1796: Instead of outputting the result of preprocessing, output a rule ! 1797: suitable for `make' describing the dependencies of the main ! 1798: source file. The preprocessor outputs one `make' rule containing ! 1799: the object file name for that source file, a colon, and the names of ! 1800: all the included files. If there are many included files then the ! 1801: rule is split into several lines using `\'-newline. ! 1802: ! 1803: This feature is used in automatic updating of makefiles. ! 1804: ! 1805: `-MM' ! 1806: Like `-M' but mention only the files included with `#include ! 1807: "FILE"'. System header files included with `#include ! 1808: <FILE>' are omitted. ! 1809: 1.1 root 1810: `-i FILE' 1811: Process FILE as input, discarding the resulting output, before 1812: processing the regular input file. Because the output generated from 1813: FILE is discarded, the only effect of `-i FILE' is to 1814: make the macros defined in FILE available for use in the main 1815: input. 1816: 1817: 1.1.1.2 ! root 1818: File: cpp.info Node: Concept Index, Prev: Invocation, Up: Top, Next: Index 1.1 root 1819: 1820: Concept Index 1821: ************* 1822: 1823: * Menu: 1824: 1825: * cascaded macros: Cascaded Macros. 1826: * commands: Commands. 1827: * concatenation: Concatenation. 1828: * conditionals: Conditionals. 1829: * header file: Header Files. 1830: * line control: Combining Sources. 1831: * macro body uses macro: Cascaded Macros. 1832: * null command: Other Commands. 1.1.1.2 ! root 1833: * options: Invocation. 1.1 root 1834: * output format: Output. 1835: * predefined macros: Predefined. 1836: * preprocessor commands: Commands. 1837: * redefining macros: Redefining. 1838: * self-reference: Self-Reference. 1839: * semicolons (after macro calls): Swallow Semicolon. 1840: * side effects (in macro arguments): Side Effects. 1841: * stringification: Stringification. 1842: * undefining macros: Undefining. 1843: * unsafe macros: Side Effects. 1844: 1845: 1.1.1.2 ! root 1846: File: cpp.info Node: Index, Prev: Concept Index, Up: Top 1.1 root 1847: 1.1.1.2 ! root 1848: Index of Commands, Macros and Options ! 1849: ************************************* 1.1 root 1850: 1851: * Menu: 1852: 1.1.1.2 ! root 1853: * BSD: Nonstandard Predefined. ! 1854: * -C: Invocation. ! 1855: * -D: Invocation. ! 1856: * -d: Invocation. ! 1857: * __DATE__: Standard Predefined. ! 1858: * defined: Conditionals-Macros. 1.1 root 1859: * #elif: #elif Command. 1860: * #else: #else Command. 1861: * #error: #error Command. 1.1.1.2 ! root 1862: * __FILE__: Standard Predefined. ! 1863: * -I: Invocation. ! 1864: * -i: Invocation. 1.1 root 1865: * #if: Conditional Syntax. 1866: * #ifdef: Conditionals-Macros. 1867: * #ifndef: Conditionals-Macros. 1868: * #include: Include Syntax. 1869: * #line: Combining Sources. 1.1.1.2 ! root 1870: * __LINE__: Standard Predefined. ! 1871: * -M: Invocation. 1.1 root 1872: * M68020: Nonstandard Predefined. 1873: * m68k: Nonstandard Predefined. 1874: * mc68000: Nonstandard Predefined. 1.1.1.2 ! root 1875: * -MM: Invocation. ! 1876: * ns32000: Nonstandard Predefined. ! 1877: * -P: Invocation. ! 1878: * -pedantic: Invocation. ! 1879: * #pragma: Other Commands. 1.1 root 1880: * pyr: Nonstandard Predefined. 1.1.1.2 ! root 1881: * sequent: Nonstandard Predefined. ! 1882: * __STDC__: Standard Predefined. 1.1 root 1883: * sun: Nonstandard Predefined. 1884: * system header files: Header Uses. 1.1.1.2 ! root 1885: * -T: Invocation. ! 1886: * __TIME__: Standard Predefined. ! 1887: * -U: Invocation. ! 1888: * -undef: Invocation. 1.1 root 1889: * unix: Nonstandard Predefined. 1890: * vax: Nonstandard Predefined. 1891: 1892: 1893: Tag table: 1.1.1.2 ! root 1894: Node: Top742 ! 1895: Node: Global Actions3291 ! 1896: Node: Commands5797 ! 1897: Node: Header Files7393 ! 1898: Node: Header Uses7728 ! 1899: Node: Include Syntax9114 ! 1900: Node: Include Operation11866 ! 1901: Node: Macros13510 ! 1902: Node: Simple Macros14417 ! 1903: Node: Argument Macros17455 ! 1904: Node: Predefined22546 ! 1905: Node: Standard Predefined22969 ! 1906: Node: Nonstandard Predefined27054 ! 1907: Node: Stringification29853 ! 1908: Node: Concatenation32685 ! 1909: Node: Undefining35937 ! 1910: Node: Redefining36954 ! 1911: Node: Macro Pitfalls38238 ! 1912: Node: Misnesting39278 ! 1913: Node: Macro Parentheses40279 ! 1914: Node: Swallow Semicolon42126 ! 1915: Node: Side Effects44012 ! 1916: Node: Self-Reference45694 ! 1917: Node: Argument Prescan47932 ! 1918: Node: Cascaded Macros51637 ! 1919: Node: Conditionals52654 ! 1920: Node: Conditional Uses53935 ! 1921: Node: Conditional Syntax55267 ! 1922: Node: #if Command55829 ! 1923: Node: #else Command58086 ! 1924: Node: #elif Command58724 ! 1925: Node: Deleted Code60059 ! 1926: Node: Conditionals-Macros60585 ! 1927: Node: #error Command63826 ! 1928: Node: Combining Sources64867 ! 1929: Node: Other Commands67499 ! 1930: Node: Output68634 ! 1931: Node: Invocation69347 ! 1932: Node: Concept Index73904 ! 1933: Node: Index74667 1.1 root 1934: 1935: End tag table
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.