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