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