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 | |
---|