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