![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info-1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cpp.info-1 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.3 ! root 1: This is Info file cpp.info, produced by Makeinfo-1.54 from the input 1.1.1.2 root 2: file cpp.texi. 1.1 root 3: 4: This file documents the GNU C Preprocessor. 5: 1.1.1.3 ! root 6: Copyright 1987, 1989, 1991, 1992, 1993 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 1.1.1.3 ! root 28: by the C compiler to transform your program before actual compilation. 1.1.1.2 root 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 `#'. 1.1.1.3 ! root 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. 1.1.1.3 ! root 161: For example, `#define' must be followed by a macro name and the 1.1.1.2 root 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.3 ! root 165: circumstances. It may be split cosmetically with Backslash-Newline, ! 166: but that has no effect on its meaning. Comments containing Newlines ! 167: can also divide the command into multiple lines, but the comments are 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 1.1.1.3 ! root 248: comments are not recognized within the `<...>'. Thus, in ! 249: `#include <x/*y>' the `/*' does not start a comment and the ! 250: command specifies inclusion of a system header file named `x/*y'. ! 251: Of course, a header file with such a name is unlikely to exist on 1.1.1.2 root 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 1.1.1.3 ! root 336: may not start in the included file and finish in the including file. 1.1 root 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 1.1.1.3 ! root 386: `#import' which includes a file, but does so at most once. If you use 1.1.1.2 root 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: 1.1.1.3 ! root 390: `#import' is obsolete because it is not a well-designed feature. It 1.1.1.2 root 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.3 ! root 416: a particular system doesn't do what the application program expects. ! 417: It might be convenient to define a "local" version, perhaps under the ! 418: name `/usr/local/include/sys/signal.h', to override or add to the one 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 1.1.1.3 ! root 444: `#include <sys/signal.h>' finds the file under `/usr/local/include'. 1.1 root 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 1.1.1.3 ! root 512: character constant. Comments within a macro definition may contain 1.1.1.2 root 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 1.1.1.3 ! root 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.3 ! 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.3 ! 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 1.1.1.3 ! root 580: macro followed by a list of "actual arguments" in parentheses, 1.1 root 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 1.1.1.3 ! root 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. 1.1 root 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.3 ! root 658: names must follow the macro name immediately with no space in between. 1.1.1.2 root 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.3 ! root 663: identifier in parentheses. This rule about spaces makes it possible ! 664: for 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.3 ! root 703: GNU C. Their names all start and end with double underscores. Those 1.1.1.2 root 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 1.1.1.3 ! root 721: state the source line at which the inconsistency was detected. 1.1 root 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: 1.1.1.3 ! root 766: `__GNUG__' ! 767: The GNU C compiler defines this when the compilation language is ! 768: C++; use `__GNUG__' to distinguish between GNU C and GNU C++. ! 769: ! 770: `__cplusplus' ! 771: The draft ANSI standard for C++ used to require predefining this ! 772: variable. Though it is no longer required, GNU C++ continues to ! 773: define it, as do other popular C++ compilers. You can use ! 774: `__cplusplus' to test whether a header is compiled by a C compiler ! 775: or a C++ compiler. ! 776: 1.1 root 777: `__STRICT_ANSI__' 778: This macro is defined if and only if the `-ansi' switch was 779: specified when GNU C was invoked. Its definition is the null 1.1.1.3 ! root 780: string. This macro exists primarily to direct certain GNU header 1.1 root 781: files not to define certain traditional Unix constructs which are 782: incompatible with ANSI C. 783: 784: `__BASE_FILE__' 785: This macro expands to the name of the main input file, in the form 1.1.1.2 root 786: of a C string constant. This is the source file that was specified 787: as an argument when the C compiler was invoked. 1.1 root 788: 789: `__VERSION__' 790: This macro expands to a string which describes the version number 791: of GNU C. The string is normally a sequence of decimal numbers 792: separated by periods, such as `"1.18"'. The only reasonable use 793: of this macro is to incorporate it into a string constant. 794: 795: `__OPTIMIZE__' 796: This macro is defined in optimizing compilations. It causes 797: certain GNU header files to define alternative macro definitions 798: for some system library functions. It is unwise to refer to or 799: test the definition of this macro unless you make very sure that 800: programs will execute with the same effect regardless. 801: 802: `__CHAR_UNSIGNED__' 803: This macro is defined if and only if the data type `char' is 804: unsigned on the target machine. It exists to cause the standard 805: header file `limit.h' to work correctly. It is bad practice to 806: refer to this macro yourself; instead, refer to the standard 807: macros defined in `limit.h'. The preprocessor uses this macro to 808: determine whether or not to sign-extend large character constants 809: written in octal; see *Note The `#if' Command: #if Command. 810: 811: 812: File: cpp.info, Node: Nonstandard Predefined, Prev: Standard Predefined, Up: Predefined 813: 814: Nonstandard Predefined Macros 815: ............................. 816: 817: The C preprocessor normally has several predefined macros that vary 818: between machines because their purpose is to indicate what type of 819: system and machine is in use. This manual, being for all systems and 820: machines, cannot tell you exactly what their names are; instead, we 821: offer a list of some typical ones. You can use `cpp -dM' to see the 822: values of predefined macros; *note Invocation::.. 823: 824: Some nonstandard predefined macros describe the operating system in 825: use, with more or less specificity. For example, 826: 827: `unix' 828: `unix' is normally predefined on all Unix systems. 829: 830: `BSD' 831: `BSD' is predefined on recent versions of Berkeley Unix (perhaps 832: only in version 4.3). 833: 834: Other nonstandard predefined macros describe the kind of CPU, with 835: more or less specificity. For example, 836: 837: `vax' 838: `vax' is predefined on Vax computers. 839: 840: `mc68000' 841: `mc68000' is predefined on most computers whose CPU is a Motorola 842: 68000, 68010 or 68020. 843: 844: `m68k' 845: `m68k' is also predefined on most computers whose CPU is a 68000, 846: 68010 or 68020; however, some makers use `mc68000' and some use 1.1.1.2 root 847: `m68k'. Some predefine both names. What happens in GNU C depends 848: on the system you are using it on. 1.1 root 849: 850: `M68020' 851: `M68020' has been observed to be predefined on some systems that 852: use 68020 CPUs--in addition to `mc68000' and `m68k', which are 853: less specific. 854: 855: `_AM29K' 856: `_AM29000' 857: Both `_AM29K' and `_AM29000' are predefined for the AMD 29000 CPU 858: family. 859: 860: `ns32000' 861: `ns32000' is predefined on computers which use the National 862: Semiconductor 32000 series CPU. 863: 864: Yet other nonstandard predefined macros describe the manufacturer of 865: the system. For example, 866: 867: `sun' 868: `sun' is predefined on all models of Sun computers. 869: 870: `pyr' 871: `pyr' is predefined on all models of Pyramid computers. 872: 873: `sequent' 874: `sequent' is predefined on all models of Sequent computers. 875: 1.1.1.2 root 876: These predefined symbols are not only nonstandard, they are contrary 877: to the ANSI standard because their names do not start with underscores. 878: Therefore, the option `-ansi' inhibits the definition of these symbols. 879: 880: This tends to make `-ansi' useless, since many programs depend on the 881: customary nonstandard predefined symbols. Even system header files 882: check them and will generate incorrect declarations if they do not find 883: the names that are expected. You might think that the header files 884: supplied for the Uglix computer would not need to test what machine 885: they are running on, because they can simply assume it is the Uglix; 886: but often they do, and they do so using the customary names. As a 887: result, very few C programs will compile with `-ansi'. We intend to 888: avoid such problems on the GNU system. 1.1 root 889: 890: What, then, should you do in an ANSI C program to test the type of 891: machine it will run on? 892: 893: GNU C offers a parallel series of symbols for this purpose, whose 894: names are made from the customary ones by adding `__' at the beginning 895: and end. Thus, the symbol `__vax__' would be available on a Vax, and 896: so on. 897: 898: The set of nonstandard predefined names in the GNU C preprocessor is 899: controlled (when `cpp' is itself compiled) by the macro 900: `CPP_PREDEFINES', which should be a string containing `-D' options, 901: separated by spaces. For example, on the Sun 3, we use the following 902: definition: 903: 904: #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" 905: 906: This macro is usually specified in `tm.h'. 907: 908: 909: File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Predefined, Up: Macros 910: 911: Stringification 912: --------------- 913: 914: "Stringification" means turning a code fragment into a string 915: constant whose contents are the text for the code fragment. For 916: example, stringifying `foo (z)' results in `"foo (z)"'. 917: 918: In the C preprocessor, stringification is an option available when 1.1.1.2 root 919: macro arguments are substituted into the macro definition. In the body 920: of the definition, when an argument name appears, the character `#' 921: before the name specifies stringification of the corresponding actual 922: argument when it is substituted at that point in the definition. The 923: same argument may be substituted in other places in the definition 924: without stringification if the argument name appears in those places 925: with no `#'. 1.1 root 926: 927: Here is an example of a macro definition that uses stringification: 928: 929: #define WARN_IF(EXP) \ 930: do { if (EXP) \ 931: fprintf (stderr, "Warning: " #EXP "\n"); } \ 932: while (0) 933: 934: Here the actual argument for `EXP' is substituted once as given, into 935: the `if' statement, and once as stringified, into the argument to 936: `fprintf'. The `do' and `while (0)' are a kludge to make it possible 937: to write `WARN_IF (ARG);', which the resemblance of `WARN_IF' to a 938: function would make C programmers want to do; *note Swallow 939: Semicolon::.). 940: 941: The stringification feature is limited to transforming one macro 942: argument into one string constant: there is no way to combine the 943: argument with other text and then stringify it all together. But the 944: example above shows how an equivalent result can be obtained in ANSI 945: Standard C using the feature that adjacent string constants are 1.1.1.2 root 946: concatenated as one string constant. The preprocessor stringifies the 947: actual value of `EXP' into a separate string constant, resulting in 1.1 root 948: text like 949: 950: do { if (x == 0) \ 951: fprintf (stderr, "Warning: " "x == 0" "\n"); } \ 952: while (0) 953: 954: but the C compiler then sees three consecutive string constants and 955: concatenates them into one, producing effectively 956: 957: do { if (x == 0) \ 958: fprintf (stderr, "Warning: x == 0\n"); } \ 959: while (0) 960: 961: Stringification in C involves more than putting doublequote 962: characters around the fragment; it is necessary to put backslashes in 963: front of all doublequote characters, and all backslashes in string and 1.1.1.2 root 964: character constants, in order to get a valid C string constant with the 965: proper contents. Thus, stringifying `p = "foo\n";' results in `"p = 966: \"foo\\n\";"'. However, backslashes that are not inside of string or 1.1 root 967: character constants are not duplicated: `\n' by itself stringifies to 968: `"\n"'. 969: 970: Whitespace (including comments) in the text being stringified is 971: handled according to precise rules. All leading and trailing 1.1.1.3 ! root 972: whitespace is ignored. Any sequence of whitespace in the middle of the 1.1.1.2 root 973: text is converted to a single space in the stringified result. 1.1 root 974: 975: 976: File: cpp.info, Node: Concatenation, Next: Undefining, Prev: Stringification, Up: Macros 977: 978: Concatenation 979: ------------- 980: 981: "Concatenation" means joining two strings into one. In the context 982: of macro expansion, concatenation refers to joining two lexical units 1.1.1.2 root 983: into one longer one. Specifically, an actual argument to the macro can 984: be concatenated with another actual argument or with fixed text to 985: produce a longer name. The longer name might be the name of a function, 986: variable or type, or a C keyword; it might even be the name of another 987: macro, in which case it will be expanded. 1.1 root 988: 989: When you define a macro, you request concatenation with the special 990: operator `##' in the macro body. When the macro is called, after 991: actual arguments are substituted, all `##' operators are deleted, and 992: so is any whitespace next to them (including whitespace that was part 993: of an actual argument). The result is to concatenate the syntactic 994: tokens on either side of the `##'. 995: 1.1.1.2 root 996: Consider a C program that interprets named commands. There probably 997: needs to be a table of commands, perhaps an array of structures 998: declared as follows: 1.1 root 999: 1000: struct command 1001: { 1002: char *name; 1003: void (*function) (); 1004: }; 1005: 1006: struct command commands[] = 1007: { 1008: { "quit", quit_command}, 1009: { "help", help_command}, 1010: ... 1011: }; 1012: 1013: It would be cleaner not to have to give each command name twice, 1014: once in the string constant and once in the function name. A macro 1015: which takes the name of a command as an argument can make this 1016: unnecessary. The string constant can be created with stringification, 1.1.1.3 ! root 1017: and the function name by concatenating the argument with `_command'. 1.1 root 1018: Here is how it is done: 1019: 1020: #define COMMAND(NAME) { #NAME, NAME ## _command } 1021: 1022: struct command commands[] = 1023: { 1024: COMMAND (quit), 1025: COMMAND (help), 1026: ... 1027: }; 1028: 1029: The usual case of concatenation is concatenating two names (or a 1030: name and a number) into a longer name. But this isn't the only valid 1031: case. It is also possible to concatenate two numbers (or a number and 1032: a name, such as `1.5' and `e3') into a number. Also, multi-character 1033: operators such as `+=' can be formed by concatenation. In some cases 1034: it is even possible to piece together a string constant. However, two 1035: pieces of text that don't together form a valid lexical unit cannot be 1036: concatenated. For example, concatenation with `x' on one side and `+' 1037: on the other is not meaningful because those two characters can't fit 1038: together in any lexical unit of C. The ANSI standard says that such 1039: attempts at concatenation are undefined, but in the GNU C preprocessor 1040: it is well defined: it puts the `x' and `+' side by side with no 1041: particular special results. 1042: 1.1.1.2 root 1043: Keep in mind that the C preprocessor converts comments to whitespace 1044: before macros are even considered. Therefore, you cannot create a 1045: comment by concatenating `/' and `*': the `/*' sequence that starts a 1046: comment is not a lexical unit, but rather the beginning of a "long" 1047: space character. Also, you can freely use comments next to a `##' in a 1048: macro definition, or in actual arguments that will be concatenated, 1049: because the comments will be converted to spaces at first sight, and 1050: concatenation will later discard the spaces. 1.1 root 1051: 1052: 1053: File: cpp.info, Node: Undefining, Next: Redefining, Prev: Concatenation, Up: Macros 1054: 1055: Undefining Macros 1056: ----------------- 1057: 1058: To "undefine" a macro means to cancel its definition. This is done 1059: with the `#undef' command. `#undef' is followed by the macro name to 1060: be undefined. 1061: 1062: Like definition, undefinition occurs at a specific point in the 1063: source file, and it applies starting from that point. The name ceases 1064: to be a macro name, and from that point on it is treated by the 1065: preprocessor as if it had never been a macro name. 1066: 1067: For example, 1068: 1069: #define FOO 4 1070: x = FOO; 1071: #undef FOO 1072: x = FOO; 1073: 1074: expands into 1075: 1076: x = 4; 1077: 1078: x = FOO; 1079: 1080: In this example, `FOO' had better be a variable or function as well as 1081: (temporarily) a macro, in order for the result of the expansion to be 1082: valid C code. 1083: 1084: The same form of `#undef' command will cancel definitions with 1085: arguments or definitions that don't expect arguments. The `#undef' 1086: command has no effect when used on a name not currently defined as a 1087: macro. 1088: 1089: 1090: File: cpp.info, Node: Redefining, Next: Macro Pitfalls, Prev: Undefining, Up: Macros 1091: 1092: Redefining Macros 1093: ----------------- 1094: 1095: "Redefining" a macro means defining (with `#define') a name that is 1096: already defined as a macro. 1097: 1098: A redefinition is trivial if the new definition is transparently 1099: identical to the old one. You probably wouldn't deliberately write a 1100: trivial redefinition, but they can happen automatically when a header 1101: file is included more than once (*note Header Files::.), so they are 1102: accepted silently and without effect. 1103: 1104: Nontrivial redefinition is considered likely to be an error, so it 1.1.1.2 root 1105: provokes a warning message from the preprocessor. However, sometimes it 1106: is useful to change the definition of a macro in mid-compilation. You 1107: can inhibit the warning by undefining the macro with `#undef' before the 1108: second definition. 1.1 root 1109: 1110: In order for a redefinition to be trivial, the new definition must 1111: exactly match the one already in effect, with two possible exceptions: 1112: 1113: * Whitespace may be added or deleted at the beginning or the end. 1114: 1.1.1.2 root 1115: * Whitespace may be changed in the middle (but not inside strings). 1116: However, it may not be eliminated entirely, and it may not be added 1117: where there was no whitespace at all. 1.1 root 1118: 1119: Recall that a comment counts as whitespace. 1120: 1121: 1122: File: cpp.info, Node: Macro Pitfalls, Prev: Redefining, Up: Macros 1123: 1124: Pitfalls and Subtleties of Macros 1125: --------------------------------- 1126: 1127: In this section we describe some special rules that apply to macros 1.1.1.2 root 1128: and macro expansion, and point out certain cases in which the rules have 1129: counterintuitive consequences that you must watch out for. 1.1 root 1130: 1131: * Menu: 1132: 1133: * Misnesting:: Macros can contain unmatched parentheses. 1134: * Macro Parentheses:: Why apparently superfluous parentheses 1135: may be necessary to avoid incorrect grouping. 1136: * Swallow Semicolon:: Macros that look like functions 1137: but expand into compound statements. 1138: * Side Effects:: Unsafe macros that cause trouble when 1139: arguments contain side effects. 1140: * Self-Reference:: Macros whose definitions use the macros' own names. 1141: * Argument Prescan:: Actual arguments are checked for macro calls 1142: before they are substituted. 1143: * Cascaded Macros:: Macros whose definitions use other macros. 1.1.1.2 root 1144: * Newlines in Args:: Sometimes line numbers get confused. 1.1 root 1145: 1146: 1147: File: cpp.info, Node: Misnesting, Next: Macro Parentheses, Prev: Macro Pitfalls, Up: Macro Pitfalls 1148: 1149: Improperly Nested Constructs 1150: ............................ 1151: 1152: Recall that when a macro is called with arguments, the arguments are 1.1.1.2 root 1153: substituted into the macro body and the result is checked, together with 1154: the rest of the input file, for more macro calls. 1.1 root 1155: 1156: It is possible to piece together a macro call coming partially from 1157: the macro body and partially from the actual arguments. For example, 1158: 1159: #define double(x) (2*(x)) 1160: #define call_with_1(x) x(1) 1161: 1162: would expand `call_with_1 (double)' into `(2*(1))'. 1163: 1164: Macro definitions do not have to have balanced parentheses. By 1165: writing an unbalanced open parenthesis in a macro body, it is possible 1166: to create a macro call that begins inside the macro body but ends 1167: outside of it. For example, 1168: 1169: #define strange(file) fprintf (file, "%s %d", 1170: ... 1171: strange(stderr) p, 35) 1172: 1173: This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'! 1174: 1175: 1176: File: cpp.info, Node: Macro Parentheses, Next: Swallow Semicolon, Prev: Misnesting, Up: Macro Pitfalls 1177: 1178: Unintended Grouping of Arithmetic 1179: ................................. 1180: 1181: You may have noticed that in most of the macro definition examples 1182: shown above, each occurrence of a macro argument name had parentheses 1.1.1.3 ! root 1183: around it. In addition, another pair of parentheses usually surround 1.1 root 1184: the entire macro definition. Here is why it is best to write macros 1185: that way. 1186: 1187: Suppose you define a macro as follows, 1188: 1189: #define ceil_div(x, y) (x + y - 1) / y 1190: 1.1.1.2 root 1191: whose purpose is to divide, rounding up. (One use for this operation is 1192: to compute how many `int' objects are needed to hold a certain number 1193: of `char' objects.) Then suppose it is used as follows: 1.1 root 1194: 1195: a = ceil_div (b & c, sizeof (int)); 1196: 1197: This expands into 1198: 1199: a = (b & c + sizeof (int) - 1) / sizeof (int); 1200: 1.1.1.2 root 1201: which does not do what is intended. The operator-precedence rules of C 1202: make it equivalent to this: 1.1 root 1203: 1204: a = (b & (c + sizeof (int) - 1)) / sizeof (int); 1205: 1206: But what we want is this: 1207: 1208: a = ((b & c) + sizeof (int) - 1)) / sizeof (int); 1209: 1210: Defining the macro as 1211: 1212: #define ceil_div(x, y) ((x) + (y) - 1) / (y) 1213: 1214: provides the desired result. 1215: 1216: However, unintended grouping can result in another way. Consider 1217: `sizeof ceil_div(1, 2)'. That has the appearance of a C expression 1218: that would compute the size of the type of `ceil_div (1, 2)', but in 1219: fact it means something very different. Here is what it expands to: 1220: 1221: sizeof ((1) + (2) - 1) / (2) 1222: 1223: This would take the size of an integer and divide it by two. The 1.1.1.2 root 1224: precedence rules have put the division outside the `sizeof' when it was 1225: intended to be inside. 1.1 root 1226: 1227: Parentheses around the entire macro definition can prevent such 1.1.1.3 ! root 1228: problems. Here, then, is the recommended way to define `ceil_div': 1.1 root 1229: 1230: #define ceil_div(x, y) (((x) + (y) - 1) / (y)) 1231:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.