1\input texinfo 2@setfilename cpp.info 3@settitle The C Preprocessor 4 5@ifinfo 6@dircategory Programming 7@direntry 8* Cpp: (cpp). The GNU C preprocessor. 9@end direntry 10@end ifinfo 11 12@c @smallbook 13@c @cropmarks 14@c @finalout 15@setchapternewpage odd 16@ifinfo 17This file documents the GNU C Preprocessor. 18 19Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1997, 1998 Free Software 20Foundation, Inc. 21 22Permission is granted to make and distribute verbatim copies of 23this manual provided the copyright notice and this permission notice 24are preserved on all copies. 25 26@ignore 27Permission is granted to process this file through Tex and print the 28results, provided the printed document carries copying permission 29notice identical to this one except for the removal of this paragraph 30(this paragraph not being relevant to the printed manual). 31 32@end ignore 33Permission is granted to copy and distribute modified versions of this 34manual under the conditions for verbatim copying, provided also that 35the entire resulting derived work is distributed under the terms of a 36permission notice identical to this one. 37 38Permission is granted to copy and distribute translations of this manual 39into another language, under the above conditions for modified versions. 40@end ifinfo 41 42@titlepage 43@c @finalout 44@title The C Preprocessor 45@subtitle Last revised September 1998 46@subtitle for GCC version 2 47@author Richard M. Stallman 48@page 49@vskip 2pc 50This booklet is eventually intended to form the first chapter of a GNU 51C Language manual. 52 53@vskip 0pt plus 1filll 54Copyright @copyright{} 1987, 1989, 1991-1998 55Free Software Foundation, Inc. 56 57Permission is granted to make and distribute verbatim copies of 58this manual provided the copyright notice and this permission notice 59are preserved on all copies. 60 61Permission is granted to copy and distribute modified versions of this 62manual under the conditions for verbatim copying, provided also that 63the entire resulting derived work is distributed under the terms of a 64permission notice identical to this one. 65 66Permission is granted to copy and distribute translations of this manual 67into another language, under the above conditions for modified versions. 68@end titlepage 69@page 70 71@node Top, Global Actions,, (DIR) 72@chapter The C Preprocessor 73 74The C preprocessor is a @dfn{macro processor} that is used automatically by 75the C compiler to transform your program before actual compilation. It is 76called a macro processor because it allows you to define @dfn{macros}, 77which are brief abbreviations for longer constructs. 78 79The C preprocessor provides four separate facilities that you can use as 80you see fit: 81 82@itemize @bullet 83@item 84Inclusion of header files. These are files of declarations that can be 85substituted into your program. 86 87@item 88Macro expansion. You can define @dfn{macros}, which are abbreviations 89for arbitrary fragments of C code, and then the C preprocessor will 90replace the macros with their definitions throughout the program. 91 92@item 93Conditional compilation. Using special preprocessing directives, you 94can include or exclude parts of the program according to various 95conditions. 96 97@item 98Line control. If you use a program to combine or rearrange source files into 99an intermediate file which is then compiled, you can use line control 100to inform the compiler of where each source line originally came from. 101@end itemize 102 103C preprocessors vary in some details. This manual discusses the GNU C 104preprocessor, the C Compatible Compiler Preprocessor. The GNU C 105preprocessor provides a superset of the features of ANSI Standard C@. 106 107ANSI Standard C requires the rejection of many harmless constructs commonly 108used by today's C programs. Such incompatibility would be inconvenient for 109users, so the GNU C preprocessor is configured to accept these constructs 110by default. Strictly speaking, to get ANSI Standard C, you must use the 111options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in 112practice the consequences of having strict ANSI Standard C make it 113undesirable to do this. @xref{Invocation}. 114 115The C preprocessor is designed for C-like languages; you may run into 116problems if you apply it to other kinds of languages, because it assumes 117that it is dealing with C@. For example, the C preprocessor sometimes 118outputs extra white space to avoid inadvertent C token concatenation, 119and this may cause problems with other languages. 120 121@menu 122* Global Actions:: Actions made uniformly on all input files. 123* Directives:: General syntax of preprocessing directives. 124* Header Files:: How and why to use header files. 125* Macros:: How and why to use macros. 126* Conditionals:: How and why to use conditionals. 127* Combining Sources:: Use of line control when you combine source files. 128* Other Directives:: Miscellaneous preprocessing directives. 129* Output:: Format of output from the C preprocessor. 130* Invocation:: How to invoke the preprocessor; command options. 131* Concept Index:: Index of concepts and terms. 132* Index:: Index of directives, predefined macros and options. 133@end menu 134 135@node Global Actions, Directives, Top, Top 136@section Transformations Made Globally 137 138Most C preprocessor features are inactive unless you give specific directives 139to request their use. (Preprocessing directives are lines starting with 140@samp{#}; @pxref{Directives}). But there are three transformations that the 141preprocessor always makes on all the input it receives, even in the absence 142of directives. 143 144@itemize @bullet 145@item 146All C comments are replaced with single spaces. 147 148@item 149Backslash-Newline sequences are deleted, no matter where. This 150feature allows you to break long lines for cosmetic purposes without 151changing their meaning. 152 153@item 154Predefined macro names are replaced with their expansions 155(@pxref{Predefined}). 156@end itemize 157 158The first two transformations are done @emph{before} nearly all other parsing 159and before preprocessing directives are recognized. Thus, for example, you 160can split a line cosmetically with Backslash-Newline anywhere (except 161when trigraphs are in use; see below). 162 163@example 164/* 165*/ # /* 166*/ defi\ 167ne FO\ 168O 10\ 16920 170@end example 171 172@noindent 173is equivalent into @samp{#define FOO 1020}. You can split even an escape 174sequence with Backslash-Newline. For example, you can split @code{"foo\bar"} 175between the @samp{\} and the @samp{b} to get 176 177@example 178"foo\\ 179bar" 180@end example 181 182@noindent 183This behavior is unclean: in all other contexts, a Backslash can be 184inserted in a string constant as an ordinary character by writing a double 185Backslash, and this creates an exception. But the ANSI C standard requires 186it. (Strict ANSI C does not allow Newlines in string constants, so they 187do not consider this a problem.) 188 189But there are a few exceptions to all three transformations. 190 191@itemize @bullet 192@item 193C comments and predefined macro names are not recognized inside a 194@samp{#include} directive in which the file name is delimited with 195@samp{<} and @samp{>}. 196 197@item 198C comments and predefined macro names are never recognized within a 199character or string constant. (Strictly speaking, this is the rule, 200not an exception, but it is worth noting here anyway.) 201 202@item 203Backslash-Newline may not safely be used within an ANSI ``trigraph''. 204Trigraphs are converted before Backslash-Newline is deleted. If you 205write what looks like a trigraph with a Backslash-Newline inside, the 206Backslash-Newline is deleted as usual, but it is then too late to 207recognize the trigraph. 208 209This exception is relevant only if you use the @samp{-trigraphs} 210option to enable trigraph processing. @xref{Invocation}. 211@end itemize 212 213@node Directives, Header Files, Global Actions, Top 214@section Preprocessing Directives 215 216@cindex preprocessing directives 217@cindex directives 218Most preprocessor features are active only if you use preprocessing directives 219to request their use. 220 221Preprocessing directives are lines in your program that start with @samp{#}. 222The @samp{#} is followed by an identifier that is the @dfn{directive name}. 223For example, @samp{#define} is the directive that defines a macro. 224Whitespace is also allowed before and after the @samp{#}. 225 226The set of valid directive names is fixed. Programs cannot define new 227preprocessing directives. 228 229Some directive names require arguments; these make up the rest of the directive 230line and must be separated from the directive name by whitespace. For example, 231@samp{#define} must be followed by a macro name and the intended expansion 232of the macro. @xref{Simple Macros}. 233 234A preprocessing directive cannot be more than one line in normal circumstances. 235It may be split cosmetically with Backslash-Newline, but that has no effect 236on its meaning. Comments containing Newlines can also divide the 237directive into multiple lines, but the comments are changed to Spaces 238before the directive is interpreted. The only way a significant Newline 239can occur in a preprocessing directive is within a string constant or 240character constant. Note that 241most C compilers that might be applied to the output from the preprocessor 242do not accept string or character constants containing Newlines. 243 244The @samp{#} and the directive name cannot come from a macro expansion. For 245example, if @samp{foo} is defined as a macro expanding to @samp{define}, 246that does not make @samp{#foo} a valid preprocessing directive. 247 248@node Header Files, Macros, Directives, Top 249@section Header Files 250 251@cindex header file 252A header file is a file containing C declarations and macro definitions 253(@pxref{Macros}) to be shared between several source files. You request 254the use of a header file in your program with the C preprocessing directive 255@samp{#include}. 256 257@menu 258* Header Uses:: What header files are used for. 259* Include Syntax:: How to write @samp{#include} directives. 260* Include Operation:: What @samp{#include} does. 261* Once-Only:: Preventing multiple inclusion of one header file. 262* Inheritance:: Including one header file in another header file. 263@end menu 264 265@node Header Uses, Include Syntax, Header Files, Header Files 266@subsection Uses of Header Files 267 268Header files serve two kinds of purposes. 269 270@itemize @bullet 271@item 272@findex system header files 273System header files declare the interfaces to parts of the operating 274system. You include them in your program to supply the definitions and 275declarations you need to invoke system calls and libraries. 276 277@item 278Your own header files contain declarations for interfaces between the 279source files of your program. Each time you have a group of related 280declarations and macro definitions all or most of which are needed in 281several different source files, it is a good idea to create a header 282file for them. 283@end itemize 284 285Including a header file produces the same results in C compilation as 286copying the header file into each source file that needs it. But such 287copying would be time-consuming and error-prone. With a header file, the 288related declarations appear in only one place. If they need to be changed, 289they can be changed in one place, and programs that include the header file 290will automatically use the new version when next recompiled. The header 291file eliminates the labor of finding and changing all the copies as well as 292the risk that a failure to find one copy will result in inconsistencies 293within a program. 294 295The usual convention is to give header files names that end with 296@file{.h}. Avoid unusual characters in header file names, as they 297reduce portability. 298 299@node Include Syntax, Include Operation, Header Uses, Header Files 300@subsection The @samp{#include} Directive 301 302@findex #include 303Both user and system header files are included using the preprocessing 304directive @samp{#include}. It has three variants: 305 306@table @code 307@item #include <@var{file}> 308This variant is used for system header files. It searches for a file 309named @var{file} in a list of directories specified by you, then in a 310standard list of system directories. You specify directories to 311search for header files with the command option @samp{-I} 312(@pxref{Invocation}). The option @samp{-nostdinc} inhibits searching 313the standard system directories; in this case only the directories 314you specify are searched. 315 316The parsing of this form of @samp{#include} is slightly special 317because comments are not recognized within the @samp{<@dots{}>}. 318Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment 319and the directive specifies inclusion of a system header file named 320@file{x/*y}. Of course, a header file with such a name is unlikely to 321exist on Unix, where shell wildcard features would make it hard to 322manipulate.@refill 323 324The argument @var{file} may not contain a @samp{>} character. It may, 325however, contain a @samp{<} character. 326 327@item #include "@var{file}" 328This variant is used for header files of your own program. It 329searches for a file named @var{file} first in the current directory, 330then in the same directories used for system header files. The 331current directory is the directory of the current input file. It is 332tried first because it is presumed to be the location of the files 333that the current input file refers to. (If the @samp{-I-} option is 334used, the special treatment of the current directory is inhibited.) 335 336The argument @var{file} may not contain @samp{"} characters. If 337backslashes occur within @var{file}, they are considered ordinary text 338characters, not escape characters. None of the character escape 339sequences appropriate to string constants in C are processed. Thus, 340@samp{#include "x\n\\y"} specifies a filename containing three 341backslashes. It is not clear why this behavior is ever useful, but 342the ANSI standard specifies it. 343 344@item #include @var{anything else} 345@cindex computed @samp{#include} 346This variant is called a @dfn{computed #include}. Any @samp{#include} 347directive whose argument does not fit the above two forms is a computed 348include. The text @var{anything else} is checked for macro calls, 349which are expanded (@pxref{Macros}). When this is done, the result 350must fit one of the above two variants---in particular, the expanded 351text must in the end be surrounded by either quotes or angle braces. 352 353This feature allows you to define a macro which controls the file name 354to be used at a later point in the program. One application of this is 355to allow a site-specific configuration file for your program to specify 356the names of the system include files to be used. This can help in 357porting the program to various operating systems in which the necessary 358system header files are found in different places. 359@end table 360 361@node Include Operation, Once-Only, Include Syntax, Header Files 362@subsection How @samp{#include} Works 363 364The @samp{#include} directive works by directing the C preprocessor to scan 365the specified file as input before continuing with the rest of the current 366file. The output from the preprocessor contains the output already 367generated, followed by the output resulting from the included file, 368followed by the output that comes from the text after the @samp{#include} 369directive. For example, given a header file @file{header.h} as follows, 370 371@example 372char *test (); 373@end example 374 375@noindent 376and a main program called @file{program.c} that uses the header file, 377like this, 378 379@example 380int x; 381#include "header.h" 382 383main () 384@{ 385 printf (test ()); 386@} 387@end example 388 389@noindent 390the output generated by the C preprocessor for @file{program.c} as input 391would be 392 393@example 394int x; 395char *test (); 396 397main () 398@{ 399 printf (test ()); 400@} 401@end example 402 403Included files are not limited to declarations and macro definitions; those 404are merely the typical uses. Any fragment of a C program can be included 405from another file. The include file could even contain the beginning of a 406statement that is concluded in the containing file, or the end of a 407statement that was started in the including file. However, a comment or a 408string or character constant may not start in the included file and finish 409in the including file. An unterminated comment, string constant or 410character constant in an included file is considered to end (with an error 411message) at the end of the file. 412 413It is possible for a header file to begin or end a syntactic unit such 414as a function definition, but that would be very confusing, so don't do 415it. 416 417The line following the @samp{#include} directive is always treated as a 418separate line by the C preprocessor even if the included file lacks a final 419newline. 420 421@node Once-Only, Inheritance, Include Operation, Header Files 422@subsection Once-Only Include Files 423@cindex repeated inclusion 424@cindex including just once 425 426Very often, one header file includes another. It can easily result that a 427certain header file is included more than once. This may lead to errors, 428if the header file defines structure types or typedefs, and is certainly 429wasteful. Therefore, we often wish to prevent multiple inclusion of a 430header file. 431 432The standard way to do this is to enclose the entire real contents of the 433file in a conditional, like this: 434 435@example 436#ifndef FILE_FOO_SEEN 437#define FILE_FOO_SEEN 438 439@var{the entire file} 440 441#endif /* FILE_FOO_SEEN */ 442@end example 443 444The macro @code{FILE_FOO_SEEN} indicates that the file has been included 445once already. In a user header file, the macro name should not begin 446with @samp{_}. In a system header file, this name should begin with 447@samp{__} to avoid conflicts with user programs. In any kind of header 448file, the macro name should contain the name of the file and some 449additional text, to avoid conflicts with other header files. 450 451The GNU C preprocessor is programmed to notice when a header file uses 452this particular construct and handle it efficiently. If a header file 453is contained entirely in a @samp{#ifndef} conditional, then it records 454that fact. If a subsequent @samp{#include} specifies the same file, 455and the macro in the @samp{#ifndef} is already defined, then the file 456is entirely skipped, without even reading it. 457 458@findex #pragma once 459There is also an explicit directive to tell the preprocessor that it need 460not include a file more than once. This is called @samp{#pragma once}, 461and was used @emph{in addition to} the @samp{#ifndef} conditional around 462the contents of the header file. @samp{#pragma once} is now obsolete 463and should not be used at all. 464 465@findex #import 466In the Objective C language, there is a variant of @samp{#include} 467called @samp{#import} which includes a file, but does so at most once. 468If you use @samp{#import} @emph{instead of} @samp{#include}, then you 469don't need the conditionals inside the header file to prevent multiple 470execution of the contents. 471 472@samp{#import} is obsolete because it is not a well designed feature. 473It requires the users of a header file---the applications 474programmers---to know that a certain header file should only be included 475once. It is much better for the header file's implementor to write the 476file so that users don't need to know this. Using @samp{#ifndef} 477accomplishes this goal. 478 479@node Inheritance,, Once-Only, Header Files 480@subsection Inheritance and Header Files 481@cindex inheritance 482@cindex overriding a header file 483 484@dfn{Inheritance} is what happens when one object or file derives some 485of its contents by virtual copying from another object or file. In 486the case of C header files, inheritance means that one header file 487includes another header file and then replaces or adds something. 488 489If the inheriting header file and the base header file have different 490names, then inheritance is straightforward: simply write @samp{#include 491"@var{base}"} in the inheriting file. 492 493Sometimes it is necessary to give the inheriting file the same name as 494the base file. This is less straightforward. 495 496For example, suppose an application program uses the system header 497@file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h} 498on a particular system doesn't do what the application program expects. 499It might be convenient to define a ``local'' version, perhaps under the 500name @file{/usr/local/include/sys/signal.h}, to override or add to the 501one supplied by the system. 502 503You can do this by compiling with the option @samp{-I.}, and 504writing a file @file{sys/signal.h} that does what the application 505program expects. But making this file include the standard 506@file{sys/signal.h} is not so easy---writing @samp{#include 507<sys/signal.h>} in that file doesn't work, because it includes your own 508version of the file, not the standard system version. Used in that file 509itself, this leads to an infinite recursion and a fatal error in 510compilation. 511 512@samp{#include </usr/include/sys/signal.h>} would find the proper file, 513but that is not clean, since it makes an assumption about where the 514system header file is found. This is bad for maintenance, since it 515means that any change in where the system's header files are kept 516requires a change somewhere else. 517 518@findex #include_next 519The clean way to solve this problem is to use 520@samp{#include_next}, which means, ``Include the @emph{next} file with 521this name.'' This directive works like @samp{#include} except in 522searching for the specified file: it starts searching the list of header 523file directories @emph{after} the directory in which the current file 524was found. 525 526Suppose you specify @samp{-I /usr/local/include}, and the list of 527directories to search also includes @file{/usr/include}; and suppose 528both directories contain @file{sys/signal.h}. Ordinary 529@samp{#include <sys/signal.h>} finds the file under 530@file{/usr/local/include}. If that file contains @samp{#include_next 531<sys/signal.h>}, it starts searching after that directory, and finds the 532file in @file{/usr/include}. 533 534@node Macros, Conditionals, Header Files, Top 535@section Macros 536 537A macro is a sort of abbreviation which you can define once and then 538use later. There are many complicated features associated with macros 539in the C preprocessor. 540 541@menu 542* Simple Macros:: Macros that always expand the same way. 543* Argument Macros:: Macros that accept arguments that are substituted 544 into the macro expansion. 545* Predefined:: Predefined macros that are always available. 546* Stringification:: Macro arguments converted into string constants. 547* Concatenation:: Building tokens from parts taken from macro arguments. 548* Undefining:: Cancelling a macro's definition. 549* Redefining:: Changing a macro's definition. 550* Macro Pitfalls:: Macros can confuse the unwary. Here we explain 551 several common problems and strange features. 552@end menu 553 554@node Simple Macros, Argument Macros, Macros, Macros 555@subsection Simple Macros 556@cindex simple macro 557@cindex manifest constant 558 559A @dfn{simple macro} is a kind of abbreviation. It is a name which 560stands for a fragment of code. Some people refer to these as 561@dfn{manifest constants}. 562 563Before you can use a macro, you must @dfn{define} it explicitly with the 564@samp{#define} directive. @samp{#define} is followed by the name of the 565macro and then the code it should be an abbreviation for. For example, 566 567@example 568#define BUFFER_SIZE 1020 569@end example 570 571@noindent 572defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text 573@samp{1020}. If somewhere after this @samp{#define} directive there comes 574a C statement of the form 575 576@example 577foo = (char *) xmalloc (BUFFER_SIZE); 578@end example 579 580@noindent 581then the C preprocessor will recognize and @dfn{expand} the macro 582@samp{BUFFER_SIZE}, resulting in 583 584@example 585foo = (char *) xmalloc (1020); 586@end example 587 588The use of all upper case for macro names is a standard convention. 589Programs are easier to read when it is possible to tell at a glance which 590names are macros. 591 592Normally, a macro definition must be a single line, like all C 593preprocessing directives. (You can split a long macro definition 594cosmetically with Backslash-Newline.) There is one exception: Newlines 595can be included in the macro definition if within a string or character 596constant. This is because it is not possible for a macro definition to 597contain an unbalanced quote character; the definition automatically 598extends to include the matching quote character that ends the string or 599character constant. Comments within a macro definition may contain 600Newlines, which make no difference since the comments are entirely 601replaced with Spaces regardless of their contents. 602 603Aside from the above, there is no restriction on what can go in a macro 604body. Parentheses need not balance. The body need not resemble valid C 605code. (But if it does not, you may get error messages from the C 606compiler when you use the macro.) 607 608The C preprocessor scans your program sequentially, so macro definitions 609take effect at the place you write them. Therefore, the following input to 610the C preprocessor 611 612@example 613foo = X; 614#define X 4 615bar = X; 616@end example 617 618@noindent 619produces as output 620 621@example 622foo = X; 623 624bar = 4; 625@end example 626 627After the preprocessor expands a macro name, the macro's definition body is 628appended to the front of the remaining input, and the check for macro calls 629continues. Therefore, the macro body can contain calls to other macros. 630For example, after 631 632@example 633#define BUFSIZE 1020 634#define TABLESIZE BUFSIZE 635@end example 636 637@noindent 638the name @samp{TABLESIZE} when used in the program would go through two 639stages of expansion, resulting ultimately in @samp{1020}. 640 641This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}. 642The @samp{#define} for @samp{TABLESIZE} uses exactly the body you 643specify---in this case, @samp{BUFSIZE}---and does not check to see whether 644it too is the name of a macro. It's only when you @emph{use} @samp{TABLESIZE} 645that the result of its expansion is checked for more macro names. 646@xref{Cascaded Macros}. 647 648@node Argument Macros, Predefined, Simple Macros, Macros 649@subsection Macros with Arguments 650@cindex macros with argument 651@cindex arguments in macro definitions 652@cindex function-like macro 653 654A simple macro always stands for exactly the same text, each time it is 655used. Macros can be more flexible when they accept @dfn{arguments}. 656Arguments are fragments of code that you supply each time the macro is 657used. These fragments are included in the expansion of the macro 658according to the directions in the macro definition. A macro that 659accepts arguments is called a @dfn{function-like macro} because the 660syntax for using it looks like a function call. 661 662@findex #define 663To define a macro that uses arguments, you write a @samp{#define} directive 664with a list of @dfn{argument names} in parentheses after the name of the 665macro. The argument names may be any valid C identifiers, separated by 666commas and optionally whitespace. The open-parenthesis must follow the 667macro name immediately, with no space in between. 668 669For example, here is a macro that computes the minimum of two numeric 670values, as it is defined in many C programs: 671 672@example 673#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 674@end example 675 676@noindent 677(This is not the best way to define a ``minimum'' macro in GNU C@. 678@xref{Side Effects}, for more information.) 679 680To use a macro that expects arguments, you write the name of the macro 681followed by a list of @dfn{actual arguments} in parentheses, separated by 682commas. The number of actual arguments you give must match the number of 683arguments the macro expects. Examples of use of the macro @samp{min} 684include @samp{min (1, 2)} and @samp{min (x + 28, *p)}. 685 686The expansion text of the macro depends on the arguments you use. 687Each of the argument names of the macro is replaced, throughout the 688macro definition, with the corresponding actual argument. Using the 689same macro @samp{min} defined above, @samp{min (1, 2)} expands into 690 691@example 692((1) < (2) ? (1) : (2)) 693@end example 694 695@noindent 696where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}. 697 698Likewise, @samp{min (x + 28, *p)} expands into 699 700@example 701((x + 28) < (*p) ? (x + 28) : (*p)) 702@end example 703 704Parentheses in the actual arguments must balance; a comma within 705parentheses does not end an argument. However, there is no requirement 706for brackets or braces to balance, and they do not prevent a comma from 707separating arguments. Thus, 708 709@example 710macro (array[x = y, x + 1]) 711@end example 712 713@noindent 714passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x + 7151]}. If you want to supply @samp{array[x = y, x + 1]} as an argument, 716you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C 717code. 718 719After the actual arguments are substituted into the macro body, the entire 720result is appended to the front of the remaining input, and the check for 721macro calls continues. Therefore, the actual arguments can contain calls 722to other macros, either with or without arguments, or even to the same 723macro. The macro body can also contain calls to other macros. For 724example, @samp{min (min (a, b), c)} expands into this text: 725 726@example 727((((a) < (b) ? (a) : (b))) < (c) 728 ? (((a) < (b) ? (a) : (b))) 729 : (c)) 730@end example 731 732@noindent 733(Line breaks shown here for clarity would not actually be generated.) 734 735@cindex blank macro arguments 736@cindex space as macro argument 737If a macro @code{foo} takes one argument, and you want to supply an 738empty argument, you must write at least some whitespace between the 739parentheses, like this: @samp{foo ( )}. Just @samp{foo ()} is providing 740no arguments, which is an error if @code{foo} expects an argument. But 741@samp{foo0 ()} is the correct way to call a macro defined to take zero 742arguments, like this: 743 744@example 745#define foo0() @dots{} 746@end example 747 748If you use the macro name followed by something other than an 749open-parenthesis (after ignoring any spaces, tabs and comments that 750follow), it is not a call to the macro, and the preprocessor does not 751change what you have written. Therefore, it is possible for the same name 752to be a variable or function in your program as well as a macro, and you 753can choose in each instance whether to refer to the macro (if an actual 754argument list follows) or the variable or function (if an argument list 755does not follow). 756 757Such dual use of one name could be confusing and should be avoided 758except when the two meanings are effectively synonymous: that is, when the 759name is both a macro and a function and the two have similar effects. You 760can think of the name simply as a function; use of the name for purposes 761other than calling it (such as, to take the address) will refer to the 762function, while calls will expand the macro and generate better but 763equivalent code. For example, you can use a function named @samp{min} in 764the same source file that defines the macro. If you write @samp{&min} with 765no argument list, you refer to the function. If you write @samp{min (x, 766bb)}, with an argument list, the macro is expanded. If you write 767@samp{(min) (a, bb)}, where the name @samp{min} is not followed by an 768open-parenthesis, the macro is not expanded, so you wind up with a call to 769the function @samp{min}. 770 771You may not define the same name as both a simple macro and a macro with 772arguments. 773 774In the definition of a macro with arguments, the list of argument names 775must follow the macro name immediately with no space in between. If there 776is a space after the macro name, the macro is defined as taking no 777arguments, and all the rest of the line is taken to be the expansion. The 778reason for this is that it is often useful to define a macro that takes no 779arguments and whose definition begins with an identifier in parentheses. 780This rule about spaces makes it possible for you to do either this: 781 782@example 783#define FOO(x) - 1 / (x) 784@end example 785 786@noindent 787(which defines @samp{FOO} to take an argument and expand into minus the 788reciprocal of that argument) or this: 789 790@example 791#define BAR (x) - 1 / (x) 792@end example 793 794@noindent 795(which defines @samp{BAR} to take no argument and always expand into 796@samp{(x) - 1 / (x)}). 797 798Note that the @emph{uses} of a macro with arguments can have spaces before 799the left parenthesis; it's the @emph{definition} where it matters whether 800there is a space. 801 802@node Predefined, Stringification, Argument Macros, Macros 803@subsection Predefined Macros 804 805@cindex predefined macros 806Several simple macros are predefined. You can use them without giving 807definitions for them. They fall into two classes: standard macros and 808system-specific macros. 809 810@menu 811* Standard Predefined:: Standard predefined macros. 812* Nonstandard Predefined:: Nonstandard predefined macros. 813@end menu 814 815@node Standard Predefined, Nonstandard Predefined, Predefined, Predefined 816@subsubsection Standard Predefined Macros 817@cindex standard predefined macros 818 819The standard predefined macros are available with the same meanings 820regardless of the machine or operating system on which you are using GNU C@. 821Their names all start and end with double underscores. Those preceding 822@code{__GNUC__} in this table are standardized by ANSI C; the rest are 823GNU C extensions. 824 825@table @code 826@item __FILE__ 827@findex __FILE__ 828This macro expands to the name of the current input file, in the form of 829a C string constant. The precise name returned is the one that was 830specified in @samp{#include} or as the input file name argument. 831 832@item __LINE__ 833@findex __LINE__ 834This macro expands to the current input line number, in the form of a 835decimal integer constant. While we call it a predefined macro, it's 836a pretty strange macro, since its ``definition'' changes with each 837new line of source code. 838 839This and @samp{__FILE__} are useful in generating an error message to 840report an inconsistency detected by the program; the message can state 841the source line at which the inconsistency was detected. For example, 842 843@smallexample 844fprintf (stderr, "Internal error: " 845 "negative string length " 846 "%d at %s, line %d.", 847 length, __FILE__, __LINE__); 848@end smallexample 849 850A @samp{#include} directive changes the expansions of @samp{__FILE__} 851and @samp{__LINE__} to correspond to the included file. At the end of 852that file, when processing resumes on the input file that contained 853the @samp{#include} directive, the expansions of @samp{__FILE__} and 854@samp{__LINE__} revert to the values they had before the 855@samp{#include} (but @samp{__LINE__} is then incremented by one as 856processing moves to the line after the @samp{#include}). 857 858The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered 859if a @samp{#line} directive is used. @xref{Combining Sources}. 860 861@item __DATE__ 862@findex __DATE__ 863This macro expands to a string constant that describes the date on 864which the preprocessor is being run. The string constant contains 865eleven characters and looks like @w{@samp{"Feb 1 1996"}}. 866@c After reformatting the above, check that the date remains `Feb 1 1996', 867@c all on one line, with two spaces between the `Feb' and the `1'. 868 869@item __TIME__ 870@findex __TIME__ 871This macro expands to a string constant that describes the time at 872which the preprocessor is being run. The string constant contains 873eight characters and looks like @samp{"23:59:01"}. 874 875@item __STDC__ 876@findex __STDC__ 877This macro expands to the constant 1, to signify that this is ANSI 878Standard C@. (Whether that is actually true depends on what C compiler 879will operate on the output from the preprocessor.) 880 881On some hosts, system include files use a different convention, where 882@samp{__STDC__} is normally 0, but is 1 if the user specifies strict 883conformance to the C Standard. The preprocessor follows the host convention 884when processing system include files, but when processing user files it follows 885the usual GNU C convention. 886 887This macro is not defined if the @samp{-traditional} option is used. 888 889@item __STDC_VERSION__ 890@findex __STDC_VERSION__ 891This macro expands to the C Standard's version number, 892a long integer constant of the form @samp{@var{yyyy}@var{mm}L} 893where @var{yyyy} and @var{mm} are the year and month of the Standard version. 894This signifies which version of the C Standard the preprocessor conforms to. 895Like @samp{__STDC__}, whether this version number is accurate 896for the entire implementation depends on what C compiler 897will operate on the output from the preprocessor. 898 899This macro is not defined if the @samp{-traditional} option is used. 900 901@item __GNUC__ 902@findex __GNUC__ 903This macro is defined if and only if this is GNU C@. This macro is 904defined only when the entire GNU C compiler is in use; if you invoke the 905preprocessor directly, @samp{__GNUC__} is undefined. The value 906identifies the major version number of GNU CC (@samp{1} for GNU CC 907version 1, which is now obsolete, and @samp{2} for version 2). 908 909@item __GNUC_MINOR__ 910@findex __GNUC_MINOR__ 911The macro contains the minor version number of the compiler. This can 912be used to work around differences between different releases of the 913compiler (for example, if gcc 2.6.3 is known to support a feature, you 914can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}). 915The last number, @samp{3} in the 916example above, denotes the bugfix level of the compiler; no macro 917contains this value. 918 919@item __GNUG__ 920@findex __GNUG__ 921The GNU C compiler defines this when the compilation language is 922C++; use @samp{__GNUG__} to distinguish between GNU C and GNU 923C++. 924 925@item __cplusplus 926@findex __cplusplus 927The draft ANSI standard for C++ used to require predefining this 928variable. Though it is no longer required, GNU C++ continues to define 929it, as do other popular C++ compilers. You can use @samp{__cplusplus} 930to test whether a header is compiled by a C compiler or a C++ compiler. 931 932@item __STRICT_ANSI__ 933@findex __STRICT_ANSI__ 934GNU C defines this macro if and only if the @samp{-ansi} switch was 935specified when GNU C was invoked. Its definition is the null string. 936This macro exists primarily to direct certain GNU header files not to 937define certain traditional Unix constructs which are incompatible with 938ANSI C@. 939 940@item __BASE_FILE__ 941@findex __BASE_FILE__ 942This macro expands to the name of the main input file, in the form 943of a C string constant. This is the source file that was specified 944as an argument when the C compiler was invoked. 945 946@item __INCLUDE_LEVEL__ 947@findex __INCLUDE_LEVEL_ 948This macro expands to a decimal integer constant that represents the 949depth of nesting in include files. The value of this macro is 950incremented on every @samp{#include} directive and decremented at every 951end of file. For input files specified by command line arguments, 952the nesting level is zero. 953 954@item __VERSION__ 955@findex __VERSION__ 956This macro expands to a string constant which describes the version number of 957GNU C@. The string is normally a sequence of decimal numbers separated 958by periods, such as @samp{"2.6.0"}. 959 960@item __OPTIMIZE__ 961@findex __OPTIMIZE__ 962GNU CC defines this macro in optimizing compilations. It causes certain 963GNU header files to define alternative macro definitions for some system 964library functions. You should not refer to or test the definition of 965this macro unless you make very sure that programs will execute with the 966same effect regardless. 967 968@item __CHAR_UNSIGNED__ 969@findex __CHAR_UNSIGNED__ 970GNU C defines this macro if and only if the data type @code{char} is 971unsigned on the target machine. It exists to cause the standard header 972file @file{limits.h} to work correctly. You should not refer to this 973macro yourself; instead, refer to the standard macros defined in 974@file{limits.h}. The preprocessor uses this macro to determine whether 975or not to sign-extend large character constants written in octal; see 976@ref{#if Directive,,The @samp{#if} Directive}. 977 978@item __REGISTER_PREFIX__ 979@findex __REGISTER_PREFIX__ 980This macro expands to a string (not a string constant) describing the 981prefix applied to CPU registers in assembler code. You can use it to 982write assembler code that is usable in multiple environments. For 983example, in the @samp{m68k-aout} environment it expands to the null 984string, but in the @samp{m68k-coff} environment it expands to the string 985@samp{%}. 986 987@item __USER_LABEL_PREFIX__ 988@findex __USER_LABEL_PREFIX__ 989Similar to @code{__REGISTER_PREFIX__}, but describes the prefix applied 990to user generated labels in assembler code. For example, in the 991@samp{m68k-aout} environment it expands to the string @samp{_}, but in 992the @samp{m68k-coff} environment it expands to the null string. This 993does not work with the @samp{-mno-underscores} option that the i386 994OSF/rose and m88k targets provide nor with the @samp{-mcall*} options of 995the rs6000 System V Release 4 target. 996@end table 997 998@node Nonstandard Predefined,, Standard Predefined, Predefined 999@subsubsection Nonstandard Predefined Macros 1000 1001The C preprocessor normally has several predefined macros that vary between 1002machines because their purpose is to indicate what type of system and 1003machine is in use. This manual, being for all systems and machines, cannot 1004tell you exactly what their names are; instead, we offer a list of some 1005typical ones. You can use @samp{cpp -dM} to see the values of 1006predefined macros; see @ref{Invocation}. 1007 1008Some nonstandard predefined macros describe the operating system in use, 1009with more or less specificity. For example, 1010 1011@table @code 1012@item unix 1013@findex unix 1014@samp{unix} is normally predefined on all Unix systems. 1015 1016@item BSD 1017@findex BSD 1018@samp{BSD} is predefined on recent versions of Berkeley Unix 1019(perhaps only in version 4.3). 1020@end table 1021 1022Other nonstandard predefined macros describe the kind of CPU, with more or 1023less specificity. For example, 1024 1025@table @code 1026@item vax 1027@findex vax 1028@samp{vax} is predefined on Vax computers. 1029 1030@item mc68000 1031@findex mc68000 1032@samp{mc68000} is predefined on most computers whose CPU is a Motorola 103368000, 68010 or 68020. 1034 1035@item m68k 1036@findex m68k 1037@samp{m68k} is also predefined on most computers whose CPU is a 68000, 103868010 or 68020; however, some makers use @samp{mc68000} and some use 1039@samp{m68k}. Some predefine both names. What happens in GNU C 1040depends on the system you are using it on. 1041 1042@item M68020 1043@findex M68020 1044@samp{M68020} has been observed to be predefined on some systems that 1045use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which 1046are less specific. 1047 1048@item _AM29K 1049@findex _AM29K 1050@itemx _AM29000 1051@findex _AM29000 1052Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000 1053CPU family. 1054 1055@item ns32000 1056@findex ns32000 1057@samp{ns32000} is predefined on computers which use the National 1058Semiconductor 32000 series CPU. 1059@end table 1060 1061Yet other nonstandard predefined macros describe the manufacturer of 1062the system. For example, 1063 1064@table @code 1065@item sun 1066@findex sun 1067@samp{sun} is predefined on all models of Sun computers. 1068 1069@item pyr 1070@findex pyr 1071@samp{pyr} is predefined on all models of Pyramid computers. 1072 1073@item sequent 1074@findex sequent 1075@samp{sequent} is predefined on all models of Sequent computers. 1076@end table 1077 1078These predefined symbols are not only nonstandard, they are contrary to the 1079ANSI standard because their names do not start with underscores. 1080Therefore, the option @samp{-ansi} inhibits the definition of these 1081symbols. 1082 1083This tends to make @samp{-ansi} useless, since many programs depend on the 1084customary nonstandard predefined symbols. Even system header files check 1085them and will generate incorrect declarations if they do not find the names 1086that are expected. You might think that the header files supplied for the 1087Uglix computer would not need to test what machine they are running on, 1088because they can simply assume it is the Uglix; but often they do, and they 1089do so using the customary names. As a result, very few C programs will 1090compile with @samp{-ansi}. We intend to avoid such problems on the GNU 1091system. 1092 1093What, then, should you do in an ANSI C program to test the type of machine 1094it will run on? 1095 1096GNU C offers a parallel series of symbols for this purpose, whose names 1097are made from the customary ones by adding @samp{__} at the beginning 1098and end. Thus, the symbol @code{__vax__} would be available on a Vax, 1099and so on. 1100 1101The set of nonstandard predefined names in the GNU C preprocessor is 1102controlled (when @code{cpp} is itself compiled) by the macro 1103@samp{CPP_PREDEFINES}, which should be a string containing @samp{-D} 1104options, separated by spaces. For example, on the Sun 3, we use the 1105following definition: 1106 1107@example 1108#define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" 1109@end example 1110 1111@noindent 1112This macro is usually specified in @file{tm.h}. 1113 1114@node Stringification, Concatenation, Predefined, Macros 1115@subsection Stringification 1116 1117@cindex stringification 1118@dfn{Stringification} means turning a code fragment into a string constant 1119whose contents are the text for the code fragment. For example, 1120stringifying @samp{foo (z)} results in @samp{"foo (z)"}. 1121 1122In the C preprocessor, stringification is an option available when macro 1123arguments are substituted into the macro definition. In the body of the 1124definition, when an argument name appears, the character @samp{#} before 1125the name specifies stringification of the corresponding actual argument 1126when it is substituted at that point in the definition. The same argument 1127may be substituted in other places in the definition without 1128stringification if the argument name appears in those places with no 1129@samp{#}. 1130 1131Here is an example of a macro definition that uses stringification: 1132 1133@smallexample 1134@group 1135#define WARN_IF(EXP) \ 1136do @{ if (EXP) \ 1137 fprintf (stderr, "Warning: " #EXP "\n"); @} \ 1138while (0) 1139@end group 1140@end smallexample 1141 1142@noindent 1143Here the actual argument for @samp{EXP} is substituted once as given, 1144into the @samp{if} statement, and once as stringified, into the 1145argument to @samp{fprintf}. The @samp{do} and @samp{while (0)} are 1146a kludge to make it possible to write @samp{WARN_IF (@var{arg});}, 1147which the resemblance of @samp{WARN_IF} to a function would make 1148C programmers want to do; see @ref{Swallow Semicolon}. 1149 1150The stringification feature is limited to transforming one macro argument 1151into one string constant: there is no way to combine the argument with 1152other text and then stringify it all together. But the example above shows 1153how an equivalent result can be obtained in ANSI Standard C using the 1154feature that adjacent string constants are concatenated as one string 1155constant. The preprocessor stringifies the actual value of @samp{EXP} 1156into a separate string constant, resulting in text like 1157 1158@smallexample 1159@group 1160do @{ if (x == 0) \ 1161 fprintf (stderr, "Warning: " "x == 0" "\n"); @} \ 1162while (0) 1163@end group 1164@end smallexample 1165 1166@noindent 1167but the C compiler then sees three consecutive string constants and 1168concatenates them into one, producing effectively 1169 1170@smallexample 1171do @{ if (x == 0) \ 1172 fprintf (stderr, "Warning: x == 0\n"); @} \ 1173while (0) 1174@end smallexample 1175 1176Stringification in C involves more than putting doublequote characters 1177around the fragment; it is necessary to put backslashes in front of all 1178doublequote characters, and all backslashes in string and character 1179constants, in order to get a valid C string constant with the proper 1180contents. Thus, stringifying @samp{p = "foo\n";} results in @samp{"p = 1181\"foo\\n\";"}. However, backslashes that are not inside of string or 1182character constants are not duplicated: @samp{\n} by itself stringifies to 1183@samp{"\n"}. 1184 1185Whitespace (including comments) in the text being stringified is handled 1186according to precise rules. All leading and trailing whitespace is ignored. 1187Any sequence of whitespace in the middle of the text is converted to 1188a single space in the stringified result. 1189 1190@node Concatenation, Undefining, Stringification, Macros 1191@subsection Concatenation 1192@cindex concatenation 1193@cindex @samp{##} 1194@dfn{Concatenation} means joining two strings into one. In the context 1195of macro expansion, concatenation refers to joining two lexical units 1196into one longer one. Specifically, an actual argument to the macro can be 1197concatenated with another actual argument or with fixed text to produce 1198a longer name. The longer name might be the name of a function, 1199variable or type, or a C keyword; it might even be the name of another 1200macro, in which case it will be expanded. 1201 1202When you define a macro, you request concatenation with the special 1203operator @samp{##} in the macro body. When the macro is called, 1204after actual arguments are substituted, all @samp{##} operators are 1205deleted, and so is any whitespace next to them (including whitespace 1206that was part of an actual argument). The result is to concatenate 1207the syntactic tokens on either side of the @samp{##}. 1208 1209Consider a C program that interprets named commands. There probably needs 1210to be a table of commands, perhaps an array of structures declared as 1211follows: 1212 1213@example 1214struct command 1215@{ 1216 char *name; 1217 void (*function) (); 1218@}; 1219 1220struct command commands[] = 1221@{ 1222 @{ "quit", quit_command@}, 1223 @{ "help", help_command@}, 1224 @dots{} 1225@}; 1226@end example 1227 1228It would be cleaner not to have to give each command name twice, once in 1229the string constant and once in the function name. A macro which takes the 1230name of a command as an argument can make this unnecessary. The string 1231constant can be created with stringification, and the function name by 1232concatenating the argument with @samp{_command}. Here is how it is done: 1233 1234@example 1235#define COMMAND(NAME) @{ #NAME, NAME ## _command @} 1236 1237struct command commands[] = 1238@{ 1239 COMMAND (quit), 1240 COMMAND (help), 1241 @dots{} 1242@}; 1243@end example 1244 1245The usual case of concatenation is concatenating two names (or a name and a 1246number) into a longer name. But this isn't the only valid case. It is 1247also possible to concatenate two numbers (or a number and a name, such as 1248@samp{1.5} and @samp{e3}) into a number. Also, multi-character operators 1249such as @samp{+=} can be formed by concatenation. In some cases it is even 1250possible to piece together a string constant. However, two pieces of text 1251that don't together form a valid lexical unit cannot be concatenated. For 1252example, concatenation with @samp{x} on one side and @samp{+} on the other 1253is not meaningful because those two characters can't fit together in any 1254lexical unit of C@. The ANSI standard says that such attempts at 1255concatenation are undefined, but in the GNU C preprocessor it is well 1256defined: it puts the @samp{x} and @samp{+} side by side with no particular 1257special results. 1258 1259Keep in mind that the C preprocessor converts comments to whitespace before 1260macros are even considered. Therefore, you cannot create a comment by 1261concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a 1262comment is not a lexical unit, but rather the beginning of a ``long'' space 1263character. Also, you can freely use comments next to a @samp{##} in a 1264macro definition, or in actual arguments that will be concatenated, because 1265the comments will be converted to spaces at first sight, and concatenation 1266will later discard the spaces. 1267 1268@node Undefining, Redefining, Concatenation, Macros 1269@subsection Undefining Macros 1270 1271@cindex undefining macros 1272To @dfn{undefine} a macro means to cancel its definition. This is done 1273with the @samp{#undef} directive. @samp{#undef} is followed by the macro 1274name to be undefined. 1275 1276Like definition, undefinition occurs at a specific point in the source 1277file, and it applies starting from that point. The name ceases to be a 1278macro name, and from that point on it is treated by the preprocessor as if 1279it had never been a macro name. 1280 1281For example, 1282 1283@example 1284#define FOO 4 1285x = FOO; 1286#undef FOO 1287x = FOO; 1288@end example 1289 1290@noindent 1291expands into 1292 1293@example 1294x = 4; 1295 1296x = FOO; 1297@end example 1298 1299@noindent 1300In this example, @samp{FOO} had better be a variable or function as well 1301as (temporarily) a macro, in order for the result of the expansion to be 1302valid C code. 1303 1304The same form of @samp{#undef} directive will cancel definitions with 1305arguments or definitions that don't expect arguments. The @samp{#undef} 1306directive has no effect when used on a name not currently defined as a macro. 1307 1308@node Redefining, Macro Pitfalls, Undefining, Macros 1309@subsection Redefining Macros 1310 1311@cindex redefining macros 1312@dfn{Redefining} a macro means defining (with @samp{#define}) a name that 1313is already defined as a macro. 1314 1315A redefinition is trivial if the new definition is transparently identical 1316to the old one. You probably wouldn't deliberately write a trivial 1317redefinition, but they can happen automatically when a header file is 1318included more than once (@pxref{Header Files}), so they are accepted 1319silently and without effect. 1320 1321Nontrivial redefinition is considered likely to be an error, so 1322it provokes a warning message from the preprocessor. However, sometimes it 1323is useful to change the definition of a macro in mid-compilation. You can 1324inhibit the warning by undefining the macro with @samp{#undef} before the 1325second definition. 1326 1327In order for a redefinition to be trivial, the new definition must 1328exactly match the one already in effect, with two possible exceptions: 1329 1330@itemize @bullet 1331@item 1332Whitespace may be added or deleted at the beginning or the end. 1333 1334@item 1335Whitespace may be changed in the middle (but not inside strings). 1336However, it may not be eliminated entirely, and it may not be added 1337where there was no whitespace at all. 1338@end itemize 1339 1340Recall that a comment counts as whitespace. 1341 1342@node Macro Pitfalls,, Redefining, Macros 1343@subsection Pitfalls and Subtleties of Macros 1344@cindex problems with macros 1345@cindex pitfalls of macros 1346 1347In this section we describe some special rules that apply to macros and 1348macro expansion, and point out certain cases in which the rules have 1349counterintuitive consequences that you must watch out for. 1350 1351@menu 1352* Misnesting:: Macros can contain unmatched parentheses. 1353* Macro Parentheses:: Why apparently superfluous parentheses 1354 may be necessary to avoid incorrect grouping. 1355* Swallow Semicolon:: Macros that look like functions 1356 but expand into compound statements. 1357* Side Effects:: Unsafe macros that cause trouble when 1358 arguments contain side effects. 1359* Self-Reference:: Macros whose definitions use the macros' own names. 1360* Argument Prescan:: Actual arguments are checked for macro calls 1361 before they are substituted. 1362* Cascaded Macros:: Macros whose definitions use other macros. 1363* Newlines in Args:: Sometimes line numbers get confused. 1364@end menu 1365 1366@node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls 1367@subsubsection Improperly Nested Constructs 1368 1369Recall that when a macro is called with arguments, the arguments are 1370substituted into the macro body and the result is checked, together with 1371the rest of the input file, for more macro calls. 1372 1373It is possible to piece together a macro call coming partially from the 1374macro body and partially from the actual arguments. For example, 1375 1376@example 1377#define double(x) (2*(x)) 1378#define call_with_1(x) x(1) 1379@end example 1380 1381@noindent 1382would expand @samp{call_with_1 (double)} into @samp{(2*(1))}. 1383 1384Macro definitions do not have to have balanced parentheses. By writing an 1385unbalanced open parenthesis in a macro body, it is possible to create a 1386macro call that begins inside the macro body but ends outside of it. For 1387example, 1388 1389@example 1390#define strange(file) fprintf (file, "%s %d", 1391@dots{} 1392strange(stderr) p, 35) 1393@end example 1394 1395@noindent 1396This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}! 1397 1398@node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls 1399@subsubsection Unintended Grouping of Arithmetic 1400@cindex parentheses in macro bodies 1401 1402You may have noticed that in most of the macro definition examples shown 1403above, each occurrence of a macro argument name had parentheses around it. 1404In addition, another pair of parentheses usually surround the entire macro 1405definition. Here is why it is best to write macros that way. 1406 1407Suppose you define a macro as follows, 1408 1409@example 1410#define ceil_div(x, y) (x + y - 1) / y 1411@end example 1412 1413@noindent 1414whose purpose is to divide, rounding up. (One use for this operation is 1415to compute how many @samp{int} objects are needed to hold a certain 1416number of @samp{char} objects.) Then suppose it is used as follows: 1417 1418@example 1419a = ceil_div (b & c, sizeof (int)); 1420@end example 1421 1422@noindent 1423This expands into 1424 1425@example 1426a = (b & c + sizeof (int) - 1) / sizeof (int); 1427@end example 1428 1429@noindent 1430which does not do what is intended. The operator-precedence rules of 1431C make it equivalent to this: 1432 1433@example 1434a = (b & (c + sizeof (int) - 1)) / sizeof (int); 1435@end example 1436 1437@noindent 1438But what we want is this: 1439 1440@example 1441a = ((b & c) + sizeof (int) - 1)) / sizeof (int); 1442@end example 1443 1444@noindent 1445Defining the macro as 1446 1447@example 1448#define ceil_div(x, y) ((x) + (y) - 1) / (y) 1449@end example 1450 1451@noindent 1452provides the desired result. 1453 1454Unintended grouping can result in another way. Consider 1455@samp{sizeof ceil_div(1, 2)}. That has the appearance of a C expression 1456that would compute the size of the type of @samp{ceil_div (1, 2)}, but in 1457fact it means something very different. Here is what it expands to: 1458 1459@example 1460sizeof ((1) + (2) - 1) / (2) 1461@end example 1462 1463@noindent 1464This would take the size of an integer and divide it by two. The precedence 1465rules have put the division outside the @samp{sizeof} when it was intended 1466to be inside. 1467 1468Parentheses around the entire macro definition can prevent such problems. 1469Here, then, is the recommended way to define @samp{ceil_div}: 1470 1471@example 1472#define ceil_div(x, y) (((x) + (y) - 1) / (y)) 1473@end example 1474 1475@node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls 1476@subsubsection Swallowing the Semicolon 1477 1478@cindex semicolons (after macro calls) 1479Often it is desirable to define a macro that expands into a compound 1480statement. Consider, for example, the following macro, that advances a 1481pointer (the argument @samp{p} says where to find it) across whitespace 1482characters: 1483 1484@example 1485#define SKIP_SPACES(p, limit) \ 1486@{ register char *lim = (limit); \ 1487 while (p != lim) @{ \ 1488 if (*p++ != ' ') @{ \ 1489 p--; break; @}@}@} 1490@end example 1491 1492@noindent 1493Here Backslash-Newline is used to split the macro definition, which must 1494be a single line, so that it resembles the way such C code would be 1495laid out if not part of a macro definition. 1496 1497A call to this macro might be @samp{SKIP_SPACES (p, lim)}. Strictly 1498speaking, the call expands to a compound statement, which is a complete 1499statement with no need for a semicolon to end it. But it looks like a 1500function call. So it minimizes confusion if you can use it like a function 1501call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);} 1502 1503But this can cause trouble before @samp{else} statements, because the 1504semicolon is actually a null statement. Suppose you write 1505 1506@example 1507if (*p != 0) 1508 SKIP_SPACES (p, lim); 1509else @dots{} 1510@end example 1511 1512@noindent 1513The presence of two statements---the compound statement and a null 1514statement---in between the @samp{if} condition and the @samp{else} 1515makes invalid C code. 1516 1517The definition of the macro @samp{SKIP_SPACES} can be altered to solve 1518this problem, using a @samp{do @dots{} while} statement. Here is how: 1519 1520@example 1521#define SKIP_SPACES(p, limit) \ 1522do @{ register char *lim = (limit); \ 1523 while (p != lim) @{ \ 1524 if (*p++ != ' ') @{ \ 1525 p--; break; @}@}@} \ 1526while (0) 1527@end example 1528 1529Now @samp{SKIP_SPACES (p, lim);} expands into 1530 1531@example 1532do @{@dots{}@} while (0); 1533@end example 1534 1535@noindent 1536which is one statement. 1537 1538@node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls 1539@subsubsection Duplication of Side Effects 1540 1541@cindex side effects (in macro arguments) 1542@cindex unsafe macros 1543Many C programs define a macro @samp{min}, for ``minimum'', like this: 1544 1545@example 1546#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1547@end example 1548 1549When you use this macro with an argument containing a side effect, 1550as shown here, 1551 1552@example 1553next = min (x + y, foo (z)); 1554@end example 1555 1556@noindent 1557it expands as follows: 1558 1559@example 1560next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 1561@end example 1562 1563@noindent 1564where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)} 1565for @samp{Y}. 1566 1567The function @samp{foo} is used only once in the statement as it appears 1568in the program, but the expression @samp{foo (z)} has been substituted 1569twice into the macro expansion. As a result, @samp{foo} might be called 1570two times when the statement is executed. If it has side effects or 1571if it takes a long time to compute, the results might not be what you 1572intended. We say that @samp{min} is an @dfn{unsafe} macro. 1573 1574The best solution to this problem is to define @samp{min} in a way that 1575computes the value of @samp{foo (z)} only once. The C language offers no 1576standard way to do this, but it can be done with GNU C extensions as 1577follows: 1578 1579@example 1580#define min(X, Y) \ 1581(@{ typeof (X) __x = (X), __y = (Y); \ 1582 (__x < __y) ? __x : __y; @}) 1583@end example 1584 1585If you do not wish to use GNU C extensions, the only solution is to be 1586careful when @emph{using} the macro @samp{min}. For example, you can 1587calculate the value of @samp{foo (z)}, save it in a variable, and use that 1588variable in @samp{min}: 1589 1590@example 1591#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1592@dots{} 1593@{ 1594 int tem = foo (z); 1595 next = min (x + y, tem); 1596@} 1597@end example 1598 1599@noindent 1600(where we assume that @samp{foo} returns type @samp{int}). 1601 1602@node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls 1603@subsubsection Self-Referential Macros 1604 1605@cindex self-reference 1606A @dfn{self-referential} macro is one whose name appears in its definition. 1607A special feature of ANSI Standard C is that the self-reference is not 1608considered a macro call. It is passed into the preprocessor output 1609unchanged. 1610 1611Let's consider an example: 1612 1613@example 1614#define foo (4 + foo) 1615@end example 1616 1617@noindent 1618where @samp{foo} is also a variable in your program. 1619 1620Following the ordinary rules, each reference to @samp{foo} will expand into 1621@samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(4 1622+ (4 + foo))}; and so on until it causes a fatal error (memory full) in the 1623preprocessor. 1624 1625However, the special rule about self-reference cuts this process short 1626after one step, at @samp{(4 + foo)}. Therefore, this macro definition 1627has the possibly useful effect of causing the program to add 4 to 1628the value of @samp{foo} wherever @samp{foo} is referred to. 1629 1630In most cases, it is a bad idea to take advantage of this feature. A 1631person reading the program who sees that @samp{foo} is a variable will 1632not expect that it is a macro as well. The reader will come across the 1633identifier @samp{foo} in the program and think its value should be that 1634of the variable @samp{foo}, whereas in fact the value is four greater. 1635 1636The special rule for self-reference applies also to @dfn{indirect} 1637self-reference. This is the case where a macro @var{x} expands to use a 1638macro @samp{y}, and the expansion of @samp{y} refers to the macro 1639@samp{x}. The resulting reference to @samp{x} comes indirectly from the 1640expansion of @samp{x}, so it is a self-reference and is not further 1641expanded. Thus, after 1642 1643@example 1644#define x (4 + y) 1645#define y (2 * x) 1646@end example 1647 1648@noindent 1649@samp{x} would expand into @samp{(4 + (2 * x))}. Clear? 1650 1651But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}. 1652Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference 1653because @samp{x} is not ``in progress''. So it does expand. However, 1654the expansion of @samp{x} contains a reference to @samp{y}, and that 1655is an indirect self-reference now because @samp{y} is ``in progress''. 1656The result is that @samp{y} expands to @samp{(2 * (4 + y))}. 1657 1658It is not clear that this behavior would ever be useful, but it is specified 1659by the ANSI C standard, so you may need to understand it. 1660 1661@node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls 1662@subsubsection Separate Expansion of Macro Arguments 1663@cindex expansion of arguments 1664@cindex macro argument expansion 1665@cindex prescan of macro arguments 1666 1667We have explained that the expansion of a macro, including the substituted 1668actual arguments, is scanned over again for macro calls to be expanded. 1669 1670What really happens is more subtle: first each actual argument text is scanned 1671separately for macro calls. Then the results of this are substituted into 1672the macro body to produce the macro expansion, and the macro expansion 1673is scanned again for macros to expand. 1674 1675The result is that the actual arguments are scanned @emph{twice} to expand 1676macro calls in them. 1677 1678Most of the time, this has no effect. If the actual argument contained 1679any macro calls, they are expanded during the first scan. The result 1680therefore contains no macro calls, so the second scan does not change it. 1681If the actual argument were substituted as given, with no prescan, 1682the single remaining scan would find the same macro calls and produce 1683the same results. 1684 1685You might expect the double scan to change the results when a 1686self-referential macro is used in an actual argument of another macro 1687(@pxref{Self-Reference}): the self-referential macro would be expanded once 1688in the first scan, and a second time in the second scan. But this is not 1689what happens. The self-references that do not expand in the first scan are 1690marked so that they will not expand in the second scan either. 1691 1692The prescan is not done when an argument is stringified or concatenated. 1693Thus, 1694 1695@example 1696#define str(s) #s 1697#define foo 4 1698str (foo) 1699@end example 1700 1701@noindent 1702expands to @samp{"foo"}. Once more, prescan has been prevented from 1703having any noticeable effect. 1704 1705More precisely, stringification and concatenation use the argument as 1706written, in un-prescanned form. The same actual argument would be used in 1707prescanned form if it is substituted elsewhere without stringification or 1708concatenation. 1709 1710@example 1711#define str(s) #s lose(s) 1712#define foo 4 1713str (foo) 1714@end example 1715 1716expands to @samp{"foo" lose(4)}. 1717 1718You might now ask, ``Why mention the prescan, if it makes no difference? 1719And why not skip it and make the preprocessor faster?'' The answer is 1720that the prescan does make a difference in three special cases: 1721 1722@itemize @bullet 1723@item 1724Nested calls to a macro. 1725 1726@item 1727Macros that call other macros that stringify or concatenate. 1728 1729@item 1730Macros whose expansions contain unshielded commas. 1731@end itemize 1732 1733We say that @dfn{nested} calls to a macro occur when a macro's actual 1734argument contains a call to that very macro. For example, if @samp{f} 1735is a macro that expects one argument, @samp{f (f (1))} is a nested 1736pair of calls to @samp{f}. The desired expansion is made by 1737expanding @samp{f (1)} and substituting that into the definition of 1738@samp{f}. The prescan causes the expected result to happen. 1739Without the prescan, @samp{f (1)} itself would be substituted as 1740an actual argument, and the inner use of @samp{f} would appear 1741during the main scan as an indirect self-reference and would not 1742be expanded. Here, the prescan cancels an undesirable side effect 1743(in the medical, not computational, sense of the term) of the special 1744rule for self-referential macros. 1745 1746But prescan causes trouble in certain other cases of nested macro calls. 1747Here is an example: 1748 1749@example 1750#define foo a,b 1751#define bar(x) lose(x) 1752#define lose(x) (1 + (x)) 1753 1754bar(foo) 1755@end example 1756 1757@noindent 1758We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which 1759would then turn into @samp{(1 + (a,b))}. But instead, @samp{bar(foo)} 1760expands into @samp{lose(a,b)}, and you get an error because @code{lose} 1761requires a single argument. In this case, the problem is easily solved 1762by the same parentheses that ought to be used to prevent misnesting of 1763arithmetic operations: 1764 1765@example 1766#define foo (a,b) 1767#define bar(x) lose((x)) 1768@end example 1769 1770The problem is more serious when the operands of the macro are not 1771expressions; for example, when they are statements. Then parentheses 1772are unacceptable because they would make for invalid C code: 1773 1774@example 1775#define foo @{ int a, b; @dots{} @} 1776@end example 1777 1778@noindent 1779In GNU C you can shield the commas using the @samp{(@{@dots{}@})} 1780construct which turns a compound statement into an expression: 1781 1782@example 1783#define foo (@{ int a, b; @dots{} @}) 1784@end example 1785 1786Or you can rewrite the macro definition to avoid such commas: 1787 1788@example 1789#define foo @{ int a; int b; @dots{} @} 1790@end example 1791 1792There is also one case where prescan is useful. It is possible 1793to use prescan to expand an argument and then stringify it---if you use 1794two levels of macros. Let's add a new macro @samp{xstr} to the 1795example shown above: 1796 1797@example 1798#define xstr(s) str(s) 1799#define str(s) #s 1800#define foo 4 1801xstr (foo) 1802@end example 1803 1804This expands into @samp{"4"}, not @samp{"foo"}. The reason for the 1805difference is that the argument of @samp{xstr} is expanded at prescan 1806(because @samp{xstr} does not specify stringification or concatenation of 1807the argument). The result of prescan then forms the actual argument for 1808@samp{str}. @samp{str} uses its argument without prescan because it 1809performs stringification; but it cannot prevent or undo the prescanning 1810already done by @samp{xstr}. 1811 1812@node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls 1813@subsubsection Cascaded Use of Macros 1814 1815@cindex cascaded macros 1816@cindex macro body uses macro 1817A @dfn{cascade} of macros is when one macro's body contains a reference 1818to another macro. This is very common practice. For example, 1819 1820@example 1821#define BUFSIZE 1020 1822#define TABLESIZE BUFSIZE 1823@end example 1824 1825This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}. 1826The @samp{#define} for @samp{TABLESIZE} uses exactly the body you 1827specify---in this case, @samp{BUFSIZE}---and does not check to see whether 1828it too is the name of a macro. 1829 1830It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion 1831is checked for more macro names. 1832 1833This makes a difference if you change the definition of @samp{BUFSIZE} 1834at some point in the source file. @samp{TABLESIZE}, defined as shown, 1835will always expand using the definition of @samp{BUFSIZE} that is 1836currently in effect: 1837 1838@example 1839#define BUFSIZE 1020 1840#define TABLESIZE BUFSIZE 1841#undef BUFSIZE 1842#define BUFSIZE 37 1843@end example 1844 1845@noindent 1846Now @samp{TABLESIZE} expands (in two stages) to @samp{37}. (The 1847@samp{#undef} is to prevent any warning about the nontrivial 1848redefinition of @code{BUFSIZE}.) 1849 1850@node Newlines in Args,, Cascaded Macros, Macro Pitfalls 1851@subsection Newlines in Macro Arguments 1852@cindex newlines in macro arguments 1853 1854Traditional macro processing carries forward all newlines in macro 1855arguments into the expansion of the macro. This means that, if some of 1856the arguments are substituted more than once, or not at all, or out of 1857order, newlines can be duplicated, lost, or moved around within the 1858expansion. If the expansion consists of multiple statements, then the 1859effect is to distort the line numbers of some of these statements. The 1860result can be incorrect line numbers, in error messages or displayed in 1861a debugger. 1862 1863The GNU C preprocessor operating in ANSI C mode adjusts appropriately 1864for multiple use of an argument---the first use expands all the 1865newlines, and subsequent uses of the same argument produce no newlines. 1866But even in this mode, it can produce incorrect line numbering if 1867arguments are used out of order, or not used at all. 1868 1869Here is an example illustrating this problem: 1870 1871@example 1872#define ignore_second_arg(a,b,c) a; c 1873 1874ignore_second_arg (foo (), 1875 ignored (), 1876 syntax error); 1877@end example 1878 1879@noindent 1880The syntax error triggered by the tokens @samp{syntax error} results 1881in an error message citing line four, even though the statement text 1882comes from line five. 1883 1884@node Conditionals, Combining Sources, Macros, Top 1885@section Conditionals 1886 1887@cindex conditionals 1888In a macro processor, a @dfn{conditional} is a directive that allows a part 1889of the program to be ignored during compilation, on some conditions. 1890In the C preprocessor, a conditional can test either an arithmetic expression 1891or whether a name is defined as a macro. 1892 1893A conditional in the C preprocessor resembles in some ways an @samp{if} 1894statement in C, but it is important to understand the difference between 1895them. The condition in an @samp{if} statement is tested during the execution 1896of your program. Its purpose is to allow your program to behave differently 1897from run to run, depending on the data it is operating on. The condition 1898in a preprocessing conditional directive is tested when your program is compiled. 1899Its purpose is to allow different code to be included in the program depending 1900on the situation at the time of compilation. 1901 1902@menu 1903* Uses: Conditional Uses. What conditionals are for. 1904* Syntax: Conditional Syntax. How conditionals are written. 1905* Deletion: Deleted Code. Making code into a comment. 1906* Macros: Conditionals-Macros. Why conditionals are used with macros. 1907* Assertions:: How and why to use assertions. 1908* Errors: #error Directive. Detecting inconsistent compilation parameters. 1909@end menu 1910 1911@node Conditional Uses 1912@subsection Why Conditionals are Used 1913 1914Generally there are three kinds of reason to use a conditional. 1915 1916@itemize @bullet 1917@item 1918A program may need to use different code depending on the machine or 1919operating system it is to run on. In some cases the code for one 1920operating system may be erroneous on another operating system; for 1921example, it might refer to library routines that do not exist on the 1922other system. When this happens, it is not enough to avoid executing 1923the invalid code: merely having it in the program makes it impossible 1924to link the program and run it. With a preprocessing conditional, the 1925offending code can be effectively excised from the program when it is 1926not valid. 1927 1928@item 1929You may want to be able to compile the same source file into two 1930different programs. Sometimes the difference between the programs is 1931that one makes frequent time-consuming consistency checks on its 1932intermediate data, or prints the values of those data for debugging, 1933while the other does not. 1934 1935@item 1936A conditional whose condition is always false is a good way to exclude 1937code from the program but keep it as a sort of comment for future 1938reference. 1939@end itemize 1940 1941Most simple programs that are intended to run on only one machine will 1942not need to use preprocessing conditionals. 1943 1944@node Conditional Syntax 1945@subsection Syntax of Conditionals 1946 1947@findex #if 1948A conditional in the C preprocessor begins with a @dfn{conditional 1949directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. 1950@xref{Conditionals-Macros}, for information on @samp{#ifdef} and 1951@samp{#ifndef}; only @samp{#if} is explained here. 1952 1953@menu 1954* If: #if Directive. Basic conditionals using @samp{#if} and @samp{#endif}. 1955* Else: #else Directive. Including some text if the condition fails. 1956* Elif: #elif Directive. Testing several alternative possibilities. 1957@end menu 1958 1959@node #if Directive 1960@subsubsection The @samp{#if} Directive 1961 1962The @samp{#if} directive in its simplest form consists of 1963 1964@example 1965#if @var{expression} 1966@var{controlled text} 1967#endif /* @var{expression} */ 1968@end example 1969 1970The comment following the @samp{#endif} is not required, but it is a good 1971practice because it helps people match the @samp{#endif} to the 1972corresponding @samp{#if}. Such comments should always be used, except in 1973short conditionals that are not nested. In fact, you can put anything at 1974all after the @samp{#endif} and it will be ignored by the GNU C preprocessor, 1975but only comments are acceptable in ANSI Standard C@. 1976 1977@var{expression} is a C expression of integer type, subject to stringent 1978restrictions. It may contain 1979 1980@itemize @bullet 1981@item 1982Integer constants, which are all regarded as @code{long} or 1983@code{unsigned long}. 1984 1985@item 1986Character constants, which are interpreted according to the character 1987set and conventions of the machine and operating system on which the 1988preprocessor is running. The GNU C preprocessor uses the C data type 1989@samp{char} for these character constants; therefore, whether some 1990character codes are negative is determined by the C compiler used to 1991compile the preprocessor. If it treats @samp{char} as signed, then 1992character codes large enough to set the sign bit will be considered 1993negative; otherwise, no character code is considered negative. 1994 1995@item 1996Arithmetic operators for addition, subtraction, multiplication, 1997division, bitwise operations, shifts, comparisons, and logical 1998operations (@samp{&&} and @samp{||}). 1999 2000@item 2001Identifiers that are not macros, which are all treated as zero(!). 2002 2003@item 2004Macro calls. All macro calls in the expression are expanded before 2005actual computation of the expression's value begins. 2006@end itemize 2007 2008Note that @samp{sizeof} operators and @code{enum}-type values are not allowed. 2009@code{enum}-type values, like all other identifiers that are not taken 2010as macro calls and expanded, are treated as zero. 2011 2012The @var{controlled text} inside of a conditional can include 2013preprocessing directives. Then the directives inside the conditional are 2014obeyed only if that branch of the conditional succeeds. The text can 2015also contain other conditional groups. However, the @samp{#if} and 2016@samp{#endif} directives must balance. 2017 2018@node #else Directive 2019@subsubsection The @samp{#else} Directive 2020 2021@findex #else 2022The @samp{#else} directive can be added to a conditional to provide 2023alternative text to be used if the condition is false. This is what 2024it looks like: 2025 2026@example 2027#if @var{expression} 2028@var{text-if-true} 2029#else /* Not @var{expression} */ 2030@var{text-if-false} 2031#endif /* Not @var{expression} */ 2032@end example 2033 2034If @var{expression} is nonzero, and thus the @var{text-if-true} is 2035active, then @samp{#else} acts like a failing conditional and the 2036@var{text-if-false} is ignored. Contrariwise, if the @samp{#if} 2037conditional fails, the @var{text-if-false} is considered included. 2038 2039@node #elif Directive 2040@subsubsection The @samp{#elif} Directive 2041 2042@findex #elif 2043One common case of nested conditionals is used to check for more than two 2044possible alternatives. For example, you might have 2045 2046@example 2047#if X == 1 2048@dots{} 2049#else /* X != 1 */ 2050#if X == 2 2051@dots{} 2052#else /* X != 2 */ 2053@dots{} 2054#endif /* X != 2 */ 2055#endif /* X != 1 */ 2056@end example 2057 2058Another conditional directive, @samp{#elif}, allows this to be abbreviated 2059as follows: 2060 2061@example 2062#if X == 1 2063@dots{} 2064#elif X == 2 2065@dots{} 2066#else /* X != 2 and X != 1*/ 2067@dots{} 2068#endif /* X != 2 and X != 1*/ 2069@end example 2070 2071@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the 2072middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not 2073require a matching @samp{#endif} of its own. Like @samp{#if}, the 2074@samp{#elif} directive includes an expression to be tested. 2075 2076The text following the @samp{#elif} is processed only if the original 2077@samp{#if}-condition failed and the @samp{#elif} condition succeeds. 2078More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif} 2079group. Then the text after each @samp{#elif} is processed only if the 2080@samp{#elif} condition succeeds after the original @samp{#if} and any 2081previous @samp{#elif} directives within it have failed. @samp{#else} is 2082equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any 2083number of @samp{#elif} directives, but @samp{#elif} may not follow 2084@samp{#else}. 2085 2086@node Deleted Code 2087@subsection Keeping Deleted Code for Future Reference 2088@cindex commenting out code 2089 2090If you replace or delete a part of the program but want to keep the old 2091code around as a comment for future reference, the easy way to do this 2092is to put @samp{#if 0} before it and @samp{#endif} after it. This is 2093better than using comment delimiters @samp{/*} and @samp{*/} since those 2094won't work if the code already contains comments (C comments do not 2095nest). 2096 2097This works even if the code being turned off contains conditionals, but 2098they must be entire conditionals (balanced @samp{#if} and @samp{#endif}). 2099 2100Conversely, do not use @samp{#if 0} for comments which are not C code. 2101Use the comment delimiters @samp{/*} and @samp{*/} instead. The 2102interior of @samp{#if 0} must consist of complete tokens; in particular, 2103singlequote characters must balance. But comments often contain 2104unbalanced singlequote characters (known in English as apostrophes). 2105These confuse @samp{#if 0}. They do not confuse @samp{/*}. 2106 2107@node Conditionals-Macros 2108@subsection Conditionals and Macros 2109 2110Conditionals are useful in connection with macros or assertions, because 2111those are the only ways that an expression's value can vary from one 2112compilation to another. A @samp{#if} directive whose expression uses no 2113macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you 2114might as well determine which one, by computing the value of the 2115expression yourself, and then simplify the program. 2116 2117For example, here is a conditional that tests the expression 2118@samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro. 2119 2120@example 2121#if BUFSIZE == 1020 2122 printf ("Large buffers!\n"); 2123#endif /* BUFSIZE is large */ 2124@end example 2125 2126(Programmers often wish they could test the size of a variable or data 2127type in @samp{#if}, but this does not work. The preprocessor does not 2128understand @code{sizeof}, or typedef names, or even the type keywords 2129such as @code{int}.) 2130 2131@findex defined 2132The special operator @samp{defined} is used in @samp{#if} expressions to 2133test whether a certain name is defined as a macro. Either @samp{defined 2134@var{name}} or @samp{defined (@var{name})} is an expression whose value 2135is 1 if @var{name} is defined as macro at the current point in the 2136program, and 0 otherwise. For the @samp{defined} operator it makes no 2137difference what the definition of the macro is; all that matters is 2138whether there is a definition. Thus, for example,@refill 2139 2140@example 2141#if defined (vax) || defined (ns16000) 2142@end example 2143 2144@noindent 2145would succeed if either of the names @samp{vax} and @samp{ns16000} is 2146defined as a macro. You can test the same condition using assertions 2147(@pxref{Assertions}), like this: 2148 2149@example 2150#if #cpu (vax) || #cpu (ns16000) 2151@end example 2152 2153If a macro is defined and later undefined with @samp{#undef}, 2154subsequent use of the @samp{defined} operator returns 0, because 2155the name is no longer defined. If the macro is defined again with 2156another @samp{#define}, @samp{defined} will recommence returning 1. 2157 2158@findex #ifdef 2159@findex #ifndef 2160Conditionals that test whether just one name is defined are very common, 2161so there are two special short conditional directives for this case. 2162 2163@table @code 2164@item #ifdef @var{name} 2165is equivalent to @samp{#if defined (@var{name})}. 2166 2167@item #ifndef @var{name} 2168is equivalent to @samp{#if ! defined (@var{name})}. 2169@end table 2170 2171Macro definitions can vary between compilations for several reasons. 2172 2173@itemize @bullet 2174@item 2175Some macros are predefined on each kind of machine. For example, on a 2176Vax, the name @samp{vax} is a predefined macro. On other machines, it 2177would not be defined. 2178 2179@item 2180Many more macros are defined by system header files. Different 2181systems and machines define different macros, or give them different 2182values. It is useful to test these macros with conditionals to avoid 2183using a system feature on a machine where it is not implemented. 2184 2185@item 2186Macros are a common way of allowing users to customize a program for 2187different machines or applications. For example, the macro 2188@samp{BUFSIZE} might be defined in a configuration file for your 2189program that is included as a header file in each source file. You 2190would use @samp{BUFSIZE} in a preprocessing conditional in order to 2191generate different code depending on the chosen configuration. 2192 2193@item 2194Macros can be defined or undefined with @samp{-D} and @samp{-U} 2195command options when you compile the program. You can arrange to 2196compile the same source file into two different programs by choosing 2197a macro name to specify which program you want, writing conditionals 2198to test whether or how this macro is defined, and then controlling 2199the state of the macro with compiler command options. 2200@xref{Invocation}. 2201@end itemize 2202 2203@ifinfo 2204Assertions are usually predefined, but can be defined with preprocessor 2205directives or command-line options. 2206@end ifinfo 2207 2208@node Assertions 2209@subsection Assertions 2210 2211@cindex assertions 2212@dfn{Assertions} are a more systematic alternative to macros in writing 2213conditionals to test what sort of computer or system the compiled 2214program will run on. Assertions are usually predefined, but you can 2215define them with preprocessing directives or command-line options. 2216 2217@cindex predicates 2218The macros traditionally used to describe the type of target are not 2219classified in any way according to which question they answer; they may 2220indicate a hardware architecture, a particular hardware model, an 2221operating system, a particular version of an operating system, or 2222specific configuration options. These are jumbled together in a single 2223namespace. In contrast, each assertion consists of a named question and 2224an answer. The question is usually called the @dfn{predicate}. 2225An assertion looks like this: 2226 2227@example 2228#@var{predicate} (@var{answer}) 2229@end example 2230 2231@noindent 2232You must use a properly formed identifier for @var{predicate}. The 2233value of @var{answer} can be any sequence of words; all characters are 2234significant except for leading and trailing whitespace, and differences 2235in internal whitespace sequences are ignored. Thus, @samp{x + y} is 2236different from @samp{x+y} but equivalent to @samp{x + y}. @samp{)} is 2237not allowed in an answer. 2238 2239@cindex testing predicates 2240Here is a conditional to test whether the answer @var{answer} is asserted 2241for the predicate @var{predicate}: 2242 2243@example 2244#if #@var{predicate} (@var{answer}) 2245@end example 2246 2247@noindent 2248There may be more than one answer asserted for a given predicate. If 2249you omit the answer, you can test whether @emph{any} answer is asserted 2250for @var{predicate}: 2251 2252@example 2253#if #@var{predicate} 2254@end example 2255 2256@findex #system 2257@findex #machine 2258@findex #cpu 2259Most of the time, the assertions you test will be predefined assertions. 2260GNU C provides three predefined predicates: @code{system}, @code{cpu}, 2261and @code{machine}. @code{system} is for assertions about the type of 2262software, @code{cpu} describes the type of computer architecture, and 2263@code{machine} gives more information about the computer. For example, 2264on a GNU system, the following assertions would be true: 2265 2266@example 2267#system (gnu) 2268#system (mach) 2269#system (mach 3) 2270#system (mach 3.@var{subversion}) 2271#system (hurd) 2272#system (hurd @var{version}) 2273@end example 2274 2275@noindent 2276and perhaps others. The alternatives with 2277more or less version information let you ask more or less detailed 2278questions about the type of system software. 2279 2280On a Unix system, you would find @code{#system (unix)} and perhaps one of: 2281@code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)}, 2282@code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)}, 2283@code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)} 2284with possible version numbers following. 2285 2286Other values for @code{system} are @code{#system (mvs)} 2287and @code{#system (vms)}. 2288 2289@strong{Portability note:} Many Unix C compilers provide only one answer 2290for the @code{system} assertion: @code{#system (unix)}, if they support 2291assertions at all. This is less than useful. 2292 2293An assertion with a multi-word answer is completely different from several 2294assertions with individual single-word answers. For example, the presence 2295of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true. 2296It also does not directly imply @code{system (mach)}, but in GNU C, that 2297last will normally be asserted as well. 2298 2299The current list of possible assertion values for @code{cpu} is: 2300@code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu 2301(clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu 2302(tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)}, 2303@code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu 2304(m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)}, 2305@code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)}, 2306@code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu 2307(tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}. 2308 2309@findex #assert 2310You can create assertions within a C program using @samp{#assert}, like 2311this: 2312 2313@example 2314#assert @var{predicate} (@var{answer}) 2315@end example 2316 2317@noindent 2318(Note the absence of a @samp{#} before @var{predicate}.) 2319 2320@cindex unassert 2321@cindex assertions, undoing 2322@cindex retracting assertions 2323@findex #unassert 2324Each time you do this, you assert a new true answer for @var{predicate}. 2325Asserting one answer does not invalidate previously asserted answers; 2326they all remain true. The only way to remove an assertion is with 2327@samp{#unassert}. @samp{#unassert} has the same syntax as 2328@samp{#assert}. You can also remove all assertions about 2329@var{predicate} like this: 2330 2331@example 2332#unassert @var{predicate} 2333@end example 2334 2335You can also add or cancel assertions using command options 2336when you run @code{gcc} or @code{cpp}. @xref{Invocation}. 2337 2338@node #error Directive 2339@subsection The @samp{#error} and @samp{#warning} Directives 2340 2341@findex #error 2342The directive @samp{#error} causes the preprocessor to report a fatal 2343error. The rest of the line that follows @samp{#error} is used as the 2344error message. The line must consist of complete tokens. 2345 2346You would use @samp{#error} inside of a conditional that detects a 2347combination of parameters which you know the program does not properly 2348support. For example, if you know that the program will not run 2349properly on a Vax, you might write 2350 2351@smallexample 2352@group 2353#ifdef __vax__ 2354#error "Won't work on Vaxen. See comments at get_last_object." 2355#endif 2356@end group 2357@end smallexample 2358 2359@noindent 2360@xref{Nonstandard Predefined}, for why this works. 2361 2362If you have several configuration parameters that must be set up by 2363the installation in a consistent way, you can use conditionals to detect 2364an inconsistency and report it with @samp{#error}. For example, 2365 2366@smallexample 2367#if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ 2368 || HASH_TABLE_SIZE % 5 == 0 2369#error HASH_TABLE_SIZE should not be divisible by a small prime 2370#endif 2371@end smallexample 2372 2373@findex #warning 2374The directive @samp{#warning} is like the directive @samp{#error}, but causes 2375the preprocessor to issue a warning and continue preprocessing. The rest of 2376the line that follows @samp{#warning} is used as the warning message. 2377 2378You might use @samp{#warning} in obsolete header files, with a message 2379directing the user to the header file which should be used instead. 2380 2381@node Combining Sources, Other Directives, Conditionals, Top 2382@section Combining Source Files 2383 2384@cindex line control 2385One of the jobs of the C preprocessor is to inform the C compiler of where 2386each line of C code came from: which source file and which line number. 2387 2388C code can come from multiple source files if you use @samp{#include}; 2389both @samp{#include} and the use of conditionals and macros can cause 2390the line number of a line in the preprocessor output to be different 2391from the line's number in the original source file. You will appreciate 2392the value of making both the C compiler (in error messages) and symbolic 2393debuggers such as GDB use the line numbers in your source file. 2394 2395The C preprocessor builds on this feature by offering a directive by which 2396you can control the feature explicitly. This is useful when a file for 2397input to the C preprocessor is the output from another program such as the 2398@code{bison} parser generator, which operates on another file that is the 2399true source file. Parts of the output from @code{bison} are generated from 2400scratch, other parts come from a standard parser file. The rest are copied 2401nearly verbatim from the source file, but their line numbers in the 2402@code{bison} output are not the same as their original line numbers. 2403Naturally you would like compiler error messages and symbolic debuggers to 2404know the original source file and line number of each line in the 2405@code{bison} input. 2406 2407@findex #line 2408@code{bison} arranges this by writing @samp{#line} directives into the output 2409file. @samp{#line} is a directive that specifies the original line number 2410and source file name for subsequent input in the current preprocessor input 2411file. @samp{#line} has three variants: 2412 2413@table @code 2414@item #line @var{linenum} 2415Here @var{linenum} is a decimal integer constant. This specifies that 2416the line number of the following line of input, in its original source file, 2417was @var{linenum}. 2418 2419@item #line @var{linenum} @var{filename} 2420Here @var{linenum} is a decimal integer constant and @var{filename} 2421is a string constant. This specifies that the following line of input 2422came originally from source file @var{filename} and its line number there 2423was @var{linenum}. Keep in mind that @var{filename} is not just a 2424file name; it is surrounded by doublequote characters so that it looks 2425like a string constant. 2426 2427@item #line @var{anything else} 2428@var{anything else} is checked for macro calls, which are expanded. 2429The result should be a decimal integer constant followed optionally 2430by a string constant, as described above. 2431@end table 2432 2433@samp{#line} directives alter the results of the @samp{__FILE__} and 2434@samp{__LINE__} predefined macros from that point on. @xref{Standard 2435Predefined}. 2436 2437The output of the preprocessor (which is the input for the rest of the 2438compiler) contains directives that look much like @samp{#line} directives. 2439They start with just @samp{#} instead of @samp{#line}, but this is 2440followed by a line number and file name as in @samp{#line}. @xref{Output}. 2441 2442@node Other Directives, Output, Combining Sources, Top 2443@section Miscellaneous Preprocessing Directives 2444 2445@cindex null directive 2446This section describes three additional preprocessing directives. They are 2447not very useful, but are mentioned for completeness. 2448 2449The @dfn{null directive} consists of a @samp{#} followed by a Newline, with 2450only whitespace (including comments) in between. A null directive is 2451understood as a preprocessing directive but has no effect on the preprocessor 2452output. The primary significance of the existence of the null directive is 2453that an input line consisting of just a @samp{#} will produce no output, 2454rather than a line of output containing just a @samp{#}. Supposedly 2455some old C programs contain such lines. 2456 2457@findex #pragma 2458The ANSI standard specifies that the effect of the @samp{#pragma} 2459directive is implementation-defined. In the GNU C preprocessor, 2460@samp{#pragma} directives are not used, except for @samp{#pragma once} 2461(@pxref{Once-Only}). However, they are left in the preprocessor output, 2462so they are available to the compilation pass. 2463 2464@findex #ident 2465The @samp{#ident} directive is supported for compatibility with certain 2466other systems. It is followed by a line of text. On some systems, the 2467text is copied into a special place in the object file; on most systems, 2468the text is ignored and this directive has no effect. Typically 2469@samp{#ident} is only used in header files supplied with those systems 2470where it is meaningful. 2471 2472@node Output, Invocation, Other Directives, Top 2473@section C Preprocessor Output 2474 2475@cindex output format 2476The output from the C preprocessor looks much like the input, except 2477that all preprocessing directive lines have been replaced with blank lines 2478and all comments with spaces. Whitespace within a line is not altered; 2479however, unless @samp{-traditional} is used, spaces may be inserted into 2480the expansions of macro calls to prevent tokens from being concatenated. 2481 2482Source file name and line number information is conveyed by lines of 2483the form 2484 2485@example 2486# @var{linenum} @var{filename} @var{flags} 2487@end example 2488 2489@noindent 2490which are inserted as needed into the middle of the input (but never 2491within a string or character constant). Such a line means that the 2492following line originated in file @var{filename} at line @var{linenum}. 2493 2494After the file name comes zero or more flags, which are @samp{1}, 2495@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces separate 2496them. Here is what the flags mean: 2497 2498@table @samp 2499@item 1 2500This indicates the start of a new file. 2501@item 2 2502This indicates returning to a file (after having included another file). 2503@item 3 2504This indicates that the following text comes from a system header file, 2505so certain warnings should be suppressed. 2506@item 4 2507This indicates that the following text should be treated as C@. 2508@c maybe cross reference NO_IMPLICIT_EXTERN_C 2509@end table 2510 2511@node Invocation, Concept Index, Output, Top 2512@section Invoking the C Preprocessor 2513@cindex invocation of the preprocessor 2514 2515Most often when you use the C preprocessor you will not have to invoke it 2516explicitly: the C compiler will do so automatically. However, the 2517preprocessor is sometimes useful on its own. 2518 2519The C preprocessor expects two file names as arguments, @var{infile} and 2520@var{outfile}. The preprocessor reads @var{infile} together with any other 2521files it specifies with @samp{#include}. All the output generated by the 2522combined input files is written in @var{outfile}. 2523 2524Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile} 2525means to read from standard input and as @var{outfile} means to write to 2526standard output. Also, if @var{outfile} or both file names are omitted, 2527the standard output and standard input are used for the omitted file names. 2528 2529@cindex options 2530Here is a table of command options accepted by the C preprocessor. 2531These options can also be given when compiling a C program; they are 2532passed along automatically to the preprocessor when it is invoked by the 2533compiler. 2534 2535@table @samp 2536@item -P 2537@findex -P 2538Inhibit generation of @samp{#}-lines with line-number information in 2539the output from the preprocessor (@pxref{Output}). This might be 2540useful when running the preprocessor on something that is not C code 2541and will be sent to a program which might be confused by the 2542@samp{#}-lines. 2543 2544@item -C 2545@findex -C 2546Do not discard comments: pass them through to the output file. 2547Comments appearing in arguments of a macro call will be copied to the 2548output before the expansion of the macro call. 2549 2550@item -traditional 2551@findex -traditional 2552Try to imitate the behavior of old-fashioned C, as opposed to ANSI C@. 2553 2554@itemize @bullet 2555@item 2556Traditional macro expansion pays no attention to singlequote or 2557doublequote characters; macro argument symbols are replaced by the 2558argument values even when they appear within apparent string or 2559character constants. 2560 2561@item 2562Traditionally, it is permissible for a macro expansion to end in the 2563middle of a string or character constant. The constant continues into 2564the text surrounding the macro call. 2565 2566@item 2567However, traditionally the end of the line terminates a string or 2568character constant, with no error. 2569 2570@item 2571In traditional C, a comment is equivalent to no text at all. (In ANSI 2572C, a comment counts as whitespace.) 2573 2574@item 2575Traditional C does not have the concept of a ``preprocessing number''. 2576It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+}, 2577and @samp{4}. 2578 2579@item 2580A macro is not suppressed within its own definition, in traditional C@. 2581Thus, any macro that is used recursively inevitably causes an error. 2582 2583@item 2584The character @samp{#} has no special meaning within a macro definition 2585in traditional C@. 2586 2587@item 2588In traditional C, the text at the end of a macro expansion can run 2589together with the text after the macro call, to produce a single token. 2590(This is impossible in ANSI C@.) 2591 2592@item 2593Traditionally, @samp{\} inside a macro argument suppresses the syntactic 2594significance of the following character. 2595@end itemize 2596 2597@cindex Fortran 2598@cindex unterminated 2599Use the @samp{-traditional} option when preprocessing Fortran code, 2600so that singlequotes and doublequotes 2601within Fortran comment lines 2602(which are generally not recognized as such by the preprocessor) 2603do not cause diagnostics 2604about unterminated character or string constants. 2605 2606However, this option does not prevent diagnostics 2607about unterminated comments 2608when a C-style comment appears to start, but not end, 2609within Fortran-style commentary. 2610 2611So, the following Fortran comment lines are accepted with 2612@samp{-traditional}: 2613 2614@smallexample 2615C This isn't an unterminated character constant 2616C Neither is "20000000000, an octal constant 2617C in some dialects of Fortran 2618@end smallexample 2619 2620However, this type of comment line will likely produce a diagnostic, 2621or at least unexpected output from the preprocessor, 2622due to the unterminated comment: 2623 2624@smallexample 2625C Some Fortran compilers accept /* as starting 2626C an inline comment. 2627@end smallexample 2628 2629@cindex g77 2630Note that @code{g77} automatically supplies 2631the @samp{-traditional} option 2632when it invokes the preprocessor. 2633However, a future version of @code{g77} 2634might use a different, more-Fortran-aware preprocessor 2635in place of @code{cpp}. 2636 2637@item -trigraphs 2638@findex -trigraphs 2639Process ANSI standard trigraph sequences. These are three-character 2640sequences, all starting with @samp{??}, that are defined by ANSI C to 2641stand for single characters. For example, @samp{??/} stands for 2642@samp{\}, so @samp{'??/n'} is a character constant for a newline. 2643Strictly speaking, the GNU C preprocessor does not support all 2644programs in ANSI Standard C unless @samp{-trigraphs} is used, but if 2645you ever notice the difference it will be with relief. 2646 2647You don't want to know any more about trigraphs. 2648 2649@item -pedantic 2650@findex -pedantic 2651Issue warnings required by the ANSI C standard in certain cases such 2652as when text other than a comment follows @samp{#else} or @samp{#endif}. 2653 2654@item -pedantic-errors 2655@findex -pedantic-errors 2656Like @samp{-pedantic}, except that errors are produced rather than 2657warnings. 2658 2659@item -Wtrigraphs 2660@findex -Wtrigraphs 2661Warn if any trigraphs are encountered. Currently this only works if you 2662have turned trigraphs on with @samp{-trigraphs} or @samp{-ansi}; in the 2663future this restriction will be removed. 2664 2665@item -Wcomment 2666@findex -Wcomment 2667@ignore 2668@c "Not worth documenting" both singular and plural forms of this 2669@c option, per RMS. But also unclear which is better; hence may need to 2670@c switch this at some future date. pesch@cygnus.com, 2jan92. 2671@itemx -Wcomments 2672(Both forms have the same effect). 2673@end ignore 2674Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} 2675comment, or whenever a Backslash-Newline appears in a @samp{//} comment. 2676 2677@item -Wall 2678@findex -Wall 2679Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not 2680@samp{-Wtraditional} or @samp{-Wundef}). 2681 2682@item -Wtraditional 2683@findex -Wtraditional 2684Warn about certain constructs that behave differently in traditional and 2685ANSI C@. 2686 2687@item -Wundef 2688@findex -Wundef 2689Warn if an undefined identifier is evaluated in an @samp{#if} directive. 2690 2691@item -I @var{directory} 2692@findex -I 2693Add the directory @var{directory} to the head of the list of 2694directories to be searched for header files (@pxref{Include Syntax}). 2695This can be used to override a system header file, substituting your 2696own version, since these directories are searched before the system 2697header file directories. If you use more than one @samp{-I} option, 2698the directories are scanned in left-to-right order; the standard 2699system directories come after. 2700 2701@item -I- 2702Any directories specified with @samp{-I} options before the @samp{-I-} 2703option are searched only for the case of @samp{#include "@var{file}"}; 2704they are not searched for @samp{#include <@var{file}>}. 2705 2706If additional directories are specified with @samp{-I} options after 2707the @samp{-I-}, these directories are searched for all @samp{#include} 2708directives. 2709 2710In addition, the @samp{-I-} option inhibits the use of the current 2711directory as the first search directory for @samp{#include "@var{file}"}. 2712Therefore, the current directory is searched only if it is requested 2713explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.} 2714allows you to control precisely which directories are searched before 2715the current one and which are searched after. 2716 2717@item -nostdinc 2718@findex -nostdinc 2719Do not search the standard system directories for header files. 2720Only the directories you have specified with @samp{-I} options 2721(and the current directory, if appropriate) are searched. 2722 2723@item -nostdinc++ 2724@findex -nostdinc++ 2725Do not search for header files in the C++-specific standard directories, 2726but do still search the other standard directories. 2727(This option is used when building the C++ library.) 2728 2729@item -remap 2730@findex -remap 2731When searching for a header file in a directory, remap file names if a 2732file named @file{header.gcc} exists in that directory. This can be used 2733to work around limitations of file systems with file name restrictions. 2734The @file{header.gcc} file should contain a series of lines with two 2735tokens on each line: the first token is the name to map, and the second 2736token is the actual name to use. 2737 2738@item -D @var{name} 2739@findex -D 2740Predefine @var{name} as a macro, with definition @samp{1}. 2741 2742@item -D @var{name}=@var{definition} 2743Predefine @var{name} as a macro, with definition @var{definition}. 2744There are no restrictions on the contents of @var{definition}, but if 2745you are invoking the preprocessor from a shell or shell-like program you 2746may need to use the shell's quoting syntax to protect characters such as 2747spaces that have a meaning in the shell syntax. If you use more than 2748one @samp{-D} for the same @var{name}, the rightmost definition takes 2749effect. 2750 2751@item -U @var{name} 2752@findex -U 2753Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are 2754specified for one name, the @samp{-U} beats the @samp{-D} and the name 2755is not predefined. 2756 2757@item -undef 2758@findex -undef 2759Do not predefine any nonstandard macros. 2760 2761@item -gcc 2762@findex -gcc 2763Define the macros @var{__GNUC__} and @var{__GNUC_MINOR__}. These are 2764defined automatically when you use @samp{gcc -E}; you can turn them off 2765in that case with @samp{-no-gcc}. 2766 2767@item -A @var{predicate}(@var{answer}) 2768@findex -A 2769Make an assertion with the predicate @var{predicate} and answer 2770@var{answer}. @xref{Assertions}. 2771 2772@noindent 2773You can use @samp{-A-} to disable all predefined assertions; it also 2774undefines all predefined macros and all macros that preceded it on the 2775command line. 2776 2777@item -dM 2778@findex -dM 2779Instead of outputting the result of preprocessing, output a list of 2780@samp{#define} directives for all the macros defined during the 2781execution of the preprocessor, including predefined macros. This gives 2782you a way of finding out what is predefined in your version of the 2783preprocessor; assuming you have no file @samp{foo.h}, the command 2784 2785@example 2786touch foo.h; cpp -dM foo.h 2787@end example 2788 2789@noindent 2790will show the values of any predefined macros. 2791 2792@item -dD 2793@findex -dD 2794Like @samp{-dM} except in two respects: it does @emph{not} include the 2795predefined macros, and it outputs @emph{both} the @samp{#define} 2796directives and the result of preprocessing. Both kinds of output go to 2797the standard output file. 2798 2799@item -dI 2800@findex -dI 2801Output @samp{#include} directives in addition to the result of preprocessing. 2802 2803@item -M [-MG] 2804@findex -M 2805Instead of outputting the result of preprocessing, output a rule 2806suitable for @code{make} describing the dependencies of the main 2807source file. The preprocessor outputs one @code{make} rule containing 2808the object file name for that source file, a colon, and the names of 2809all the included files. If there are many included files then the 2810rule is split into several lines using @samp{\}-newline. 2811 2812@samp{-MG} says to treat missing header files as generated files and assume 2813they live in the same directory as the source file. It must be specified 2814in addition to @samp{-M}. 2815 2816This feature is used in automatic updating of makefiles. 2817 2818@item -MM [-MG] 2819@findex -MM 2820Like @samp{-M} but mention only the files included with @samp{#include 2821"@var{file}"}. System header files included with @samp{#include 2822<@var{file}>} are omitted. 2823 2824@item -MD @var{file} 2825@findex -MD 2826Like @samp{-M} but the dependency information is written to @var{file}. 2827This is in addition to compiling the file as specified---@samp{-MD} does 2828not inhibit ordinary compilation the way @samp{-M} does. 2829 2830When invoking @code{gcc}, do not specify the @var{file} argument. 2831@code{gcc} will create file names made by replacing ".c" with ".d" at 2832the end of the input file names. 2833 2834In Mach, you can use the utility @code{md} to merge multiple dependency 2835files into a single dependency file suitable for using with the @samp{make} 2836command. 2837 2838@item -MMD @var{file} 2839@findex -MMD 2840Like @samp{-MD} except mention only user header files, not system 2841header files. 2842 2843@item -H 2844@findex -H 2845Print the name of each header file used, in addition to other normal 2846activities. 2847 2848@item -imacros @var{file} 2849@findex -imacros 2850Process @var{file} as input, discarding the resulting output, before 2851processing the regular input file. Because the output generated from 2852@var{file} is discarded, the only effect of @samp{-imacros @var{file}} 2853is to make the macros defined in @var{file} available for use in the 2854main input. 2855 2856@item -include @var{file} 2857@findex -include 2858Process @var{file} as input, and include all the resulting output, 2859before processing the regular input file. 2860 2861@item -idirafter @var{dir} 2862@findex -idirafter 2863@cindex second include path 2864Add the directory @var{dir} to the second include path. The directories 2865on the second include path are searched when a header file is not found 2866in any of the directories in the main include path (the one that 2867@samp{-I} adds to). 2868 2869@item -iprefix @var{prefix} 2870@findex -iprefix 2871Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix} 2872options. 2873 2874@item -iwithprefix @var{dir} 2875@findex -iwithprefix 2876Add a directory to the second include path. The directory's name is 2877made by concatenating @var{prefix} and @var{dir}, where @var{prefix} 2878was specified previously with @samp{-iprefix}. 2879 2880@item -isystem @var{dir} 2881@findex -isystem 2882Add a directory to the beginning of the second include path, marking it 2883as a system directory, so that it gets the same special treatment as 2884is applied to the standard system directories. 2885 2886@item -x c 2887@itemx -x c++ 2888@itemx -x objective-c 2889@itemx -x assembler-with-cpp 2890@findex -x c 2891@findex -x objective-c 2892@findex -x assembler-with-cpp 2893Specify the source language: C, C++, Objective-C, or assembly. This has 2894nothing to do with standards conformance or extensions; it merely 2895selects which base syntax to expect. If you give none of these options, 2896cpp will deduce the language from the extension of the source file: 2897@samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common 2898extensions for C++ and assembly are also recognized. If cpp does not 2899recognize the extension, it will treat the file as C; this is the most 2900generic mode. 2901 2902@strong{Note:} Previous versions of cpp accepted a @samp{-lang} option 2903which selected both the language and the standards conformance level. 2904This option has been removed, because it conflicts with the @samp{-l} 2905option. 2906 2907@item -std=@var{standard} 2908@itemx -ansi 2909@findex -std 2910@findex -ansi 2911Specify the standard to which the code should conform. Currently cpp 2912only knows about the standards for C; other language standards will be 2913added in the future. 2914 2915@var{standard} 2916may be one of: 2917@table @code 2918@item iso9899:1990 2919The ISO C standard from 1990. 2920 2921@item iso9899:199409 2922@itemx c89 2923The 1990 C standard, as amended in 1994. @samp{c89} is the customary 2924shorthand for this version of the standard. 2925 2926The @samp{-ansi} option is equivalent to @samp{-std=c89}. 2927 2928@item iso9899:199x 2929@itemx c9x 2930The revised ISO C standard, which is expected to be promulgated some 2931time in 1999. It has not been approved yet, hence the @samp{x}. 2932 2933@item gnu89 2934The 1990 C standard plus GNU extensions. This is the default. 2935 2936@item gnu9x 2937The 199x C standard plus GNU extensions. 2938@end table 2939 2940@item -Wp,-lint 2941@findex -lint 2942Look for commands to the program checker @code{lint} embedded in 2943comments, and emit them preceded by @samp{#pragma lint}. For example, 2944the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint 2945NOTREACHED}. 2946 2947Because of the clash with @samp{-l}, you must use the awkward syntax 2948above. In a future release, this option will be replaced by 2949@samp{-flint} or @samp{-Wlint}; we are not sure which yet. 2950 2951@item -$ 2952@findex -$ 2953Forbid the use of @samp{$} in identifiers. The C standard does not 2954permit this, but it is a common extension. 2955 2956@end table 2957 2958@node Concept Index, Index, Invocation, Top 2959@unnumbered Concept Index 2960@printindex cp 2961 2962@node Index,, Concept Index, Top 2963@unnumbered Index of Directives, Macros and Options 2964@printindex fn 2965 2966@contents 2967@bye 2968