![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info-3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cpp.info-3 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.3 root 1: This is Info file cpp.info, produced by Makeinfo-1.55 from the input
1.1 root 2: file cpp.texi.
3:
4: This file documents the GNU C Preprocessor.
5:
1.1.1.4 ! root 6: Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software
1.1.1.3 root 7: Foundation, Inc.
1.1 root 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:
1.1.1.3 root 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'
1.1.1.4 ! root 130: Add the directory DIRECTORY to the head of the list of directories
1.1.1.3 root 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'
1.1.1.4 ! root 145: directives.
1.1.1.3 root 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
1.1.1.4 ! root 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
1.1.1.3 root 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
1.1.1.4 ! root 204: predefined macros, and it outputs *both* the `#define' directives
1.1.1.3 root 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'
1.1.1.4 ! root 279: `-lang-c89'
1.1.1.3 root 280: `-lang-c++'
281: `-lang-objc'
282: `-lang-objc++'
1.1.1.4 ! root 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.
1.1.1.3 root 291:
292: These options are generated by the compiler driver `gcc', but not
1.1.1.4 ! root 293: passed from the `gcc' command line unless you use the driver's
! 294: `-Wp' option.
1.1.1.3 root 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.
1.1.1.4 ! root 329: * directives: Directives.
1.1.1.3 root 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.
1.1.1.4 ! root 342: * null directive: Other Directives.
1.1.1.3 root 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.
1.1.1.4 ! root 350: * preprocessing directives: Directives.
1.1.1.3 root 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:
1.1 root 370: File: cpp.info, Node: Index, Prev: Concept Index, Up: Top
371:
1.1.1.4 ! root 372: Index of Directives, Macros and Options
! 373: ***************************************
1.1 root 374:
375: * Menu:
376:
377: * #assert: Assertions.
1.1.1.3 root 378: * #cpu: Assertions.
379: * #define: Argument Macros.
1.1.1.4 ! root 380: * #elif: #elif Directive.
! 381: * #else: #else Directive.
! 382: * #error: #error Directive.
! 383: * #ident: Other Directives.
1.1 root 384: * #if: Conditional Syntax.
385: * #ifdef: Conditionals-Macros.
386: * #ifndef: Conditionals-Macros.
1.1.1.3 root 387: * #import: Once-Only.
1.1 root 388: * #include: Include Syntax.
389: * #include_next: Inheritance.
390: * #line: Combining Sources.
1.1.1.3 root 391: * #machine: Assertions.
1.1.1.4 ! root 392: * #pragma: Other Directives.
1.1 root 393: * #pragma once: Once-Only.
1.1.1.3 root 394: * #system: Assertions.
1.1 root 395: * #unassert: Assertions.
1.1.1.4 ! root 396: * #warning: #error Directive.
1.1.1.2 root 397: * -$: Invocation.
1.1 root 398: * -A: Invocation.
399: * -C: Invocation.
400: * -D: Invocation.
401: * -dD: Invocation.
402: * -dM: Invocation.
403: * -H: Invocation.
404: * -I: Invocation.
1.1.1.2 root 405: * -idirafter: Invocation.
1.1 root 406: * -imacros: Invocation.
407: * -include: Invocation.
1.1.1.2 root 408: * -iprefix: Invocation.
1.1.1.3 root 409: * -isystem: Invocation.
1.1.1.2 root 410: * -iwithprefix: Invocation.
411: * -lang-c: Invocation.
412: * -lang-c++: Invocation.
1.1.1.4 ! root 413: * -lang-c89: Invocation.
1.1.1.2 root 414: * -lang-objc: Invocation.
415: * -lang-objc++: Invocation.
1.1 root 416: * -M: Invocation.
417: * -MD: Invocation.
418: * -MM: Invocation.
419: * -MMD: Invocation.
1.1.1.2 root 420: * -nostdinc: Invocation.
421: * -nostdinc++: Invocation.
1.1 root 422: * -P: Invocation.
423: * -pedantic: Invocation.
424: * -pedantic-errors: Invocation.
425: * -traditional: Invocation.
426: * -trigraphs: Invocation.
427: * -U: Invocation.
1.1.1.2 root 428: * -undef: Invocation.
1.1 root 429: * -Wall: Invocation.
430: * -Wcomment: Invocation.
431: * -Wtraditional: Invocation.
1.1.1.2 root 432: * -Wtrigraphs: Invocation.
1.1 root 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.
1.1.1.3 root 448: * __CHAR_UNSIGNED__: Standard Predefined.
449: * __cplusplus: Standard Predefined.
1.1 root 450: * __DATE__: Standard Predefined.
451: * __FILE__: Standard Predefined.
1.1.1.4 ! root 452: * __GNUC_MINOR__: Standard Predefined.
1.1.1.3 root 453: * __GNUC__: Standard Predefined.
454: * __GNUG__: Standard Predefined.
1.1 root 455: * __INCLUDE_LEVEL_: Standard Predefined.
456: * __LINE__: Standard Predefined.
1.1.1.3 root 457: * __OPTIMIZE__: Standard Predefined.
1.1.1.4 ! root 458: * __REGISTER_PREFIX__: Standard Predefined.
! 459: * __STDC_VERSION__: Standard Predefined.
1.1 root 460: * __STDC__: Standard Predefined.
1.1.1.3 root 461: * __STRICT_ANSI__: Standard Predefined.
1.1 root 462: * __TIME__: Standard Predefined.
1.1.1.4 ! root 463: * __USER_LABEL_PREFIX__: Standard Predefined.
1.1.1.3 root 464: * __VERSION__: Standard Predefined.
1.1 root 465:
466:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.