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