1 | This is Info file cpp.info, produced by Makeinfo-1.55 from the input |
---|
2 | file cpp.texi. |
---|
3 | |
---|
4 | This file documents the GNU C Preprocessor. |
---|
5 | |
---|
6 | Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software |
---|
7 | Foundation, Inc. |
---|
8 | |
---|
9 | Permission is granted to make and distribute verbatim copies of this |
---|
10 | manual provided the copyright notice and this permission notice are |
---|
11 | preserved on all copies. |
---|
12 | |
---|
13 | Permission is granted to copy and distribute modified versions of |
---|
14 | this manual under the conditions for verbatim copying, provided also |
---|
15 | that the entire resulting derived work is distributed under the terms |
---|
16 | of a permission notice identical to this one. |
---|
17 | |
---|
18 | Permission is granted to copy and distribute translations of this |
---|
19 | manual into another language, under the above conditions for modified |
---|
20 | versions. |
---|
21 | |
---|
22 | |
---|
23 | File: cpp.info, Node: Invocation, Next: Concept Index, Prev: Output, Up: Top |
---|
24 | |
---|
25 | Invoking the C Preprocessor |
---|
26 | =========================== |
---|
27 | |
---|
28 | Most often when you use the C preprocessor you will not have to |
---|
29 | invoke it explicitly: the C compiler will do so automatically. |
---|
30 | However, the preprocessor is sometimes useful on its own. |
---|
31 | |
---|
32 | The C preprocessor expects two file names as arguments, INFILE and |
---|
33 | OUTFILE. The preprocessor reads INFILE together with any other files |
---|
34 | it specifies with `#include'. All the output generated by the combined |
---|
35 | input files is written in OUTFILE. |
---|
36 | |
---|
37 | Either INFILE or OUTFILE may be `-', which as INFILE means to read |
---|
38 | from standard input and as OUTFILE means to write to standard output. |
---|
39 | Also, if OUTFILE or both file names are omitted, the standard output |
---|
40 | and standard input are used for the omitted file names. |
---|
41 | |
---|
42 | Here is a table of command options accepted by the C preprocessor. |
---|
43 | These options can also be given when compiling a C program; they are |
---|
44 | passed along automatically to the preprocessor when it is invoked by the |
---|
45 | compiler. |
---|
46 | |
---|
47 | `-P' |
---|
48 | Inhibit generation of `#'-lines with line-number information in |
---|
49 | the output from the preprocessor (*note Output::.). This might be |
---|
50 | useful when running the preprocessor on something that is not C |
---|
51 | code and will be sent to a program which might be confused by the |
---|
52 | `#'-lines. |
---|
53 | |
---|
54 | `-C' |
---|
55 | Do not discard comments: pass them through to the output file. |
---|
56 | Comments appearing in arguments of a macro call will be copied to |
---|
57 | the output before the expansion of the macro call. |
---|
58 | |
---|
59 | `-traditional' |
---|
60 | Try to imitate the behavior of old-fashioned C, as opposed to ANSI |
---|
61 | C. |
---|
62 | |
---|
63 | * Traditional macro expansion pays no attention to singlequote |
---|
64 | or doublequote characters; macro argument symbols are |
---|
65 | replaced by the argument values even when they appear within |
---|
66 | apparent string or character constants. |
---|
67 | |
---|
68 | * Traditionally, it is permissible for a macro expansion to end |
---|
69 | in the middle of a string or character constant. The |
---|
70 | constant continues into the text surrounding the macro call. |
---|
71 | |
---|
72 | * However, traditionally the end of the line terminates a |
---|
73 | string or character constant, with no error. |
---|
74 | |
---|
75 | * In traditional C, a comment is equivalent to no text at all. |
---|
76 | (In ANSI C, a comment counts as whitespace.) |
---|
77 | |
---|
78 | * Traditional C does not have the concept of a "preprocessing |
---|
79 | number". It considers `1.0e+4' to be three tokens: `1.0e', |
---|
80 | `+', and `4'. |
---|
81 | |
---|
82 | * A macro is not suppressed within its own definition, in |
---|
83 | traditional C. Thus, any macro that is used recursively |
---|
84 | inevitably causes an error. |
---|
85 | |
---|
86 | * The character `#' has no special meaning within a macro |
---|
87 | definition in traditional C. |
---|
88 | |
---|
89 | * In traditional C, the text at the end of a macro expansion |
---|
90 | can run together with the text after the macro call, to |
---|
91 | produce a single token. (This is impossible in ANSI C.) |
---|
92 | |
---|
93 | * Traditionally, `\' inside a macro argument suppresses the |
---|
94 | syntactic significance of the following character. |
---|
95 | |
---|
96 | `-trigraphs' |
---|
97 | Process ANSI standard trigraph sequences. These are |
---|
98 | three-character sequences, all starting with `??', that are |
---|
99 | defined by ANSI C to stand for single characters. For example, |
---|
100 | `??/' stands for `\', so `'??/n'' is a character constant for a |
---|
101 | newline. Strictly speaking, the GNU C preprocessor does not |
---|
102 | support all programs in ANSI Standard C unless `-trigraphs' is |
---|
103 | used, but if you ever notice the difference it will be with relief. |
---|
104 | |
---|
105 | You don't want to know any more about trigraphs. |
---|
106 | |
---|
107 | `-pedantic' |
---|
108 | Issue warnings required by the ANSI C standard in certain cases |
---|
109 | such as when text other than a comment follows `#else' or `#endif'. |
---|
110 | |
---|
111 | `-pedantic-errors' |
---|
112 | Like `-pedantic', except that errors are produced rather than |
---|
113 | warnings. |
---|
114 | |
---|
115 | `-Wtrigraphs' |
---|
116 | Warn if any trigraphs are encountered (assuming they are enabled). |
---|
117 | |
---|
118 | `-Wcomment' |
---|
119 | Warn whenever a comment-start sequence `/*' appears in a comment. |
---|
120 | |
---|
121 | `-Wall' |
---|
122 | Requests both `-Wtrigraphs' and `-Wcomment' (but not |
---|
123 | `-Wtraditional'). |
---|
124 | |
---|
125 | `-Wtraditional' |
---|
126 | Warn about certain constructs that behave differently in |
---|
127 | traditional and ANSI C. |
---|
128 | |
---|
129 | `-I DIRECTORY' |
---|
130 | Add the directory DIRECTORY to the head of the list of directories |
---|
131 | to be searched for header files (*note Include Syntax::.). This |
---|
132 | can be used to override a system header file, substituting your |
---|
133 | own version, since these directories are searched before the system |
---|
134 | header file directories. If you use more than one `-I' option, |
---|
135 | the directories are scanned in left-to-right order; the standard |
---|
136 | system directories come after. |
---|
137 | |
---|
138 | `-I-' |
---|
139 | Any directories specified with `-I' options before the `-I-' |
---|
140 | option are searched only for the case of `#include "FILE"'; they |
---|
141 | are not searched for `#include <FILE>'. |
---|
142 | |
---|
143 | If additional directories are specified with `-I' options after |
---|
144 | the `-I-', these directories are searched for all `#include' |
---|
145 | directives. |
---|
146 | |
---|
147 | In addition, the `-I-' option inhibits the use of the current |
---|
148 | directory as the first search directory for `#include "FILE"'. |
---|
149 | Therefore, the current directory is searched only if it is |
---|
150 | requested explicitly with `-I.'. Specifying both `-I-' and `-I.' |
---|
151 | allows you to control precisely which directories are searched |
---|
152 | before the current one and which are searched after. |
---|
153 | |
---|
154 | `-nostdinc' |
---|
155 | Do not search the standard system directories for header files. |
---|
156 | Only the directories you have specified with `-I' options (and the |
---|
157 | current directory, if appropriate) are searched. |
---|
158 | |
---|
159 | `-nostdinc++' |
---|
160 | Do not search for header files in the C++-specific standard |
---|
161 | directories, but do still search the other standard directories. |
---|
162 | (This option is used when building libg++.) |
---|
163 | |
---|
164 | `-D NAME' |
---|
165 | Predefine NAME as a macro, with definition `1'. |
---|
166 | |
---|
167 | `-D NAME=DEFINITION' |
---|
168 | Predefine NAME as a macro, with definition DEFINITION. There are |
---|
169 | no restrictions on the contents of DEFINITION, but if you are |
---|
170 | invoking the preprocessor from a shell or shell-like program you |
---|
171 | may need to use the shell's quoting syntax to protect characters |
---|
172 | such as spaces that have a meaning in the shell syntax. If you |
---|
173 | use more than one `-D' for the same NAME, the rightmost definition |
---|
174 | takes effect. |
---|
175 | |
---|
176 | `-U NAME' |
---|
177 | Do not predefine NAME. If both `-U' and `-D' are specified for |
---|
178 | one name, the `-U' beats the `-D' and the name is not predefined. |
---|
179 | |
---|
180 | `-undef' |
---|
181 | Do not predefine any nonstandard macros. |
---|
182 | |
---|
183 | `-A PREDICATE(ANSWER)' |
---|
184 | Make an assertion with the predicate PREDICATE and answer ANSWER. |
---|
185 | *Note Assertions::. |
---|
186 | |
---|
187 | You can use `-A-' to disable all predefined assertions; it also |
---|
188 | undefines all predefined macros that identify the type of target |
---|
189 | system. |
---|
190 | |
---|
191 | `-dM' |
---|
192 | Instead of outputting the result of preprocessing, output a list of |
---|
193 | `#define' directives for all the macros defined during the |
---|
194 | execution of the preprocessor, including predefined macros. This |
---|
195 | gives you a way of finding out what is predefined in your version |
---|
196 | of the preprocessor; assuming you have no file `foo.h', the command |
---|
197 | |
---|
198 | touch foo.h; cpp -dM foo.h |
---|
199 | |
---|
200 | will show the values of any predefined macros. |
---|
201 | |
---|
202 | `-dD' |
---|
203 | Like `-dM' except in two respects: it does *not* include the |
---|
204 | predefined macros, and it outputs *both* the `#define' directives |
---|
205 | and the result of preprocessing. Both kinds of output go to the |
---|
206 | standard output file. |
---|
207 | |
---|
208 | `-M [-MG]' |
---|
209 | Instead of outputting the result of preprocessing, output a rule |
---|
210 | suitable for `make' describing the dependencies of the main source |
---|
211 | file. The preprocessor outputs one `make' rule containing the |
---|
212 | object file name for that source file, a colon, and the names of |
---|
213 | all the included files. If there are many included files then the |
---|
214 | rule is split into several lines using `\'-newline. |
---|
215 | |
---|
216 | `-MG' says to treat missing header files as generated files and |
---|
217 | assume they live in the same directory as the source file. It |
---|
218 | must be specified in addition to `-M'. |
---|
219 | |
---|
220 | This feature is used in automatic updating of makefiles. |
---|
221 | |
---|
222 | `-MM [-MG]' |
---|
223 | Like `-M' but mention only the files included with `#include |
---|
224 | "FILE"'. System header files included with `#include <FILE>' are |
---|
225 | omitted. |
---|
226 | |
---|
227 | `-MD FILE' |
---|
228 | Like `-M' but the dependency information is written to FILE. This |
---|
229 | is in addition to compiling the file as specified--`-MD' does not |
---|
230 | inhibit ordinary compilation the way `-M' does. |
---|
231 | |
---|
232 | When invoking gcc, do not specify the FILE argument. Gcc will |
---|
233 | create file names made by replacing ".c" with ".d" at the end of |
---|
234 | the input file names. |
---|
235 | |
---|
236 | In Mach, you can use the utility `md' to merge multiple dependency |
---|
237 | files into a single dependency file suitable for using with the |
---|
238 | `make' command. |
---|
239 | |
---|
240 | `-MMD FILE' |
---|
241 | Like `-MD' except mention only user header files, not system |
---|
242 | header files. |
---|
243 | |
---|
244 | `-H' |
---|
245 | Print the name of each header file used, in addition to other |
---|
246 | normal activities. |
---|
247 | |
---|
248 | `-imacros FILE' |
---|
249 | Process FILE as input, discarding the resulting output, before |
---|
250 | processing the regular input file. Because the output generated |
---|
251 | from FILE is discarded, the only effect of `-imacros FILE' is to |
---|
252 | make the macros defined in FILE available for use in the main |
---|
253 | input. |
---|
254 | |
---|
255 | `-include FILE' |
---|
256 | Process FILE as input, and include all the resulting output, |
---|
257 | before processing the regular input file. |
---|
258 | |
---|
259 | `-idirafter DIR' |
---|
260 | Add the directory DIR to the second include path. The directories |
---|
261 | on the second include path are searched when a header file is not |
---|
262 | found in any of the directories in the main include path (the one |
---|
263 | that `-I' adds to). |
---|
264 | |
---|
265 | `-iprefix PREFIX' |
---|
266 | Specify PREFIX as the prefix for subsequent `-iwithprefix' options. |
---|
267 | |
---|
268 | `-iwithprefix DIR' |
---|
269 | Add a directory to the second include path. The directory's name |
---|
270 | is made by concatenating PREFIX and DIR, where PREFIX was |
---|
271 | specified previously with `-iprefix'. |
---|
272 | |
---|
273 | `-isystem DIR' |
---|
274 | Add a directory to the beginning of the second include path, |
---|
275 | marking it as a system directory, so that it gets the same special |
---|
276 | treatment as is applied to the standard system directories. |
---|
277 | |
---|
278 | `-lang-c' |
---|
279 | `-lang-c89' |
---|
280 | `-lang-c++' |
---|
281 | `-lang-objc' |
---|
282 | `-lang-objc++' |
---|
283 | Specify the source language. `-lang-c' is the default; it allows |
---|
284 | recognition of C++ comments (comments that begin with `//' and end |
---|
285 | at end of line), since this is a common feature and it will most |
---|
286 | likely be in the next C standard. `-lang-c89' disables |
---|
287 | recognition of C++ comments. `-lang-c++' handles C++ comment |
---|
288 | syntax and includes extra default include directories for C++. |
---|
289 | `-lang-objc' enables the Objective C `#import' directive. |
---|
290 | `-lang-objc++' enables both C++ and Objective C extensions. |
---|
291 | |
---|
292 | These options are generated by the compiler driver `gcc', but not |
---|
293 | passed from the `gcc' command line unless you use the driver's |
---|
294 | `-Wp' option. |
---|
295 | |
---|
296 | `-lint' |
---|
297 | Look for commands to the program checker `lint' embedded in |
---|
298 | comments, and emit them preceded by `#pragma lint'. For example, |
---|
299 | the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'. |
---|
300 | |
---|
301 | This option is available only when you call `cpp' directly; `gcc' |
---|
302 | will not pass it from its command line. |
---|
303 | |
---|
304 | `-$' |
---|
305 | Forbid the use of `$' in identifiers. This is required for ANSI |
---|
306 | conformance. `gcc' automatically supplies this option to the |
---|
307 | preprocessor if you specify `-ansi', but `gcc' doesn't recognize |
---|
308 | the `-$' option itself--to use it without the other effects of |
---|
309 | `-ansi', you must call the preprocessor directly. |
---|
310 | |
---|
311 | |
---|
312 | File: cpp.info, Node: Concept Index, Next: Index, Prev: Invocation, Up: Top |
---|
313 | |
---|
314 | Concept Index |
---|
315 | ************* |
---|
316 | |
---|
317 | * Menu: |
---|
318 | |
---|
319 | * ##: Concatenation. |
---|
320 | * arguments in macro definitions: Argument Macros. |
---|
321 | * assertions: Assertions. |
---|
322 | * assertions, undoing: Assertions. |
---|
323 | * blank macro arguments: Argument Macros. |
---|
324 | * cascaded macros: Cascaded Macros. |
---|
325 | * commenting out code: Deleted Code. |
---|
326 | * computed #include: Include Syntax. |
---|
327 | * concatenation: Concatenation. |
---|
328 | * conditionals: Conditionals. |
---|
329 | * directives: Directives. |
---|
330 | * expansion of arguments: Argument Prescan. |
---|
331 | * function-like macro: Argument Macros. |
---|
332 | * header file: Header Files. |
---|
333 | * including just once: Once-Only. |
---|
334 | * inheritance: Inheritance. |
---|
335 | * invocation of the preprocessor: Invocation. |
---|
336 | * line control: Combining Sources. |
---|
337 | * macro argument expansion: Argument Prescan. |
---|
338 | * macro body uses macro: Cascaded Macros. |
---|
339 | * macros with argument: Argument Macros. |
---|
340 | * manifest constant: Simple Macros. |
---|
341 | * newlines in macro arguments: Newlines in Args. |
---|
342 | * null directive: Other Directives. |
---|
343 | * options: Invocation. |
---|
344 | * output format: Output. |
---|
345 | * overriding a header file: Inheritance. |
---|
346 | * parentheses in macro bodies: Macro Parentheses. |
---|
347 | * pitfalls of macros: Macro Pitfalls. |
---|
348 | * predefined macros: Predefined. |
---|
349 | * predicates: Assertions. |
---|
350 | * preprocessing directives: Directives. |
---|
351 | * prescan of macro arguments: Argument Prescan. |
---|
352 | * problems with macros: Macro Pitfalls. |
---|
353 | * redefining macros: Redefining. |
---|
354 | * repeated inclusion: Once-Only. |
---|
355 | * retracting assertions: Assertions. |
---|
356 | * second include path: Invocation. |
---|
357 | * self-reference: Self-Reference. |
---|
358 | * semicolons (after macro calls): Swallow Semicolon. |
---|
359 | * side effects (in macro arguments): Side Effects. |
---|
360 | * simple macro: Simple Macros. |
---|
361 | * space as macro argument: Argument Macros. |
---|
362 | * standard predefined macros: Standard Predefined. |
---|
363 | * stringification: Stringification. |
---|
364 | * testing predicates: Assertions. |
---|
365 | * unassert: Assertions. |
---|
366 | * undefining macros: Undefining. |
---|
367 | * unsafe macros: Side Effects. |
---|
368 | |
---|
369 | |
---|
370 | File: cpp.info, Node: Index, Prev: Concept Index, Up: Top |
---|
371 | |
---|
372 | Index of Directives, Macros and Options |
---|
373 | *************************************** |
---|
374 | |
---|
375 | * Menu: |
---|
376 | |
---|
377 | * #assert: Assertions. |
---|
378 | * #cpu: Assertions. |
---|
379 | * #define: Argument Macros. |
---|
380 | * #elif: #elif Directive. |
---|
381 | * #else: #else Directive. |
---|
382 | * #error: #error Directive. |
---|
383 | * #ident: Other Directives. |
---|
384 | * #if: Conditional Syntax. |
---|
385 | * #ifdef: Conditionals-Macros. |
---|
386 | * #ifndef: Conditionals-Macros. |
---|
387 | * #import: Once-Only. |
---|
388 | * #include: Include Syntax. |
---|
389 | * #include_next: Inheritance. |
---|
390 | * #line: Combining Sources. |
---|
391 | * #machine: Assertions. |
---|
392 | * #pragma: Other Directives. |
---|
393 | * #pragma once: Once-Only. |
---|
394 | * #system: Assertions. |
---|
395 | * #unassert: Assertions. |
---|
396 | * #warning: #error Directive. |
---|
397 | * -$: Invocation. |
---|
398 | * -A: Invocation. |
---|
399 | * -C: Invocation. |
---|
400 | * -D: Invocation. |
---|
401 | * -dD: Invocation. |
---|
402 | * -dM: Invocation. |
---|
403 | * -H: Invocation. |
---|
404 | * -I: Invocation. |
---|
405 | * -idirafter: Invocation. |
---|
406 | * -imacros: Invocation. |
---|
407 | * -include: Invocation. |
---|
408 | * -iprefix: Invocation. |
---|
409 | * -isystem: Invocation. |
---|
410 | * -iwithprefix: Invocation. |
---|
411 | * -lang-c: Invocation. |
---|
412 | * -lang-c++: Invocation. |
---|
413 | * -lang-c89: Invocation. |
---|
414 | * -lang-objc: Invocation. |
---|
415 | * -lang-objc++: Invocation. |
---|
416 | * -M: Invocation. |
---|
417 | * -MD: Invocation. |
---|
418 | * -MM: Invocation. |
---|
419 | * -MMD: Invocation. |
---|
420 | * -nostdinc: Invocation. |
---|
421 | * -nostdinc++: Invocation. |
---|
422 | * -P: Invocation. |
---|
423 | * -pedantic: Invocation. |
---|
424 | * -pedantic-errors: Invocation. |
---|
425 | * -traditional: Invocation. |
---|
426 | * -trigraphs: Invocation. |
---|
427 | * -U: Invocation. |
---|
428 | * -undef: Invocation. |
---|
429 | * -Wall: Invocation. |
---|
430 | * -Wcomment: Invocation. |
---|
431 | * -Wtraditional: Invocation. |
---|
432 | * -Wtrigraphs: Invocation. |
---|
433 | * BSD: Nonstandard Predefined. |
---|
434 | * defined: Conditionals-Macros. |
---|
435 | * M68020: Nonstandard Predefined. |
---|
436 | * m68k: Nonstandard Predefined. |
---|
437 | * mc68000: Nonstandard Predefined. |
---|
438 | * ns32000: Nonstandard Predefined. |
---|
439 | * pyr: Nonstandard Predefined. |
---|
440 | * sequent: Nonstandard Predefined. |
---|
441 | * sun: Nonstandard Predefined. |
---|
442 | * system header files: Header Uses. |
---|
443 | * unix: Nonstandard Predefined. |
---|
444 | * vax: Nonstandard Predefined. |
---|
445 | * _AM29000: Nonstandard Predefined. |
---|
446 | * _AM29K: Nonstandard Predefined. |
---|
447 | * __BASE_FILE__: Standard Predefined. |
---|
448 | * __CHAR_UNSIGNED__: Standard Predefined. |
---|
449 | * __cplusplus: Standard Predefined. |
---|
450 | * __DATE__: Standard Predefined. |
---|
451 | * __FILE__: Standard Predefined. |
---|
452 | * __GNUC_MINOR__: Standard Predefined. |
---|
453 | * __GNUC__: Standard Predefined. |
---|
454 | * __GNUG__: Standard Predefined. |
---|
455 | * __INCLUDE_LEVEL_: Standard Predefined. |
---|
456 | * __LINE__: Standard Predefined. |
---|
457 | * __OPTIMIZE__: Standard Predefined. |
---|
458 | * __REGISTER_PREFIX__: Standard Predefined. |
---|
459 | * __STDC_VERSION__: Standard Predefined. |
---|
460 | * __STDC__: Standard Predefined. |
---|
461 | * __STRICT_ANSI__: Standard Predefined. |
---|
462 | * __TIME__: Standard Predefined. |
---|
463 | * __USER_LABEL_PREFIX__: Standard Predefined. |
---|
464 | * __VERSION__: Standard Predefined. |
---|
465 | |
---|
466 | |
---|