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