![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cccp.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cccp.1 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.3 root 1: .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation \-*-Text-*-
1.1 root 2: .\" See section COPYING for conditions for redistribution
1.1.1.3 root 3: .TH cpp 1 "30apr1993" "GNU Tools" "GNU Tools"
1.1 root 4: .SH NAME
1.1.1.2 root 5: cccp, cpp \- The GNU C-Compatible Compiler Preprocessor.
1.1 root 6: .SH SYNOPSIS
7: .hy 0
8: .na
9: .TP
10: .B cccp
11: .RB "[\|" \-$ "\|]"
1.1.1.3 root 12: .RB "[\|" \-A \c
13: .I predicate\c
14: .RB [ (\c
15: .I value\c
16: .BR ) ]\|]
1.1 root 17: .RB "[\|" \-C "\|]"
18: .RB "[\|" \-D \c
19: .I name\c
20: .RB [ =\c
21: .I definition\c
22: \&]\|]
23: .RB "[\|" \-dD "\|]"
24: .RB "[\|" \-dM "\|]"
25: .RB "[\|" "\-I\ "\c
26: .I directory\c
27: \&\|]
28: .RB "[\|" \-H "\|]"
29: .RB "[\|" \-I\- "\|]"
30: .RB "[\|" "\-imacros\ "\c
31: .I file\c
32: \&\|]
33: .RB "[\|" "\-include\ "\c
34: .I file\c
35: \&\|]
1.1.1.3 root 36: .RB "[\|" "\-idirafter\ "\c
37: .I dir\c
38: \&\|]
39: .RB "[\|" "\-iprefix\ "\c
40: .I prefix\c
41: \&\|]
42: .RB "[\|" "\-iwithprefix\ "\c
43: .I dir\c
44: \&\|]
1.1 root 45: .RB "[\|" \-lang\-c "\|]"
46: .RB "[\|" \-lang\-c++ "\|]"
47: .RB "[\|" \-lang\-objc "\|]"
48: .RB "[\|" \-lang\-objc++ "\|]"
49: .RB "[\|" \-lint "\|]"
1.1.1.4 root 50: .RB "[\|" \-M\ [ \-MG "\|]]"
51: .RB "[\|" \-MM\ [ \-MG "\|]]"
52: .RB "[\|" \-MD\ \c
53: .I file\ \c
54: \&\|]
55: .RB "[\|" \-MMD\ \c
56: .I file\ \c
57: \&\|]
1.1 root 58: .RB "[\|" \-nostdinc "\|]"
1.1.1.3 root 59: .RB "[\|" \-nostdinc++ "\|]"
1.1 root 60: .RB "[\|" \-P "\|]"
61: .RB "[\|" \-pedantic "\|]"
62: .RB "[\|" \-pedantic\-errors "\|]"
1.1.1.3 root 63: .RB "[\|" \-traditional "\|]"
1.1 root 64: .RB "[\|" \-trigraphs "\|]"
65: .RB "[\|" \-U \c
66: .I name\c
67: \&\|]
68: .RB "[\|" \-undef "\|]"
69: .RB "[\|" \-Wtrigraphs "\|]"
70: .RB "[\|" \-Wcomment "\|]"
71: .RB "[\|" \-Wall "\|]"
72: .RB "[\|" \-Wtraditional "\|]"
73: .br
74: .RB "[\|" \c
75: .I infile\c
76: .RB | \- "\|]"
77: .RB "[\|" \c
78: .I outfile\c
79: .RB | \- "\|]"
80: .ad b
81: .hy 1
82: .SH DESCRIPTION
83: The C preprocessor is a \c
84: .I macro processor\c
85: \& that is used automatically by
86: the C compiler to transform your program before actual compilation. It is
87: called a macro processor because it allows you to define \c
88: .I macros\c
89: \&,
90: which are brief abbreviations for longer constructs.
91:
92: The C preprocessor provides four separate facilities that you can use as
93: you see fit:
94: .TP
95: \(bu
96: Inclusion of header files. These are files of declarations that can be
97: substituted into your program.
98: .TP
99: \(bu
100: Macro expansion. You can define \c
101: .I macros\c
102: \&, which are abbreviations
103: for arbitrary fragments of C code, and then the C preprocessor will
104: replace the macros with their definitions throughout the program.
105: .TP
106: \(bu
1.1.1.5 ! root 107: Conditional compilation. Using special preprocessing directives, you
1.1 root 108: can include or exclude parts of the program according to various
109: conditions.
110: .TP
111: \(bu
112: Line control. If you use a program to combine or rearrange source files into
113: an intermediate file which is then compiled, you can use line control
114: to inform the compiler of where each source line originally came from.
115: .PP
116: C preprocessors vary in some details. For a full explanation of the
117: GNU C preprocessor, see the
118: .B info
119: file `\|\c
120: .B cpp.info\c
121: \&\|', or the manual
122: .I The C Preprocessor\c
123: \&. Both of these are built from the same documentation source file, `\|\c
124: .B cpp.texinfo\c
125: \&\|'. The GNU C
126: preprocessor provides a superset of the features of ANSI Standard C.
127:
128: ANSI Standard C requires the rejection of many harmless constructs commonly
129: used by today's C programs. Such incompatibility would be inconvenient for
130: users, so the GNU C preprocessor is configured to accept these constructs
131: by default. Strictly speaking, to get ANSI Standard C, you must use the
132: options `\|\c
133: .B \-trigraphs\c
134: \&\|', `\|\c
135: .B \-undef\c
136: \&\|' and `\|\c
137: .B \-pedantic\c
138: \&\|', but in
139: practice the consequences of having strict ANSI Standard C make it
140: undesirable to do this.
141:
142: Most often when you use the C preprocessor you will not have to invoke it
143: explicitly: the C compiler will do so automatically. However, the
144: preprocessor is sometimes useful individually.
145:
146: When you call the preprocessor individually, either name
147: (\c
148: .B cpp\c
149: \& or \c
150: .B cccp\c
151: \&) will do\(em\&they are completely synonymous.
152:
153: The C preprocessor expects two file names as arguments, \c
154: .I infile\c
155: \& and
156: \c
157: .I outfile\c
158: \&. The preprocessor reads \c
159: .I infile\c
160: \& together with any other
161: files it specifies with `\|\c
162: .B #include\c
163: \&\|'. All the output generated by the
164: combined input files is written in \c
165: .I outfile\c
166: \&.
167:
168: Either \c
169: .I infile\c
170: \& or \c
171: .I outfile\c
172: \& may be `\|\c
173: .B \-\c
174: \&\|', which as \c
175: .I infile\c
176: \&
177: means to read from standard input and as \c
178: .I outfile\c
179: \& means to write to
180: standard output. Also, if \c
181: .I outfile\c
182: \& or both file names are omitted,
183: the standard output and standard input are used for the omitted file names.
184: .SH OPTIONS
185: Here is a table of command options accepted by the C preprocessor.
186: These options can also be given when compiling a C program; they are
187: passed along automatically to the preprocessor when it is invoked by
188: the compiler.
189: .TP
190: .B \-P
191: Inhibit generation of `\|\c
192: .B #\c
193: \&\|'-lines with line-number information in
194: the output from the preprocessor. This might be
195: useful when running the preprocessor on something that is not C code
196: and will be sent to a program which might be confused by the
197: `\|\c
198: .B #\c
199: \&\|'-lines.
200: .TP
201: .B \-C
202: Do not discard comments: pass them through to the output file.
203: Comments appearing in arguments of a macro call will be copied to the
204: output before the expansion of the macro call.
205: .TP
1.1.1.3 root 206: .B \-traditional
207: Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
208: .TP
1.1 root 209: .B \-trigraphs
210: Process ANSI standard trigraph sequences. These are three-character
211: sequences, all starting with `\|\c
212: .B ??\c
213: \&\|', that are defined by ANSI C to
214: stand for single characters. For example, `\|\c
215: .B ??/\c
216: \&\|' stands for
217: `\|\c
218: .BR "\e" "\|',"
219: so `\|\c
220: .B '??/n'\c
221: \&\|' is a character constant for a newline.
222: Strictly speaking, the GNU C preprocessor does not support all
223: programs in ANSI Standard C unless `\|\c
224: .B \-trigraphs\c
225: \&\|' is used, but if
226: you ever notice the difference it will be with relief.
227:
228: You don't want to know any more about trigraphs.
229: .TP
230: .B \-pedantic
231: Issue warnings required by the ANSI C standard in certain cases such
232: as when text other than a comment follows `\|\c
233: .B #else\c
234: \&\|' or `\|\c
235: .B #endif\c
236: \&\|'.
237: .TP
238: .B \-pedantic\-errors
239: Like `\|\c
240: .B \-pedantic\c
241: \&\|', except that errors are produced rather than
242: warnings.
243: .TP
244: .B \-Wtrigraphs
245: Warn if any trigraphs are encountered (assuming they are enabled).
246: .TP
247: .B \-Wcomment
248: .TP
249: .B \-Wcomments
250: Warn whenever a comment-start sequence `\|\c
251: .B /*\c
252: \&\|' appears in a comment.
253: (Both forms have the same effect).
254: .TP
255: .B \-Wall
256: Requests both `\|\c
257: .B \-Wtrigraphs\c
258: \&\|' and `\|\c
259: .B \-Wcomment\c
260: \&\|' (but not
261: `\|\c
262: .B \-Wtraditional\c
263: \&\|').
264: .TP
265: .B \-Wtraditional
266: Warn about certain constructs that behave differently in traditional and
267: ANSI C.
268: .TP
269: .BI "\-I " directory\c
270: \&
271: Add the directory \c
272: .I directory\c
273: \& to the end of the list of
274: directories to be searched for header files.
275: This can be used to override a system header file, substituting your
276: own version, since these directories are searched before the system
277: header file directories. If you use more than one `\|\c
278: .B \-I\c
279: \&\|' option,
280: the directories are scanned in left-to-right order; the standard
281: system directories come after.
282: .TP
283: .B \-I\-
284: Any directories specified with `\|\c
285: .B \-I\c
286: \&\|' options before the `\|\c
287: .B \-I\-\c
288: \&\|'
289: option are searched only for the case of `\|\c
290: .B #include "\c
291: .I file\c
292: \&"\c
293: \&\|';
294: they are not searched for `\|\c
295: .B #include <\c
296: .I file\c
297: \&>\c
298: \&\|'.
299:
300: If additional directories are specified with `\|\c
301: .B \-I\c
302: \&\|' options after
303: the `\|\c
304: .B \-I\-\c
305: \&\|', these directories are searched for all `\|\c
306: .B #include\c
307: \&\|'
308: directives.
309:
310: In addition, the `\|\c
311: .B \-I\-\c
312: \&\|' option inhibits the use of the current
313: directory as the first search directory for `\|\c
314: .B #include "\c
315: .I file\c
316: \&"\c
317: \&\|'.
318: Therefore, the current directory is searched only if it is requested
319: explicitly with `\|\c
320: .B \-I.\c
321: \&\|'. Specifying both `\|\c
322: .B \-I\-\c
323: \&\|' and `\|\c
324: .B \-I.\c
325: \&\|'
326: allows you to control precisely which directories are searched before
327: the current one and which are searched after.
328: .TP
329: .B \-nostdinc
330: Do not search the standard system directories for header files.
331: Only the directories you have specified with `\|\c
332: .B \-I\c
333: \&\|' options
334: (and the current directory, if appropriate) are searched.
335: .TP
1.1.1.3 root 336: .B \-nostdinc++
337: Do not search for header files in the C++ specific standard
338: directories, but do still search the other standard directories.
339: (This option is used when building libg++.)
340: .TP
1.1 root 341: .BI "\-D " "name"\c
342: \&
343: Predefine \c
344: .I name\c
345: \& as a macro, with definition `\|\c
346: .B 1\c
347: \&\|'.
348: .TP
349: .BI "\-D " "name" = definition
350: \&
351: Predefine \c
352: .I name\c
353: \& as a macro, with definition \c
354: .I definition\c
355: \&.
356: There are no restrictions on the contents of \c
357: .I definition\c
358: \&, but if
359: you are invoking the preprocessor from a shell or shell-like program
360: you may need to use the shell's quoting syntax to protect characters
361: such as spaces that have a meaning in the shell syntax. If you use more than
362: one `\|\c
363: .B \-D\c
364: \&\|' for the same
365: .I name\c
366: \&, the rightmost definition takes effect.
367: .TP
368: .BI "\-U " "name"\c
369: \&
370: Do not predefine \c
371: .I name\c
372: \&. If both `\|\c
373: .B \-U\c
374: \&\|' and `\|\c
375: .B \-D\c
376: \&\|' are
377: specified for one name, the `\|\c
378: .B \-U\c
379: \&\|' beats the `\|\c
380: .B \-D\c
381: \&\|' and the name
382: is not predefined.
383: .TP
384: .B \-undef
385: Do not predefine any nonstandard macros.
386: .TP
1.1.1.3 root 387: .BI "\-A " "name(" value )
388: Assert (in the same way as the \c
389: .B #assert\c
1.1.1.5 ! root 390: \& directive)
1.1.1.3 root 391: the predicate \c
392: .I name\c
393: \& with tokenlist \c
394: .I value\c
395: \&. Remember to escape or quote the parentheses on
396: shell command lines.
397:
398: You can use `\|\c
399: .B \-A-\c
400: \&\|' to disable all predefined assertions; it also
401: undefines all predefined macros.
402: .TP
1.1 root 403: .B \-dM
404: Instead of outputting the result of preprocessing, output a list of
405: `\|\c
406: .B #define\c
1.1.1.5 ! root 407: \&\|' directives for all the macros defined during the
1.1 root 408: execution of the preprocessor, including predefined macros. This gives
409: you a way of finding out what is predefined in your version of the
410: preprocessor; assuming you have no file `\|\c
411: .B foo.h\c
412: \&\|', the command
413: .sp
414: .br
415: touch\ foo.h;\ cpp\ \-dM\ foo.h
416: .br
417: .sp
418: will show the values of any predefined macros.
419: .TP
420: .B \-dD
421: Like `\|\c
422: .B \-dM\c
423: \&\|' except in two respects: it does \c
424: .I not\c
425: \& include the
426: predefined macros, and it outputs \c
427: .I both\c
428: \& the `\|\c
429: .B #define\c
430: \&\|'
1.1.1.5 ! root 431: directives and the result of preprocessing. Both kinds of output go to
1.1 root 432: the standard output file.
433: .PP
434: .TP
1.1.1.4 root 435: .BR \-M\ [ \-MG ]
1.1 root 436: Instead of outputting the result of preprocessing, output a rule
437: suitable for \c
438: .B make\c
439: \& describing the dependencies of the main
440: source file. The preprocessor outputs one \c
441: .B make\c
442: \& rule containing
443: the object file name for that source file, a colon, and the names of
444: all the included files. If there are many included files then the
445: rule is split into several lines using `\|\c
1.1.1.4 root 446: .B \\\\\c
1.1 root 447: \&\|'-newline.
448:
1.1.1.4 root 449: `\|\c
450: .B \-MG\c
451: \&\|' says to treat missing header files as generated files and assume \c
452: they live in the same directory as the source file. It must be specified \c
453: in addition to `\|\c
454: .B \-M\c
455: \&\|'.
456:
1.1 root 457: This feature is used in automatic updating of makefiles.
458: .TP
1.1.1.4 root 459: .BR \-MM\ [ \-MG ]
1.1 root 460: Like `\|\c
461: .B \-M\c
462: \&\|' but mention only the files included with `\|\c
463: .B #include
464: "\c
465: .I file\c
466: \&"\c
467: \&\|'. System header files included with `\|\c
468: .B #include
469: <\c
470: .I file\c
471: \&>\c
472: \&\|' are omitted.
473: .TP
1.1.1.4 root 474: .BI \-MD\ file
1.1 root 475: Like `\|\c
476: .B \-M\c
1.1.1.4 root 477: \&\|' but the dependency information is written to `\|\c
478: .I file\c
479: \&\|'. This is in addition to compiling the file as
1.1 root 480: specified\(em\&`\|\c
481: .B \-MD\c
482: \&\|' does not inhibit ordinary compilation the way
483: `\|\c
484: .B \-M\c
485: \&\|' does.
486:
1.1.1.4 root 487: When invoking gcc, do not specify the `\|\c
488: .I file\c
489: \&\|' argument. Gcc will create file names made by replacing `\|\c
490: .B .c\c
491: \&\|' with `\|\c
492: .B .d\c
493: \&\|' at the end of the input file names.
494:
1.1 root 495: In Mach, you can use the utility \c
496: .B md\c
1.1.1.4 root 497: \& to merge multiple files
1.1 root 498: into a single dependency file suitable for using with the `\|\c
499: .B make\c
500: \&\|'
501: command.
502: .TP
1.1.1.4 root 503: .BI \-MMD\ file
1.1 root 504: Like `\|\c
505: .B \-MD\c
506: \&\|' except mention only user header files, not system
507: header files.
508: .TP
509: .B \-H
510: Print the name of each header file used, in addition to other normal
511: activities.
512: .TP
513: .BI "\-imacros " "file"\c
514: \&
515: Process \c
516: .I file\c
517: \& as input, discarding the resulting output, before
518: processing the regular input file. Because the output generated from
519: \c
520: .I file\c
521: \& is discarded, the only effect of `\|\c
522: .B \-imacros \c
523: .I file\c
524: \&\c
525: \&\|' is to
526: make the macros defined in \c
527: .I file\c
528: \& available for use in the main
529: input. The preprocessor evaluates any `\|\c
530: .B \-D\c
531: \&\|' and `\|\c
532: .B \-U\c
533: \&\|' options
534: on the command line before processing `\|\c
535: .B \-imacros \c
536: .I file\c
537: \&\|' \c
538: \&.
539: .TP
540: .BI "\-include " "file"
541: Process
542: .I file
543: as input, and include all the resulting output,
544: before processing the regular input file.
545: .TP
1.1.1.3 root 546: .BI "-idirafter " "dir"\c
547: \&
548: Add the directory \c
549: .I dir\c
550: \& to the second include path. The directories
551: on the second include path are searched when a header file is not found
552: in any of the directories in the main include path (the one that
553: `\|\c
554: .B \-I\c
555: \&\|' adds to).
556: .TP
557: .BI "-iprefix " "prefix"\c
558: \&
559: Specify \c
560: .I prefix\c
561: \& as the prefix for subsequent `\|\c
562: .B \-iwithprefix\c
563: \&\|'
564: options.
565: .TP
566: .BI "-iwithprefix " "dir"\c
567: \&
568: Add a directory to the second include path. The directory's name is
569: made by concatenating \c
570: .I prefix\c
571: \& and \c
572: .I dir\c
573: \&, where \c
574: .I prefix\c
575: \&
576: was specified previously with `\|\c
577: .B \-iprefix\c
578: \&\|'.
579: .TP
1.1 root 580: .B \-lang-c
581: .TP
582: .B \-lang-c++
583: .TP
584: .B \-lang-objc
585: .TP
586: .B \-lang-objc++
587: Specify the source language. `\|\c
588: .B \-lang-c++\c
589: \&\|' makes the preprocessor
590: handle C++ comment syntax, and includes extra default include
591: directories for C++, and `\|\c
592: .B \-lang-objc\c
593: \&\|' enables the Objective C
594: `\|\c
595: .B #import\c
596: \&\|' directive. `\|\c
597: .B \-lang-c\c
598: \&\|' explicitly turns off both of
599: these extensions, and `\|\c
600: .B \-lang-objc++\c
601: \&\|' enables both.
602:
603: These options are generated by the compiler driver \c
604: .B gcc\c
605: \&, but not
606: passed from the `\|\c
607: .B gcc\c
608: \&\|' command line.
609: .TP
610: .B \-lint
611: Look for commands to the program checker \c
612: .B lint\c
613: \& embedded in
614: comments, and emit them preceded by `\|\c
615: .B #pragma lint\c
616: \&\|'. For example,
617: the comment `\|\c
618: .B /* NOTREACHED */\c
619: \&\|' becomes `\|\c
620: .B #pragma lint
621: NOTREACHED\c
622: \&\|'.
623:
624: This option is available only when you call \c
625: .B cpp\c
626: \& directly;
627: \c
628: .B gcc\c
629: \& will not pass it from its command line.
630: .TP
631: .B \-$
632: Forbid the use of `\|\c
633: .B $\c
634: \&\|' in identifiers. This is required for ANSI
635: conformance. \c
636: .B gcc\c
637: \& automatically supplies this option to the
638: preprocessor if you specify `\|\c
639: .B \-ansi\c
640: \&\|', but \c
641: .B gcc\c
642: \& doesn't
643: recognize the `\|\c
644: .B \-$\c
645: \&\|' option itself\(em\&to use it without the other
646: effects of `\|\c
647: .B \-ansi\c
648: \&\|', you must call the preprocessor directly.
649: .SH "SEE ALSO"
650: .RB "`\|" Cpp "\|'"
651: entry in
652: .B info\c
653: \&;
654: .I The C Preprocessor\c
1.1.1.2 root 655: , Richard M. Stallman.
1.1 root 656: .br
657: .BR gcc "(" 1 ");"
658: .RB "`\|" Gcc "\|'"
659: entry in
660: .B info\c
661: \&;
662: .I
663: Using and Porting GNU CC (for version 2.0)\c
1.1.1.2 root 664: , Richard M. Stallman.
1.1 root 665: .SH COPYING
1.1.1.3 root 666: Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
1.1 root 667: .PP
668: Permission is granted to make and distribute verbatim copies of
669: this manual provided the copyright notice and this permission notice
670: are preserved on all copies.
671: .PP
672: Permission is granted to copy and distribute modified versions of this
673: manual under the conditions for verbatim copying, provided that the
674: entire resulting derived work is distributed under the terms of a
675: permission notice identical to this one.
676: .PP
677: Permission is granted to copy and distribute translations of this
678: manual into another language, under the above conditions for modified
679: versions, except that this permission notice may be included in
680: translations approved by the Free Software Foundation instead of in
681: the original English.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.