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