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