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