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