[8833] | 1 | This is Info file cpp.info, produced by Makeinfo-1.55 from the input |
---|
| 2 | file cpp.texi. |
---|
| 3 | |
---|
| 4 | This file documents the GNU C Preprocessor. |
---|
| 5 | |
---|
| 6 | Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software |
---|
| 7 | Foundation, Inc. |
---|
| 8 | |
---|
| 9 | Permission is granted to make and distribute verbatim copies of this |
---|
| 10 | manual provided the copyright notice and this permission notice are |
---|
| 11 | preserved on all copies. |
---|
| 12 | |
---|
| 13 | Permission is granted to copy and distribute modified versions of |
---|
| 14 | this manual under the conditions for verbatim copying, provided also |
---|
| 15 | that the entire resulting derived work is distributed under the terms |
---|
| 16 | of a permission notice identical to this one. |
---|
| 17 | |
---|
| 18 | Permission is granted to copy and distribute translations of this |
---|
| 19 | manual into another language, under the above conditions for modified |
---|
| 20 | versions. |
---|
| 21 | |
---|
| 22 | |
---|
| 23 | File: cpp.info, Node: Top, Next: Global Actions, Up: (DIR) |
---|
| 24 | |
---|
| 25 | The C Preprocessor |
---|
| 26 | ****************** |
---|
| 27 | |
---|
| 28 | The C preprocessor is a "macro processor" that is used automatically |
---|
| 29 | by the C compiler to transform your program before actual compilation. |
---|
| 30 | It is called a macro processor because it allows you to define "macros", |
---|
| 31 | which are brief abbreviations for longer constructs. |
---|
| 32 | |
---|
| 33 | The C preprocessor provides four separate facilities that you can |
---|
| 34 | use as you see fit: |
---|
| 35 | |
---|
| 36 | * Inclusion of header files. These are files of declarations that |
---|
| 37 | can be substituted into your program. |
---|
| 38 | |
---|
| 39 | * Macro expansion. You can define "macros", which are abbreviations |
---|
| 40 | for arbitrary fragments of C code, and then the C preprocessor will |
---|
| 41 | replace the macros with their definitions throughout the program. |
---|
| 42 | |
---|
| 43 | * Conditional compilation. Using special preprocessing directives, |
---|
| 44 | you can include or exclude parts of the program according to |
---|
| 45 | various conditions. |
---|
| 46 | |
---|
| 47 | * Line control. If you use a program to combine or rearrange source |
---|
| 48 | files into an intermediate file which is then compiled, you can |
---|
| 49 | use line control to inform the compiler of where each source line |
---|
| 50 | originally came from. |
---|
| 51 | |
---|
| 52 | C preprocessors vary in some details. This manual discusses the GNU |
---|
| 53 | C preprocessor, the C Compatible Compiler Preprocessor. The GNU C |
---|
| 54 | preprocessor provides a superset of the features of ANSI Standard C. |
---|
| 55 | |
---|
| 56 | ANSI Standard C requires the rejection of many harmless constructs |
---|
| 57 | commonly used by today's C programs. Such incompatibility would be |
---|
| 58 | inconvenient for users, so the GNU C preprocessor is configured to |
---|
| 59 | accept these constructs by default. Strictly speaking, to get ANSI |
---|
| 60 | Standard C, you must use the options `-trigraphs', `-undef' and |
---|
| 61 | `-pedantic', but in practice the consequences of having strict ANSI |
---|
| 62 | Standard C make it undesirable to do this. *Note Invocation::. |
---|
| 63 | |
---|
| 64 | * Menu: |
---|
| 65 | |
---|
| 66 | * Global Actions:: Actions made uniformly on all input files. |
---|
| 67 | * Directives:: General syntax of preprocessing directives. |
---|
| 68 | * Header Files:: How and why to use header files. |
---|
| 69 | * Macros:: How and why to use macros. |
---|
| 70 | * Conditionals:: How and why to use conditionals. |
---|
| 71 | * Combining Sources:: Use of line control when you combine source files. |
---|
| 72 | * Other Directives:: Miscellaneous preprocessing directives. |
---|
| 73 | * Output:: Format of output from the C preprocessor. |
---|
| 74 | * Invocation:: How to invoke the preprocessor; command options. |
---|
| 75 | * Concept Index:: Index of concepts and terms. |
---|
| 76 | * Index:: Index of directives, predefined macros and options. |
---|
| 77 | |
---|
| 78 | |
---|
| 79 | File: cpp.info, Node: Global Actions, Next: Directives, Prev: Top, Up: Top |
---|
| 80 | |
---|
| 81 | Transformations Made Globally |
---|
| 82 | ============================= |
---|
| 83 | |
---|
| 84 | Most C preprocessor features are inactive unless you give specific |
---|
| 85 | directives to request their use. (Preprocessing directives are lines |
---|
| 86 | starting with `#'; *note Directives::.). But there are three |
---|
| 87 | transformations that the preprocessor always makes on all the input it |
---|
| 88 | receives, even in the absence of directives. |
---|
| 89 | |
---|
| 90 | * All C comments are replaced with single spaces. |
---|
| 91 | |
---|
| 92 | * Backslash-Newline sequences are deleted, no matter where. This |
---|
| 93 | feature allows you to break long lines for cosmetic purposes |
---|
| 94 | without changing their meaning. |
---|
| 95 | |
---|
| 96 | * Predefined macro names are replaced with their expansions (*note |
---|
| 97 | Predefined::.). |
---|
| 98 | |
---|
| 99 | The first two transformations are done *before* nearly all other |
---|
| 100 | parsing and before preprocessing directives are recognized. Thus, for |
---|
| 101 | example, you can split a line cosmetically with Backslash-Newline |
---|
| 102 | anywhere (except when trigraphs are in use; see below). |
---|
| 103 | |
---|
| 104 | /* |
---|
| 105 | */ # /* |
---|
| 106 | */ defi\ |
---|
| 107 | ne FO\ |
---|
| 108 | O 10\ |
---|
| 109 | 20 |
---|
| 110 | |
---|
| 111 | is equivalent into `#define FOO 1020'. You can split even an escape |
---|
| 112 | sequence with Backslash-Newline. For example, you can split `"foo\bar"' |
---|
| 113 | between the `\' and the `b' to get |
---|
| 114 | |
---|
| 115 | "foo\\ |
---|
| 116 | bar" |
---|
| 117 | |
---|
| 118 | This behavior is unclean: in all other contexts, a Backslash can be |
---|
| 119 | inserted in a string constant as an ordinary character by writing a |
---|
| 120 | double Backslash, and this creates an exception. But the ANSI C |
---|
| 121 | standard requires it. (Strict ANSI C does not allow Newlines in string |
---|
| 122 | constants, so they do not consider this a problem.) |
---|
| 123 | |
---|
| 124 | But there are a few exceptions to all three transformations. |
---|
| 125 | |
---|
| 126 | * C comments and predefined macro names are not recognized inside a |
---|
| 127 | `#include' directive in which the file name is delimited with `<' |
---|
| 128 | and `>'. |
---|
| 129 | |
---|
| 130 | * C comments and predefined macro names are never recognized within a |
---|
| 131 | character or string constant. (Strictly speaking, this is the |
---|
| 132 | rule, not an exception, but it is worth noting here anyway.) |
---|
| 133 | |
---|
| 134 | * Backslash-Newline may not safely be used within an ANSI "trigraph". |
---|
| 135 | Trigraphs are converted before Backslash-Newline is deleted. If |
---|
| 136 | you write what looks like a trigraph with a Backslash-Newline |
---|
| 137 | inside, the Backslash-Newline is deleted as usual, but it is then |
---|
| 138 | too late to recognize the trigraph. |
---|
| 139 | |
---|
| 140 | This exception is relevant only if you use the `-trigraphs' option |
---|
| 141 | to enable trigraph processing. *Note Invocation::. |
---|
| 142 | |
---|
| 143 | |
---|
| 144 | File: cpp.info, Node: Directives, Next: Header Files, Prev: Global Actions, Up: Top |
---|
| 145 | |
---|
| 146 | Preprocessing Directives |
---|
| 147 | ======================== |
---|
| 148 | |
---|
| 149 | Most preprocessor features are active only if you use preprocessing |
---|
| 150 | directives to request their use. |
---|
| 151 | |
---|
| 152 | Preprocessing directives are lines in your program that start with |
---|
| 153 | `#'. The `#' is followed by an identifier that is the "directive name". |
---|
| 154 | For example, `#define' is the directive that defines a macro. |
---|
| 155 | Whitespace is also allowed before and after the `#'. |
---|
| 156 | |
---|
| 157 | The set of valid directive names is fixed. Programs cannot define |
---|
| 158 | new preprocessing directives. |
---|
| 159 | |
---|
| 160 | Some directive names require arguments; these make up the rest of |
---|
| 161 | the directive line and must be separated from the directive name by |
---|
| 162 | whitespace. For example, `#define' must be followed by a macro name |
---|
| 163 | and the intended expansion of the macro. *Note Simple Macros::. |
---|
| 164 | |
---|
| 165 | A preprocessing directive cannot be more than one line in normal |
---|
| 166 | circumstances. It may be split cosmetically with Backslash-Newline, |
---|
| 167 | but that has no effect on its meaning. Comments containing Newlines |
---|
| 168 | can also divide the directive into multiple lines, but the comments are |
---|
| 169 | changed to Spaces before the directive is interpreted. The only way a |
---|
| 170 | significant Newline can occur in a preprocessing directive is within a |
---|
| 171 | string constant or character constant. Note that most C compilers that |
---|
| 172 | might be applied to the output from the preprocessor do not accept |
---|
| 173 | string or character constants containing Newlines. |
---|
| 174 | |
---|
| 175 | The `#' and the directive name cannot come from a macro expansion. |
---|
| 176 | For example, if `foo' is defined as a macro expanding to `define', that |
---|
| 177 | does not make `#foo' a valid preprocessing directive. |
---|
| 178 | |
---|
| 179 | |
---|
| 180 | File: cpp.info, Node: Header Files, Next: Macros, Prev: Directives, Up: Top |
---|
| 181 | |
---|
| 182 | Header Files |
---|
| 183 | ============ |
---|
| 184 | |
---|
| 185 | A header file is a file containing C declarations and macro |
---|
| 186 | definitions (*note Macros::.) to be shared between several source |
---|
| 187 | files. You request the use of a header file in your program with the C |
---|
| 188 | preprocessing directive `#include'. |
---|
| 189 | |
---|
| 190 | * Menu: |
---|
| 191 | |
---|
| 192 | * Header Uses:: What header files are used for. |
---|
| 193 | * Include Syntax:: How to write `#include' directives. |
---|
| 194 | * Include Operation:: What `#include' does. |
---|
| 195 | * Once-Only:: Preventing multiple inclusion of one header file. |
---|
| 196 | * Inheritance:: Including one header file in another header file. |
---|
| 197 | |
---|
| 198 | |
---|
| 199 | File: cpp.info, Node: Header Uses, Next: Include Syntax, Prev: Header Files, Up: Header Files |
---|
| 200 | |
---|
| 201 | Uses of Header Files |
---|
| 202 | -------------------- |
---|
| 203 | |
---|
| 204 | Header files serve two kinds of purposes. |
---|
| 205 | |
---|
| 206 | * System header files declare the interfaces to parts of the |
---|
| 207 | operating system. You include them in your program to supply the |
---|
| 208 | definitions and declarations you need to invoke system calls and |
---|
| 209 | libraries. |
---|
| 210 | |
---|
| 211 | * Your own header files contain declarations for interfaces between |
---|
| 212 | the source files of your program. Each time you have a group of |
---|
| 213 | related declarations and macro definitions all or most of which |
---|
| 214 | are needed in several different source files, it is a good idea to |
---|
| 215 | create a header file for them. |
---|
| 216 | |
---|
| 217 | Including a header file produces the same results in C compilation as |
---|
| 218 | copying the header file into each source file that needs it. But such |
---|
| 219 | copying would be time-consuming and error-prone. With a header file, |
---|
| 220 | the related declarations appear in only one place. If they need to be |
---|
| 221 | changed, they can be changed in one place, and programs that include |
---|
| 222 | the header file will automatically use the new version when next |
---|
| 223 | recompiled. The header file eliminates the labor of finding and |
---|
| 224 | changing all the copies as well as the risk that a failure to find one |
---|
| 225 | copy will result in inconsistencies within a program. |
---|
| 226 | |
---|
| 227 | The usual convention is to give header files names that end with |
---|
| 228 | `.h'. Avoid unusual characters in header file names, as they reduce |
---|
| 229 | portability. |
---|
| 230 | |
---|
| 231 | |
---|
| 232 | File: cpp.info, Node: Include Syntax, Next: Include Operation, Prev: Header Uses, Up: Header Files |
---|
| 233 | |
---|
| 234 | The `#include' Directive |
---|
| 235 | ------------------------ |
---|
| 236 | |
---|
| 237 | Both user and system header files are included using the |
---|
| 238 | preprocessing directive `#include'. It has three variants: |
---|
| 239 | |
---|
| 240 | `#include <FILE>' |
---|
| 241 | This variant is used for system header files. It searches for a |
---|
| 242 | file named FILE in a list of directories specified by you, then in |
---|
| 243 | a standard list of system directories. You specify directories to |
---|
| 244 | search for header files with the command option `-I' (*note |
---|
| 245 | Invocation::.). The option `-nostdinc' inhibits searching the |
---|
| 246 | standard system directories; in this case only the directories you |
---|
| 247 | specify are searched. |
---|
| 248 | |
---|
| 249 | The parsing of this form of `#include' is slightly special because |
---|
| 250 | comments are not recognized within the `<...>'. Thus, in |
---|
| 251 | `#include <x/*y>' the `/*' does not start a comment and the |
---|
| 252 | directive specifies inclusion of a system header file named |
---|
| 253 | `x/*y'. Of course, a header file with such a name is unlikely to |
---|
| 254 | exist on Unix, where shell wildcard features would make it hard to |
---|
| 255 | manipulate. |
---|
| 256 | |
---|
| 257 | The argument FILE may not contain a `>' character. It may, |
---|
| 258 | however, contain a `<' character. |
---|
| 259 | |
---|
| 260 | `#include "FILE"' |
---|
| 261 | This variant is used for header files of your own program. It |
---|
| 262 | searches for a file named FILE first in the current directory, |
---|
| 263 | then in the same directories used for system header files. The |
---|
| 264 | current directory is the directory of the current input file. It |
---|
| 265 | is tried first because it is presumed to be the location of the |
---|
| 266 | files that the current input file refers to. (If the `-I-' option |
---|
| 267 | is used, the special treatment of the current directory is |
---|
| 268 | inhibited.) |
---|
| 269 | |
---|
| 270 | The argument FILE may not contain `"' characters. If backslashes |
---|
| 271 | occur within FILE, they are considered ordinary text characters, |
---|
| 272 | not escape characters. None of the character escape sequences |
---|
| 273 | appropriate to string constants in C are processed. Thus, |
---|
| 274 | `#include "x\n\\y"' specifies a filename containing three |
---|
| 275 | backslashes. It is not clear why this behavior is ever useful, but |
---|
| 276 | the ANSI standard specifies it. |
---|
| 277 | |
---|
| 278 | `#include ANYTHING ELSE' |
---|
| 279 | This variant is called a "computed #include". Any `#include' |
---|
| 280 | directive whose argument does not fit the above two forms is a |
---|
| 281 | computed include. The text ANYTHING ELSE is checked for macro |
---|
| 282 | calls, which are expanded (*note Macros::.). When this is done, |
---|
| 283 | the result must fit one of the above two variants--in particular, |
---|
| 284 | the expanded text must in the end be surrounded by either quotes |
---|
| 285 | or angle braces. |
---|
| 286 | |
---|
| 287 | This feature allows you to define a macro which controls the file |
---|
| 288 | name to be used at a later point in the program. One application |
---|
| 289 | of this is to allow a site-specific configuration file for your |
---|
| 290 | program to specify the names of the system include files to be |
---|
| 291 | used. This can help in porting the program to various operating |
---|
| 292 | systems in which the necessary system header files are found in |
---|
| 293 | different places. |
---|
| 294 | |
---|
| 295 | |
---|
| 296 | File: cpp.info, Node: Include Operation, Next: Once-Only, Prev: Include Syntax, Up: Header Files |
---|
| 297 | |
---|
| 298 | How `#include' Works |
---|
| 299 | -------------------- |
---|
| 300 | |
---|
| 301 | The `#include' directive works by directing the C preprocessor to |
---|
| 302 | scan the specified file as input before continuing with the rest of the |
---|
| 303 | current file. The output from the preprocessor contains the output |
---|
| 304 | already generated, followed by the output resulting from the included |
---|
| 305 | file, followed by the output that comes from the text after the |
---|
| 306 | `#include' directive. For example, given a header file `header.h' as |
---|
| 307 | follows, |
---|
| 308 | |
---|
| 309 | char *test (); |
---|
| 310 | |
---|
| 311 | and a main program called `program.c' that uses the header file, like |
---|
| 312 | this, |
---|
| 313 | |
---|
| 314 | int x; |
---|
| 315 | #include "header.h" |
---|
| 316 | |
---|
| 317 | main () |
---|
| 318 | { |
---|
| 319 | printf (test ()); |
---|
| 320 | } |
---|
| 321 | |
---|
| 322 | the output generated by the C preprocessor for `program.c' as input |
---|
| 323 | would be |
---|
| 324 | |
---|
| 325 | int x; |
---|
| 326 | char *test (); |
---|
| 327 | |
---|
| 328 | main () |
---|
| 329 | { |
---|
| 330 | printf (test ()); |
---|
| 331 | } |
---|
| 332 | |
---|
| 333 | Included files are not limited to declarations and macro |
---|
| 334 | definitions; those are merely the typical uses. Any fragment of a C |
---|
| 335 | program can be included from another file. The include file could even |
---|
| 336 | contain the beginning of a statement that is concluded in the |
---|
| 337 | containing file, or the end of a statement that was started in the |
---|
| 338 | including file. However, a comment or a string or character constant |
---|
| 339 | may not start in the included file and finish in the including file. |
---|
| 340 | An unterminated comment, string constant or character constant in an |
---|
| 341 | included file is considered to end (with an error message) at the end |
---|
| 342 | of the file. |
---|
| 343 | |
---|
| 344 | It is possible for a header file to begin or end a syntactic unit |
---|
| 345 | such as a function definition, but that would be very confusing, so |
---|
| 346 | don't do it. |
---|
| 347 | |
---|
| 348 | The line following the `#include' directive is always treated as a |
---|
| 349 | separate line by the C preprocessor even if the included file lacks a |
---|
| 350 | final newline. |
---|
| 351 | |
---|
| 352 | |
---|
| 353 | File: cpp.info, Node: Once-Only, Next: Inheritance, Prev: Include Operation, Up: Header Files |
---|
| 354 | |
---|
| 355 | Once-Only Include Files |
---|
| 356 | ----------------------- |
---|
| 357 | |
---|
| 358 | Very often, one header file includes another. It can easily result |
---|
| 359 | that a certain header file is included more than once. This may lead |
---|
| 360 | to errors, if the header file defines structure types or typedefs, and |
---|
| 361 | is certainly wasteful. Therefore, we often wish to prevent multiple |
---|
| 362 | inclusion of a header file. |
---|
| 363 | |
---|
| 364 | The standard way to do this is to enclose the entire real contents |
---|
| 365 | of the file in a conditional, like this: |
---|
| 366 | |
---|
| 367 | #ifndef FILE_FOO_SEEN |
---|
| 368 | #define FILE_FOO_SEEN |
---|
| 369 | |
---|
| 370 | THE ENTIRE FILE |
---|
| 371 | |
---|
| 372 | #endif /* FILE_FOO_SEEN */ |
---|
| 373 | |
---|
| 374 | The macro `FILE_FOO_SEEN' indicates that the file has been included |
---|
| 375 | once already. In a user header file, the macro name should not begin |
---|
| 376 | with `_'. In a system header file, this name should begin with `__' to |
---|
| 377 | avoid conflicts with user programs. In any kind of header file, the |
---|
| 378 | macro name should contain the name of the file and some additional |
---|
| 379 | text, to avoid conflicts with other header files. |
---|
| 380 | |
---|
| 381 | The GNU C preprocessor is programmed to notice when a header file |
---|
| 382 | uses this particular construct and handle it efficiently. If a header |
---|
| 383 | file is contained entirely in a `#ifndef' conditional, then it records |
---|
| 384 | that fact. If a subsequent `#include' specifies the same file, and the |
---|
| 385 | macro in the `#ifndef' is already defined, then the file is entirely |
---|
| 386 | skipped, without even reading it. |
---|
| 387 | |
---|
| 388 | There is also an explicit directive to tell the preprocessor that it |
---|
| 389 | need not include a file more than once. This is called `#pragma once', |
---|
| 390 | and was used *in addition to* the `#ifndef' conditional around the |
---|
| 391 | contents of the header file. `#pragma once' is now obsolete and should |
---|
| 392 | not be used at all. |
---|
| 393 | |
---|
| 394 | In the Objective C language, there is a variant of `#include' called |
---|
| 395 | `#import' which includes a file, but does so at most once. If you use |
---|
| 396 | `#import' *instead of* `#include', then you don't need the conditionals |
---|
| 397 | inside the header file to prevent multiple execution of the contents. |
---|
| 398 | |
---|
| 399 | `#import' is obsolete because it is not a well designed feature. It |
---|
| 400 | requires the users of a header file--the applications programmers--to |
---|
| 401 | know that a certain header file should only be included once. It is |
---|
| 402 | much better for the header file's implementor to write the file so that |
---|
| 403 | users don't need to know this. Using `#ifndef' accomplishes this goal. |
---|
| 404 | |
---|
| 405 | |
---|
| 406 | File: cpp.info, Node: Inheritance, Prev: Once-Only, Up: Header Files |
---|
| 407 | |
---|
| 408 | Inheritance and Header Files |
---|
| 409 | ---------------------------- |
---|
| 410 | |
---|
| 411 | "Inheritance" is what happens when one object or file derives some |
---|
| 412 | of its contents by virtual copying from another object or file. In the |
---|
| 413 | case of C header files, inheritance means that one header file includes |
---|
| 414 | another header file and then replaces or adds something. |
---|
| 415 | |
---|
| 416 | If the inheriting header file and the base header file have different |
---|
| 417 | names, then inheritance is straightforward: simply write `#include |
---|
| 418 | "BASE"' in the inheriting file. |
---|
| 419 | |
---|
| 420 | Sometimes it is necessary to give the inheriting file the same name |
---|
| 421 | as the base file. This is less straightforward. |
---|
| 422 | |
---|
| 423 | For example, suppose an application program uses the system header |
---|
| 424 | file `sys/signal.h', but the version of `/usr/include/sys/signal.h' on |
---|
| 425 | a particular system doesn't do what the application program expects. |
---|
| 426 | It might be convenient to define a "local" version, perhaps under the |
---|
| 427 | name `/usr/local/include/sys/signal.h', to override or add to the one |
---|
| 428 | supplied by the system. |
---|
| 429 | |
---|
| 430 | You can do this by using the option `-I.' for compilation, and |
---|
| 431 | writing a file `sys/signal.h' that does what the application program |
---|
| 432 | expects. But making this file include the standard `sys/signal.h' is |
---|
| 433 | not so easy--writing `#include <sys/signal.h>' in that file doesn't |
---|
| 434 | work, because it includes your own version of the file, not the |
---|
| 435 | standard system version. Used in that file itself, this leads to an |
---|
| 436 | infinite recursion and a fatal error in compilation. |
---|
| 437 | |
---|
| 438 | `#include </usr/include/sys/signal.h>' would find the proper file, |
---|
| 439 | but that is not clean, since it makes an assumption about where the |
---|
| 440 | system header file is found. This is bad for maintenance, since it |
---|
| 441 | means that any change in where the system's header files are kept |
---|
| 442 | requires a change somewhere else. |
---|
| 443 | |
---|
| 444 | The clean way to solve this problem is to use `#include_next', which |
---|
| 445 | means, "Include the *next* file with this name." This directive works |
---|
| 446 | like `#include' except in searching for the specified file: it starts |
---|
| 447 | searching the list of header file directories *after* the directory in |
---|
| 448 | which the current file was found. |
---|
| 449 | |
---|
| 450 | Suppose you specify `-I /usr/local/include', and the list of |
---|
| 451 | directories to search also includes `/usr/include'; and suppose that |
---|
| 452 | both directories contain a file named `sys/signal.h'. Ordinary |
---|
| 453 | `#include <sys/signal.h>' finds the file under `/usr/local/include'. |
---|
| 454 | If that file contains `#include_next <sys/signal.h>', it starts |
---|
| 455 | searching after that directory, and finds the file in `/usr/include'. |
---|
| 456 | |
---|
| 457 | |
---|
| 458 | File: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top |
---|
| 459 | |
---|
| 460 | Macros |
---|
| 461 | ====== |
---|
| 462 | |
---|
| 463 | A macro is a sort of abbreviation which you can define once and then |
---|
| 464 | use later. There are many complicated features associated with macros |
---|
| 465 | in the C preprocessor. |
---|
| 466 | |
---|
| 467 | * Menu: |
---|
| 468 | |
---|
| 469 | * Simple Macros:: Macros that always expand the same way. |
---|
| 470 | * Argument Macros:: Macros that accept arguments that are substituted |
---|
| 471 | into the macro expansion. |
---|
| 472 | * Predefined:: Predefined macros that are always available. |
---|
| 473 | * Stringification:: Macro arguments converted into string constants. |
---|
| 474 | * Concatenation:: Building tokens from parts taken from macro arguments. |
---|
| 475 | * Undefining:: Cancelling a macro's definition. |
---|
| 476 | * Redefining:: Changing a macro's definition. |
---|
| 477 | * Macro Pitfalls:: Macros can confuse the unwary. Here we explain |
---|
| 478 | several common problems and strange features. |
---|
| 479 | |
---|
| 480 | |
---|
| 481 | File: cpp.info, Node: Simple Macros, Next: Argument Macros, Prev: Macros, Up: Macros |
---|
| 482 | |
---|
| 483 | Simple Macros |
---|
| 484 | ------------- |
---|
| 485 | |
---|
| 486 | A "simple macro" is a kind of abbreviation. It is a name which |
---|
| 487 | stands for a fragment of code. Some people refer to these as "manifest |
---|
| 488 | constants". |
---|
| 489 | |
---|
| 490 | Before you can use a macro, you must "define" it explicitly with the |
---|
| 491 | `#define' directive. `#define' is followed by the name of the macro |
---|
| 492 | and then the code it should be an abbreviation for. For example, |
---|
| 493 | |
---|
| 494 | #define BUFFER_SIZE 1020 |
---|
| 495 | |
---|
| 496 | defines a macro named `BUFFER_SIZE' as an abbreviation for the text |
---|
| 497 | `1020'. If somewhere after this `#define' directive there comes a C |
---|
| 498 | statement of the form |
---|
| 499 | |
---|
| 500 | foo = (char *) xmalloc (BUFFER_SIZE); |
---|
| 501 | |
---|
| 502 | then the C preprocessor will recognize and "expand" the macro |
---|
| 503 | `BUFFER_SIZE', resulting in |
---|
| 504 | |
---|
| 505 | foo = (char *) xmalloc (1020); |
---|
| 506 | |
---|
| 507 | The use of all upper case for macro names is a standard convention. |
---|
| 508 | Programs are easier to read when it is possible to tell at a glance |
---|
| 509 | which names are macros. |
---|
| 510 | |
---|
| 511 | Normally, a macro definition must be a single line, like all C |
---|
| 512 | preprocessing directives. (You can split a long macro definition |
---|
| 513 | cosmetically with Backslash-Newline.) There is one exception: Newlines |
---|
| 514 | can be included in the macro definition if within a string or character |
---|
| 515 | constant. This is because it is not possible for a macro definition to |
---|
| 516 | contain an unbalanced quote character; the definition automatically |
---|
| 517 | extends to include the matching quote character that ends the string or |
---|
| 518 | character constant. Comments within a macro definition may contain |
---|
| 519 | Newlines, which make no difference since the comments are entirely |
---|
| 520 | replaced with Spaces regardless of their contents. |
---|
| 521 | |
---|
| 522 | Aside from the above, there is no restriction on what can go in a |
---|
| 523 | macro body. Parentheses need not balance. The body need not resemble |
---|
| 524 | valid C code. (But if it does not, you may get error messages from the |
---|
| 525 | C compiler when you use the macro.) |
---|
| 526 | |
---|
| 527 | The C preprocessor scans your program sequentially, so macro |
---|
| 528 | definitions take effect at the place you write them. Therefore, the |
---|
| 529 | following input to the C preprocessor |
---|
| 530 | |
---|
| 531 | foo = X; |
---|
| 532 | #define X 4 |
---|
| 533 | bar = X; |
---|
| 534 | |
---|
| 535 | produces as output |
---|
| 536 | |
---|
| 537 | foo = X; |
---|
| 538 | |
---|
| 539 | bar = 4; |
---|
| 540 | |
---|
| 541 | After the preprocessor expands a macro name, the macro's definition |
---|
| 542 | body is appended to the front of the remaining input, and the check for |
---|
| 543 | macro calls continues. Therefore, the macro body can contain calls to |
---|
| 544 | other macros. For example, after |
---|
| 545 | |
---|
| 546 | #define BUFSIZE 1020 |
---|
| 547 | #define TABLESIZE BUFSIZE |
---|
| 548 | |
---|
| 549 | the name `TABLESIZE' when used in the program would go through two |
---|
| 550 | stages of expansion, resulting ultimately in `1020'. |
---|
| 551 | |
---|
| 552 | This is not at all the same as defining `TABLESIZE' to be `1020'. |
---|
| 553 | The `#define' for `TABLESIZE' uses exactly the body you specify--in |
---|
| 554 | this case, `BUFSIZE'--and does not check to see whether it too is the |
---|
| 555 | name of a macro. It's only when you *use* `TABLESIZE' that the result |
---|
| 556 | of its expansion is checked for more macro names. *Note Cascaded |
---|
| 557 | Macros::. |
---|
| 558 | |
---|
| 559 | |
---|
| 560 | File: cpp.info, Node: Argument Macros, Next: Predefined, Prev: Simple Macros, Up: Macros |
---|
| 561 | |
---|
| 562 | Macros with Arguments |
---|
| 563 | --------------------- |
---|
| 564 | |
---|
| 565 | A simple macro always stands for exactly the same text, each time it |
---|
| 566 | is used. Macros can be more flexible when they accept "arguments". |
---|
| 567 | Arguments are fragments of code that you supply each time the macro is |
---|
| 568 | used. These fragments are included in the expansion of the macro |
---|
| 569 | according to the directions in the macro definition. A macro that |
---|
| 570 | accepts arguments is called a "function-like macro" because the syntax |
---|
| 571 | for using it looks like a function call. |
---|
| 572 | |
---|
| 573 | To define a macro that uses arguments, you write a `#define' |
---|
| 574 | directive with a list of "argument names" in parentheses after the name |
---|
| 575 | of the macro. The argument names may be any valid C identifiers, |
---|
| 576 | separated by commas and optionally whitespace. The open-parenthesis |
---|
| 577 | must follow the macro name immediately, with no space in between. |
---|
| 578 | |
---|
| 579 | For example, here is a macro that computes the minimum of two numeric |
---|
| 580 | values, as it is defined in many C programs: |
---|
| 581 | |
---|
| 582 | #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
---|
| 583 | |
---|
| 584 | (This is not the best way to define a "minimum" macro in GNU C. *Note |
---|
| 585 | Side Effects::, for more information.) |
---|
| 586 | |
---|
| 587 | To use a macro that expects arguments, you write the name of the |
---|
| 588 | macro followed by a list of "actual arguments" in parentheses, |
---|
| 589 | separated by commas. The number of actual arguments you give must |
---|
| 590 | match the number of arguments the macro expects. Examples of use of |
---|
| 591 | the macro `min' include `min (1, 2)' and `min (x + 28, *p)'. |
---|
| 592 | |
---|
| 593 | The expansion text of the macro depends on the arguments you use. |
---|
| 594 | Each of the argument names of the macro is replaced, throughout the |
---|
| 595 | macro definition, with the corresponding actual argument. Using the |
---|
| 596 | same macro `min' defined above, `min (1, 2)' expands into |
---|
| 597 | |
---|
| 598 | ((1) < (2) ? (1) : (2)) |
---|
| 599 | |
---|
| 600 | where `1' has been substituted for `X' and `2' for `Y'. |
---|
| 601 | |
---|
| 602 | Likewise, `min (x + 28, *p)' expands into |
---|
| 603 | |
---|
| 604 | ((x + 28) < (*p) ? (x + 28) : (*p)) |
---|
| 605 | |
---|
| 606 | Parentheses in the actual arguments must balance; a comma within |
---|
| 607 | parentheses does not end an argument. However, there is no requirement |
---|
| 608 | for brackets or braces to balance, and they do not prevent a comma from |
---|
| 609 | separating arguments. Thus, |
---|
| 610 | |
---|
| 611 | macro (array[x = y, x + 1]) |
---|
| 612 | |
---|
| 613 | passes two arguments to `macro': `array[x = y' and `x + 1]'. If you |
---|
| 614 | want to supply `array[x = y, x + 1]' as an argument, you must write it |
---|
| 615 | as `array[(x = y, x + 1)]', which is equivalent C code. |
---|
| 616 | |
---|
| 617 | After the actual arguments are substituted into the macro body, the |
---|
| 618 | entire result is appended to the front of the remaining input, and the |
---|
| 619 | check for macro calls continues. Therefore, the actual arguments can |
---|
| 620 | contain calls to other macros, either with or without arguments, or |
---|
| 621 | even to the same macro. The macro body can also contain calls to other |
---|
| 622 | macros. For example, `min (min (a, b), c)' expands into this text: |
---|
| 623 | |
---|
| 624 | ((((a) < (b) ? (a) : (b))) < (c) |
---|
| 625 | ? (((a) < (b) ? (a) : (b))) |
---|
| 626 | : (c)) |
---|
| 627 | |
---|
| 628 | (Line breaks shown here for clarity would not actually be generated.) |
---|
| 629 | |
---|
| 630 | If a macro `foo' takes one argument, and you want to supply an empty |
---|
| 631 | argument, you must write at least some whitespace between the |
---|
| 632 | parentheses, like this: `foo ( )'. Just `foo ()' is providing no |
---|
| 633 | arguments, which is an error if `foo' expects an argument. But `foo0 |
---|
| 634 | ()' is the correct way to call a macro defined to take zero arguments, |
---|
| 635 | like this: |
---|
| 636 | |
---|
| 637 | #define foo0() ... |
---|
| 638 | |
---|
| 639 | If you use the macro name followed by something other than an |
---|
| 640 | open-parenthesis (after ignoring any spaces, tabs and comments that |
---|
| 641 | follow), it is not a call to the macro, and the preprocessor does not |
---|
| 642 | change what you have written. Therefore, it is possible for the same |
---|
| 643 | name to be a variable or function in your program as well as a macro, |
---|
| 644 | and you can choose in each instance whether to refer to the macro (if |
---|
| 645 | an actual argument list follows) or the variable or function (if an |
---|
| 646 | argument list does not follow). |
---|
| 647 | |
---|
| 648 | Such dual use of one name could be confusing and should be avoided |
---|
| 649 | except when the two meanings are effectively synonymous: that is, when |
---|
| 650 | the name is both a macro and a function and the two have similar |
---|
| 651 | effects. You can think of the name simply as a function; use of the |
---|
| 652 | name for purposes other than calling it (such as, to take the address) |
---|
| 653 | will refer to the function, while calls will expand the macro and |
---|
| 654 | generate better but equivalent code. For example, you can use a |
---|
| 655 | function named `min' in the same source file that defines the macro. |
---|
| 656 | If you write `&min' with no argument list, you refer to the function. |
---|
| 657 | If you write `min (x, bb)', with an argument list, the macro is |
---|
| 658 | expanded. If you write `(min) (a, bb)', where the name `min' is not |
---|
| 659 | followed by an open-parenthesis, the macro is not expanded, so you wind |
---|
| 660 | up with a call to the function `min'. |
---|
| 661 | |
---|
| 662 | You may not define the same name as both a simple macro and a macro |
---|
| 663 | with arguments. |
---|
| 664 | |
---|
| 665 | In the definition of a macro with arguments, the list of argument |
---|
| 666 | names must follow the macro name immediately with no space in between. |
---|
| 667 | If there is a space after the macro name, the macro is defined as |
---|
| 668 | taking no arguments, and all the rest of the line is taken to be the |
---|
| 669 | expansion. The reason for this is that it is often useful to define a |
---|
| 670 | macro that takes no arguments and whose definition begins with an |
---|
| 671 | identifier in parentheses. This rule about spaces makes it possible |
---|
| 672 | for you to do either this: |
---|
| 673 | |
---|
| 674 | #define FOO(x) - 1 / (x) |
---|
| 675 | |
---|
| 676 | (which defines `FOO' to take an argument and expand into minus the |
---|
| 677 | reciprocal of that argument) or this: |
---|
| 678 | |
---|
| 679 | #define BAR (x) - 1 / (x) |
---|
| 680 | |
---|
| 681 | (which defines `BAR' to take no argument and always expand into `(x) - |
---|
| 682 | 1 / (x)'). |
---|
| 683 | |
---|
| 684 | Note that the *uses* of a macro with arguments can have spaces before |
---|
| 685 | the left parenthesis; it's the *definition* where it matters whether |
---|
| 686 | there is a space. |
---|
| 687 | |
---|
| 688 | |
---|
| 689 | File: cpp.info, Node: Predefined, Next: Stringification, Prev: Argument Macros, Up: Macros |
---|
| 690 | |
---|
| 691 | Predefined Macros |
---|
| 692 | ----------------- |
---|
| 693 | |
---|
| 694 | Several simple macros are predefined. You can use them without |
---|
| 695 | giving definitions for them. They fall into two classes: standard |
---|
| 696 | macros and system-specific macros. |
---|
| 697 | |
---|
| 698 | * Menu: |
---|
| 699 | |
---|
| 700 | * Standard Predefined:: Standard predefined macros. |
---|
| 701 | * Nonstandard Predefined:: Nonstandard predefined macros. |
---|
| 702 | |
---|
| 703 | |
---|
| 704 | File: cpp.info, Node: Standard Predefined, Next: Nonstandard Predefined, Prev: Predefined, Up: Predefined |
---|
| 705 | |
---|
| 706 | Standard Predefined Macros |
---|
| 707 | .......................... |
---|
| 708 | |
---|
| 709 | The standard predefined macros are available with the same meanings |
---|
| 710 | regardless of the machine or operating system on which you are using |
---|
| 711 | GNU C. Their names all start and end with double underscores. Those |
---|
| 712 | preceding `__GNUC__' in this table are standardized by ANSI C; the rest |
---|
| 713 | are GNU C extensions. |
---|
| 714 | |
---|
| 715 | `__FILE__' |
---|
| 716 | This macro expands to the name of the current input file, in the |
---|
| 717 | form of a C string constant. The precise name returned is the one |
---|
| 718 | that was specified in `#include' or as the input file name |
---|
| 719 | argument. |
---|
| 720 | |
---|
| 721 | `__LINE__' |
---|
| 722 | This macro expands to the current input line number, in the form |
---|
| 723 | of a decimal integer constant. While we call it a predefined |
---|
| 724 | macro, it's a pretty strange macro, since its "definition" changes |
---|
| 725 | with each new line of source code. |
---|
| 726 | |
---|
| 727 | This and `__FILE__' are useful in generating an error message to |
---|
| 728 | report an inconsistency detected by the program; the message can |
---|
| 729 | state the source line at which the inconsistency was detected. |
---|
| 730 | For example, |
---|
| 731 | |
---|
| 732 | fprintf (stderr, "Internal error: " |
---|
| 733 | "negative string length " |
---|
| 734 | "%d at %s, line %d.", |
---|
| 735 | length, __FILE__, __LINE__); |
---|
| 736 | |
---|
| 737 | A `#include' directive changes the expansions of `__FILE__' and |
---|
| 738 | `__LINE__' to correspond to the included file. At the end of that |
---|
| 739 | file, when processing resumes on the input file that contained the |
---|
| 740 | `#include' directive, the expansions of `__FILE__' and `__LINE__' |
---|
| 741 | revert to the values they had before the `#include' (but |
---|
| 742 | `__LINE__' is then incremented by one as processing moves to the |
---|
| 743 | line after the `#include'). |
---|
| 744 | |
---|
| 745 | The expansions of both `__FILE__' and `__LINE__' are altered if a |
---|
| 746 | `#line' directive is used. *Note Combining Sources::. |
---|
| 747 | |
---|
| 748 | `__DATE__' |
---|
| 749 | This macro expands to a string constant that describes the date on |
---|
| 750 | which the preprocessor is being run. The string constant contains |
---|
| 751 | eleven characters and looks like `"Jan 29 1987"' or `"Apr 1 1905"'. |
---|
| 752 | |
---|
| 753 | `__TIME__' |
---|
| 754 | This macro expands to a string constant that describes the time at |
---|
| 755 | which the preprocessor is being run. The string constant contains |
---|
| 756 | eight characters and looks like `"23:59:01"'. |
---|
| 757 | |
---|
| 758 | `__STDC__' |
---|
| 759 | This macro expands to the constant 1, to signify that this is ANSI |
---|
| 760 | Standard C. (Whether that is actually true depends on what C |
---|
| 761 | compiler will operate on the output from the preprocessor.) |
---|
| 762 | |
---|
| 763 | `__STDC_VERSION__' |
---|
| 764 | This macro expands to the C Standard's version number, a long |
---|
| 765 | integer constant of the form `YYYYMML' where YYYY and MM are the |
---|
| 766 | year and month of the Standard version. This signifies which |
---|
| 767 | version of the C Standard the preprocessor conforms to. Like |
---|
| 768 | `__STDC__', whether this version number is accurate for the entire |
---|
| 769 | implementation depends on what C compiler will operate on the |
---|
| 770 | output from the preprocessor. |
---|
| 771 | |
---|
| 772 | `__GNUC__' |
---|
| 773 | This macro is defined if and only if this is GNU C. This macro is |
---|
| 774 | defined only when the entire GNU C compiler is in use; if you |
---|
| 775 | invoke the preprocessor directly, `__GNUC__' is undefined. The |
---|
| 776 | value identifies the major version number of GNU CC (`1' for GNU CC |
---|
| 777 | version 1, which is now obsolete, and `2' for version 2). |
---|
| 778 | |
---|
| 779 | `__GNUC_MINOR__' |
---|
| 780 | The macro contains the minor version number of the compiler. This |
---|
| 781 | can be used to work around differences between different releases |
---|
| 782 | of the compiler (for example, if gcc 2.6.3 is known to support a |
---|
| 783 | feature, you can test for `__GNUC__ > 2 || (__GNUC__ == 2 && |
---|
| 784 | __GNUC_MINOR__ >= 6)'). The last number, `3' in the example |
---|
| 785 | above, denotes the bugfix level of the compiler; no macro contains |
---|
| 786 | this value. |
---|
| 787 | |
---|
| 788 | `__GNUG__' |
---|
| 789 | The GNU C compiler defines this when the compilation language is |
---|
| 790 | C++; use `__GNUG__' to distinguish between GNU C and GNU C++. |
---|
| 791 | |
---|
| 792 | `__cplusplus' |
---|
| 793 | The draft ANSI standard for C++ used to require predefining this |
---|
| 794 | variable. Though it is no longer required, GNU C++ continues to |
---|
| 795 | define it, as do other popular C++ compilers. You can use |
---|
| 796 | `__cplusplus' to test whether a header is compiled by a C compiler |
---|
| 797 | or a C++ compiler. |
---|
| 798 | |
---|
| 799 | `__STRICT_ANSI__' |
---|
| 800 | This macro is defined if and only if the `-ansi' switch was |
---|
| 801 | specified when GNU C was invoked. Its definition is the null |
---|
| 802 | string. This macro exists primarily to direct certain GNU header |
---|
| 803 | files not to define certain traditional Unix constructs which are |
---|
| 804 | incompatible with ANSI C. |
---|
| 805 | |
---|
| 806 | `__BASE_FILE__' |
---|
| 807 | This macro expands to the name of the main input file, in the form |
---|
| 808 | of a C string constant. This is the source file that was specified |
---|
| 809 | as an argument when the C compiler was invoked. |
---|
| 810 | |
---|
| 811 | `__INCLUDE_LEVEL__' |
---|
| 812 | This macro expands to a decimal integer constant that represents |
---|
| 813 | the depth of nesting in include files. The value of this macro is |
---|
| 814 | incremented on every `#include' directive and decremented at every |
---|
| 815 | end of file. For input files specified by command line arguments, |
---|
| 816 | the nesting level is zero. |
---|
| 817 | |
---|
| 818 | `__VERSION__' |
---|
| 819 | This macro expands to a string which describes the version number |
---|
| 820 | of GNU C. The string is normally a sequence of decimal numbers |
---|
| 821 | separated by periods, such as `"2.6.0"'. The only reasonable use |
---|
| 822 | of this macro is to incorporate it into a string constant. |
---|
| 823 | |
---|
| 824 | `__OPTIMIZE__' |
---|
| 825 | This macro is defined in optimizing compilations. It causes |
---|
| 826 | certain GNU header files to define alternative macro definitions |
---|
| 827 | for some system library functions. It is unwise to refer to or |
---|
| 828 | test the definition of this macro unless you make very sure that |
---|
| 829 | programs will execute with the same effect regardless. |
---|
| 830 | |
---|
| 831 | `__CHAR_UNSIGNED__' |
---|
| 832 | This macro is defined if and only if the data type `char' is |
---|
| 833 | unsigned on the target machine. It exists to cause the standard |
---|
| 834 | header file `limit.h' to work correctly. It is bad practice to |
---|
| 835 | refer to this macro yourself; instead, refer to the standard |
---|
| 836 | macros defined in `limit.h'. The preprocessor uses this macro to |
---|
| 837 | determine whether or not to sign-extend large character constants |
---|
| 838 | written in octal; see *Note The `#if' Directive: #if Directive. |
---|
| 839 | |
---|
| 840 | `__REGISTER_PREFIX__' |
---|
| 841 | This macro expands to a string describing the prefix applied to cpu |
---|
| 842 | registers in assembler code. It can be used to write assembler |
---|
| 843 | code that is usable in multiple environments. For example, in the |
---|
| 844 | `m68k-aout' environment it expands to the string `""', but in the |
---|
| 845 | `m68k-coff' environment it expands to the string `"%"'. |
---|
| 846 | |
---|
| 847 | `__USER_LABEL_PREFIX__' |
---|
| 848 | This macro expands to a string describing the prefix applied to |
---|
| 849 | user generated labels in assembler code. It can be used to write |
---|
| 850 | assembler code that is usable in multiple environments. For |
---|
| 851 | example, in the `m68k-aout' environment it expands to the string |
---|
| 852 | `"_"', but in the `m68k-coff' environment it expands to the string |
---|
| 853 | `""'. |
---|
| 854 | |
---|
| 855 | |
---|
| 856 | File: cpp.info, Node: Nonstandard Predefined, Prev: Standard Predefined, Up: Predefined |
---|
| 857 | |
---|
| 858 | Nonstandard Predefined Macros |
---|
| 859 | ............................. |
---|
| 860 | |
---|
| 861 | The C preprocessor normally has several predefined macros that vary |
---|
| 862 | between machines because their purpose is to indicate what type of |
---|
| 863 | system and machine is in use. This manual, being for all systems and |
---|
| 864 | machines, cannot tell you exactly what their names are; instead, we |
---|
| 865 | offer a list of some typical ones. You can use `cpp -dM' to see the |
---|
| 866 | values of predefined macros; see *Note Invocation::. |
---|
| 867 | |
---|
| 868 | Some nonstandard predefined macros describe the operating system in |
---|
| 869 | use, with more or less specificity. For example, |
---|
| 870 | |
---|
| 871 | `unix' |
---|
| 872 | `unix' is normally predefined on all Unix systems. |
---|
| 873 | |
---|
| 874 | `BSD' |
---|
| 875 | `BSD' is predefined on recent versions of Berkeley Unix (perhaps |
---|
| 876 | only in version 4.3). |
---|
| 877 | |
---|
| 878 | Other nonstandard predefined macros describe the kind of CPU, with |
---|
| 879 | more or less specificity. For example, |
---|
| 880 | |
---|
| 881 | `vax' |
---|
| 882 | `vax' is predefined on Vax computers. |
---|
| 883 | |
---|
| 884 | `mc68000' |
---|
| 885 | `mc68000' is predefined on most computers whose CPU is a Motorola |
---|
| 886 | 68000, 68010 or 68020. |
---|
| 887 | |
---|
| 888 | `m68k' |
---|
| 889 | `m68k' is also predefined on most computers whose CPU is a 68000, |
---|
| 890 | 68010 or 68020; however, some makers use `mc68000' and some use |
---|
| 891 | `m68k'. Some predefine both names. What happens in GNU C depends |
---|
| 892 | on the system you are using it on. |
---|
| 893 | |
---|
| 894 | `M68020' |
---|
| 895 | `M68020' has been observed to be predefined on some systems that |
---|
| 896 | use 68020 CPUs--in addition to `mc68000' and `m68k', which are |
---|
| 897 | less specific. |
---|
| 898 | |
---|
| 899 | `_AM29K' |
---|
| 900 | `_AM29000' |
---|
| 901 | Both `_AM29K' and `_AM29000' are predefined for the AMD 29000 CPU |
---|
| 902 | family. |
---|
| 903 | |
---|
| 904 | `ns32000' |
---|
| 905 | `ns32000' is predefined on computers which use the National |
---|
| 906 | Semiconductor 32000 series CPU. |
---|
| 907 | |
---|
| 908 | Yet other nonstandard predefined macros describe the manufacturer of |
---|
| 909 | the system. For example, |
---|
| 910 | |
---|
| 911 | `sun' |
---|
| 912 | `sun' is predefined on all models of Sun computers. |
---|
| 913 | |
---|
| 914 | `pyr' |
---|
| 915 | `pyr' is predefined on all models of Pyramid computers. |
---|
| 916 | |
---|
| 917 | `sequent' |
---|
| 918 | `sequent' is predefined on all models of Sequent computers. |
---|
| 919 | |
---|
| 920 | These predefined symbols are not only nonstandard, they are contrary |
---|
| 921 | to the ANSI standard because their names do not start with underscores. |
---|
| 922 | Therefore, the option `-ansi' inhibits the definition of these symbols. |
---|
| 923 | |
---|
| 924 | This tends to make `-ansi' useless, since many programs depend on the |
---|
| 925 | customary nonstandard predefined symbols. Even system header files |
---|
| 926 | check them and will generate incorrect declarations if they do not find |
---|
| 927 | the names that are expected. You might think that the header files |
---|
| 928 | supplied for the Uglix computer would not need to test what machine |
---|
| 929 | they are running on, because they can simply assume it is the Uglix; |
---|
| 930 | but often they do, and they do so using the customary names. As a |
---|
| 931 | result, very few C programs will compile with `-ansi'. We intend to |
---|
| 932 | avoid such problems on the GNU system. |
---|
| 933 | |
---|
| 934 | What, then, should you do in an ANSI C program to test the type of |
---|
| 935 | machine it will run on? |
---|
| 936 | |
---|
| 937 | GNU C offers a parallel series of symbols for this purpose, whose |
---|
| 938 | names are made from the customary ones by adding `__' at the beginning |
---|
| 939 | and end. Thus, the symbol `__vax__' would be available on a Vax, and |
---|
| 940 | so on. |
---|
| 941 | |
---|
| 942 | The set of nonstandard predefined names in the GNU C preprocessor is |
---|
| 943 | controlled (when `cpp' is itself compiled) by the macro |
---|
| 944 | `CPP_PREDEFINES', which should be a string containing `-D' options, |
---|
| 945 | separated by spaces. For example, on the Sun 3, we use the following |
---|
| 946 | definition: |
---|
| 947 | |
---|
| 948 | #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" |
---|
| 949 | |
---|
| 950 | This macro is usually specified in `tm.h'. |
---|
| 951 | |
---|
| 952 | |
---|
| 953 | File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Predefined, Up: Macros |
---|
| 954 | |
---|
| 955 | Stringification |
---|
| 956 | --------------- |
---|
| 957 | |
---|
| 958 | "Stringification" means turning a code fragment into a string |
---|
| 959 | constant whose contents are the text for the code fragment. For |
---|
| 960 | example, stringifying `foo (z)' results in `"foo (z)"'. |
---|
| 961 | |
---|
| 962 | In the C preprocessor, stringification is an option available when |
---|
| 963 | macro arguments are substituted into the macro definition. In the body |
---|
| 964 | of the definition, when an argument name appears, the character `#' |
---|
| 965 | before the name specifies stringification of the corresponding actual |
---|
| 966 | argument when it is substituted at that point in the definition. The |
---|
| 967 | same argument may be substituted in other places in the definition |
---|
| 968 | without stringification if the argument name appears in those places |
---|
| 969 | with no `#'. |
---|
| 970 | |
---|
| 971 | Here is an example of a macro definition that uses stringification: |
---|
| 972 | |
---|
| 973 | #define WARN_IF(EXP) \ |
---|
| 974 | do { if (EXP) \ |
---|
| 975 | fprintf (stderr, "Warning: " #EXP "\n"); } \ |
---|
| 976 | while (0) |
---|
| 977 | |
---|
| 978 | Here the actual argument for `EXP' is substituted once as given, into |
---|
| 979 | the `if' statement, and once as stringified, into the argument to |
---|
| 980 | `fprintf'. The `do' and `while (0)' are a kludge to make it possible |
---|
| 981 | to write `WARN_IF (ARG);', which the resemblance of `WARN_IF' to a |
---|
| 982 | function would make C programmers want to do; see *Note Swallow |
---|
| 983 | Semicolon::. |
---|
| 984 | |
---|
| 985 | The stringification feature is limited to transforming one macro |
---|
| 986 | argument into one string constant: there is no way to combine the |
---|
| 987 | argument with other text and then stringify it all together. But the |
---|
| 988 | example above shows how an equivalent result can be obtained in ANSI |
---|
| 989 | Standard C using the feature that adjacent string constants are |
---|
| 990 | concatenated as one string constant. The preprocessor stringifies the |
---|
| 991 | actual value of `EXP' into a separate string constant, resulting in |
---|
| 992 | text like |
---|
| 993 | |
---|
| 994 | do { if (x == 0) \ |
---|
| 995 | fprintf (stderr, "Warning: " "x == 0" "\n"); } \ |
---|
| 996 | while (0) |
---|
| 997 | |
---|
| 998 | but the C compiler then sees three consecutive string constants and |
---|
| 999 | concatenates them into one, producing effectively |
---|
| 1000 | |
---|
| 1001 | do { if (x == 0) \ |
---|
| 1002 | fprintf (stderr, "Warning: x == 0\n"); } \ |
---|
| 1003 | while (0) |
---|
| 1004 | |
---|
| 1005 | Stringification in C involves more than putting doublequote |
---|
| 1006 | characters around the fragment; it is necessary to put backslashes in |
---|
| 1007 | front of all doublequote characters, and all backslashes in string and |
---|
| 1008 | character constants, in order to get a valid C string constant with the |
---|
| 1009 | proper contents. Thus, stringifying `p = "foo\n";' results in `"p = |
---|
| 1010 | \"foo\\n\";"'. However, backslashes that are not inside of string or |
---|
| 1011 | character constants are not duplicated: `\n' by itself stringifies to |
---|
| 1012 | `"\n"'. |
---|
| 1013 | |
---|
| 1014 | Whitespace (including comments) in the text being stringified is |
---|
| 1015 | handled according to precise rules. All leading and trailing |
---|
| 1016 | whitespace is ignored. Any sequence of whitespace in the middle of the |
---|
| 1017 | text is converted to a single space in the stringified result. |
---|
| 1018 | |
---|
| 1019 | |
---|
| 1020 | File: cpp.info, Node: Concatenation, Next: Undefining, Prev: Stringification, Up: Macros |
---|
| 1021 | |
---|
| 1022 | Concatenation |
---|
| 1023 | ------------- |
---|
| 1024 | |
---|
| 1025 | "Concatenation" means joining two strings into one. In the context |
---|
| 1026 | of macro expansion, concatenation refers to joining two lexical units |
---|
| 1027 | into one longer one. Specifically, an actual argument to the macro can |
---|
| 1028 | be concatenated with another actual argument or with fixed text to |
---|
| 1029 | produce a longer name. The longer name might be the name of a function, |
---|
| 1030 | variable or type, or a C keyword; it might even be the name of another |
---|
| 1031 | macro, in which case it will be expanded. |
---|
| 1032 | |
---|
| 1033 | When you define a macro, you request concatenation with the special |
---|
| 1034 | operator `##' in the macro body. When the macro is called, after |
---|
| 1035 | actual arguments are substituted, all `##' operators are deleted, and |
---|
| 1036 | so is any whitespace next to them (including whitespace that was part |
---|
| 1037 | of an actual argument). The result is to concatenate the syntactic |
---|
| 1038 | tokens on either side of the `##'. |
---|
| 1039 | |
---|
| 1040 | Consider a C program that interprets named commands. There probably |
---|
| 1041 | needs to be a table of commands, perhaps an array of structures |
---|
| 1042 | declared as follows: |
---|
| 1043 | |
---|
| 1044 | struct command |
---|
| 1045 | { |
---|
| 1046 | char *name; |
---|
| 1047 | void (*function) (); |
---|
| 1048 | }; |
---|
| 1049 | |
---|
| 1050 | struct command commands[] = |
---|
| 1051 | { |
---|
| 1052 | { "quit", quit_command}, |
---|
| 1053 | { "help", help_command}, |
---|
| 1054 | ... |
---|
| 1055 | }; |
---|
| 1056 | |
---|
| 1057 | It would be cleaner not to have to give each command name twice, |
---|
| 1058 | once in the string constant and once in the function name. A macro |
---|
| 1059 | which takes the name of a command as an argument can make this |
---|
| 1060 | unnecessary. The string constant can be created with stringification, |
---|
| 1061 | and the function name by concatenating the argument with `_command'. |
---|
| 1062 | Here is how it is done: |
---|
| 1063 | |
---|
| 1064 | #define COMMAND(NAME) { #NAME, NAME ## _command } |
---|
| 1065 | |
---|
| 1066 | struct command commands[] = |
---|
| 1067 | { |
---|
| 1068 | COMMAND (quit), |
---|
| 1069 | COMMAND (help), |
---|
| 1070 | ... |
---|
| 1071 | }; |
---|
| 1072 | |
---|
| 1073 | The usual case of concatenation is concatenating two names (or a |
---|
| 1074 | name and a number) into a longer name. But this isn't the only valid |
---|
| 1075 | case. It is also possible to concatenate two numbers (or a number and |
---|
| 1076 | a name, such as `1.5' and `e3') into a number. Also, multi-character |
---|
| 1077 | operators such as `+=' can be formed by concatenation. In some cases |
---|
| 1078 | it is even possible to piece together a string constant. However, two |
---|
| 1079 | pieces of text that don't together form a valid lexical unit cannot be |
---|
| 1080 | concatenated. For example, concatenation with `x' on one side and `+' |
---|
| 1081 | on the other is not meaningful because those two characters can't fit |
---|
| 1082 | together in any lexical unit of C. The ANSI standard says that such |
---|
| 1083 | attempts at concatenation are undefined, but in the GNU C preprocessor |
---|
| 1084 | it is well defined: it puts the `x' and `+' side by side with no |
---|
| 1085 | particular special results. |
---|
| 1086 | |
---|
| 1087 | Keep in mind that the C preprocessor converts comments to whitespace |
---|
| 1088 | before macros are even considered. Therefore, you cannot create a |
---|
| 1089 | comment by concatenating `/' and `*': the `/*' sequence that starts a |
---|
| 1090 | comment is not a lexical unit, but rather the beginning of a "long" |
---|
| 1091 | space character. Also, you can freely use comments next to a `##' in a |
---|
| 1092 | macro definition, or in actual arguments that will be concatenated, |
---|
| 1093 | because the comments will be converted to spaces at first sight, and |
---|
| 1094 | concatenation will later discard the spaces. |
---|
| 1095 | |
---|
| 1096 | |
---|
| 1097 | File: cpp.info, Node: Undefining, Next: Redefining, Prev: Concatenation, Up: Macros |
---|
| 1098 | |
---|
| 1099 | Undefining Macros |
---|
| 1100 | ----------------- |
---|
| 1101 | |
---|
| 1102 | To "undefine" a macro means to cancel its definition. This is done |
---|
| 1103 | with the `#undef' directive. `#undef' is followed by the macro name to |
---|
| 1104 | be undefined. |
---|
| 1105 | |
---|
| 1106 | Like definition, undefinition occurs at a specific point in the |
---|
| 1107 | source file, and it applies starting from that point. The name ceases |
---|
| 1108 | to be a macro name, and from that point on it is treated by the |
---|
| 1109 | preprocessor as if it had never been a macro name. |
---|
| 1110 | |
---|
| 1111 | For example, |
---|
| 1112 | |
---|
| 1113 | #define FOO 4 |
---|
| 1114 | x = FOO; |
---|
| 1115 | #undef FOO |
---|
| 1116 | x = FOO; |
---|
| 1117 | |
---|
| 1118 | expands into |
---|
| 1119 | |
---|
| 1120 | x = 4; |
---|
| 1121 | |
---|
| 1122 | x = FOO; |
---|
| 1123 | |
---|
| 1124 | In this example, `FOO' had better be a variable or function as well as |
---|
| 1125 | (temporarily) a macro, in order for the result of the expansion to be |
---|
| 1126 | valid C code. |
---|
| 1127 | |
---|
| 1128 | The same form of `#undef' directive will cancel definitions with |
---|
| 1129 | arguments or definitions that don't expect arguments. The `#undef' |
---|
| 1130 | directive has no effect when used on a name not currently defined as a |
---|
| 1131 | macro. |
---|
| 1132 | |
---|
| 1133 | |
---|
| 1134 | File: cpp.info, Node: Redefining, Next: Macro Pitfalls, Prev: Undefining, Up: Macros |
---|
| 1135 | |
---|
| 1136 | Redefining Macros |
---|
| 1137 | ----------------- |
---|
| 1138 | |
---|
| 1139 | "Redefining" a macro means defining (with `#define') a name that is |
---|
| 1140 | already defined as a macro. |
---|
| 1141 | |
---|
| 1142 | A redefinition is trivial if the new definition is transparently |
---|
| 1143 | identical to the old one. You probably wouldn't deliberately write a |
---|
| 1144 | trivial redefinition, but they can happen automatically when a header |
---|
| 1145 | file is included more than once (*note Header Files::.), so they are |
---|
| 1146 | accepted silently and without effect. |
---|
| 1147 | |
---|
| 1148 | Nontrivial redefinition is considered likely to be an error, so it |
---|
| 1149 | provokes a warning message from the preprocessor. However, sometimes it |
---|
| 1150 | is useful to change the definition of a macro in mid-compilation. You |
---|
| 1151 | can inhibit the warning by undefining the macro with `#undef' before the |
---|
| 1152 | second definition. |
---|
| 1153 | |
---|
| 1154 | In order for a redefinition to be trivial, the new definition must |
---|
| 1155 | exactly match the one already in effect, with two possible exceptions: |
---|
| 1156 | |
---|
| 1157 | * Whitespace may be added or deleted at the beginning or the end. |
---|
| 1158 | |
---|
| 1159 | * Whitespace may be changed in the middle (but not inside strings). |
---|
| 1160 | However, it may not be eliminated entirely, and it may not be added |
---|
| 1161 | where there was no whitespace at all. |
---|
| 1162 | |
---|
| 1163 | Recall that a comment counts as whitespace. |
---|
| 1164 | |
---|
| 1165 | |
---|
| 1166 | File: cpp.info, Node: Macro Pitfalls, Prev: Redefining, Up: Macros |
---|
| 1167 | |
---|
| 1168 | Pitfalls and Subtleties of Macros |
---|
| 1169 | --------------------------------- |
---|
| 1170 | |
---|
| 1171 | In this section we describe some special rules that apply to macros |
---|
| 1172 | and macro expansion, and point out certain cases in which the rules have |
---|
| 1173 | counterintuitive consequences that you must watch out for. |
---|
| 1174 | |
---|
| 1175 | * Menu: |
---|
| 1176 | |
---|
| 1177 | * Misnesting:: Macros can contain unmatched parentheses. |
---|
| 1178 | * Macro Parentheses:: Why apparently superfluous parentheses |
---|
| 1179 | may be necessary to avoid incorrect grouping. |
---|
| 1180 | * Swallow Semicolon:: Macros that look like functions |
---|
| 1181 | but expand into compound statements. |
---|
| 1182 | * Side Effects:: Unsafe macros that cause trouble when |
---|
| 1183 | arguments contain side effects. |
---|
| 1184 | * Self-Reference:: Macros whose definitions use the macros' own names. |
---|
| 1185 | * Argument Prescan:: Actual arguments are checked for macro calls |
---|
| 1186 | before they are substituted. |
---|
| 1187 | * Cascaded Macros:: Macros whose definitions use other macros. |
---|
| 1188 | * Newlines in Args:: Sometimes line numbers get confused. |
---|
| 1189 | |
---|