source: trunk/third/gcc/cccp.1 @ 8834

Revision 8834, 15.5 KB checked in by ghudson, 28 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r8833, which included commits to RCS files with non-trunk default branches.
Line 
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
5cccp, 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\  [ \-MG "\|]]"
51.RB "[\|" \-MM\  [ \-MG "\|]]"
52.RB "[\|" \-MD\  \c
53.I file\ \c
54\&\|]
55.RB "[\|" \-MMD\  \c
56.I file\ \c
57\&\|]
58.RB "[\|" \-nostdinc "\|]"
59.RB "[\|" \-nostdinc++ "\|]"
60.RB "[\|" \-P "\|]"
61.RB "[\|" \-pedantic "\|]"
62.RB "[\|" \-pedantic\-errors "\|]"
63.RB "[\|" \-traditional "\|]"
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
83The C preprocessor is a \c
84.I macro processor\c
85\& that is used automatically by
86the C compiler to transform your program before actual compilation.  It is
87called a macro processor because it allows you to define \c
88.I macros\c
89\&,
90which are brief abbreviations for longer constructs.
91
92The C preprocessor provides four separate facilities that you can use as
93you see fit:
94.TP
95\(bu
96Inclusion of header files.  These are files of declarations that can be
97substituted into your program.
98.TP
99\(bu
100Macro expansion.  You can define \c
101.I macros\c
102\&, which are abbreviations
103for arbitrary fragments of C code, and then the C preprocessor will
104replace the macros with their definitions throughout the program.
105.TP
106\(bu
107Conditional compilation.  Using special preprocessing directives, you
108can include or exclude parts of the program according to various
109conditions.
110.TP
111\(bu
112Line control.  If you use a program to combine or rearrange source files into
113an intermediate file which is then compiled, you can use line control
114to inform the compiler of where each source line originally came from.
115.PP
116C preprocessors vary in some details.  For a full explanation of the
117GNU C preprocessor, see the
118.B info
119file `\|\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
126preprocessor provides a superset of the features of ANSI Standard C.
127
128ANSI Standard C requires the rejection of many harmless constructs commonly
129used by today's C programs.  Such incompatibility would be inconvenient for
130users, so the GNU C preprocessor is configured to accept these constructs
131by default.  Strictly speaking, to get ANSI Standard C, you must use the
132options `\|\c
133.B \-trigraphs\c
134\&\|', `\|\c
135.B \-undef\c
136\&\|' and `\|\c
137.B \-pedantic\c
138\&\|', but in
139practice the consequences of having strict ANSI Standard C make it
140undesirable to do this. 
141
142Most often when you use the C preprocessor you will not have to invoke it
143explicitly: the C compiler will do so automatically.  However, the
144preprocessor is sometimes useful individually.
145
146When 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
153The 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
161files it specifies with `\|\c
162.B #include\c
163\&\|'.  All the output generated by the
164combined input files is written in \c
165.I outfile\c
166\&.
167
168Either \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\&
177means to read from standard input and as \c
178.I outfile\c
179\& means to write to
180standard output.  Also, if \c
181.I outfile\c
182\& or both file names are omitted,
183the standard output and standard input are used for the omitted file names.
184.SH OPTIONS
185Here is a table of command options accepted by the C preprocessor. 
186These options can also be given when compiling a C program; they are
187passed along automatically to the preprocessor when it is invoked by
188the compiler.
189.TP
190.B \-P
191Inhibit generation of `\|\c
192.B #\c
193\&\|'-lines with line-number information in
194the output from the preprocessor.  This might be
195useful when running the preprocessor on something that is not C code
196and will be sent to a program which might be confused by the
197`\|\c
198.B #\c
199\&\|'-lines.
200.TP
201.B \-C
202Do not discard comments: pass them through to the output file.
203Comments appearing in arguments of a macro call will be copied to the
204output before the expansion of the macro call.
205.TP
206.B \-traditional
207Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
208.TP
209.B \-trigraphs
210Process ANSI standard trigraph sequences.  These are three-character
211sequences, all starting with `\|\c
212.B ??\c
213\&\|', that are defined by ANSI C to
214stand for single characters.  For example, `\|\c
215.B ??/\c
216\&\|' stands for
217`\|\c
218.BR "\e" "\|',"
219so `\|\c
220.B '??/n'\c
221\&\|' is a character constant for a newline.
222Strictly speaking, the GNU C preprocessor does not support all
223programs in ANSI Standard C unless `\|\c
224.B \-trigraphs\c
225\&\|' is used, but if
226you ever notice the difference it will be with relief.
227
228You don't want to know any more about trigraphs.
229.TP
230.B \-pedantic
231Issue warnings required by the ANSI C standard in certain cases such
232as 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
239Like `\|\c
240.B \-pedantic\c
241\&\|', except that errors are produced rather than
242warnings.
243.TP
244.B \-Wtrigraphs
245Warn if any trigraphs are encountered (assuming they are enabled).
246.TP
247.B \-Wcomment
248.TP
249.B \-Wcomments
250Warn 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
256Requests 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
266Warn about certain constructs that behave differently in traditional and
267ANSI C.
268.TP
269.BI "\-I " directory\c
270\&
271Add the directory \c
272.I directory\c
273\& to the end of the list of
274directories to be searched for header files.
275This can be used to override a system header file, substituting your
276own version, since these directories are searched before the system
277header file directories.  If you use more than one `\|\c
278.B \-I\c
279\&\|' option,
280the directories are scanned in left-to-right order; the standard
281system directories come after.
282.TP
283.B \-I\-
284Any directories specified with `\|\c
285.B \-I\c
286\&\|' options before the `\|\c
287.B \-I\-\c
288\&\|'
289option are searched only for the case of `\|\c
290.B #include "\c
291.I file\c
292\&"\c
293\&\|';
294they are not searched for `\|\c
295.B #include <\c
296.I file\c
297\&>\c
298\&\|'.
299
300If additional directories are specified with `\|\c
301.B \-I\c
302\&\|' options after
303the `\|\c
304.B \-I\-\c
305\&\|', these directories are searched for all `\|\c
306.B #include\c
307\&\|'
308directives.
309
310In addition, the `\|\c
311.B \-I\-\c
312\&\|' option inhibits the use of the current
313directory as the first search directory for `\|\c
314.B #include "\c
315.I file\c
316\&"\c
317\&\|'.
318Therefore, the current directory is searched only if it is requested
319explicitly with `\|\c
320.B \-I.\c
321\&\|'.  Specifying both `\|\c
322.B \-I\-\c
323\&\|' and `\|\c
324.B \-I.\c
325\&\|'
326allows you to control precisely which directories are searched before
327the current one and which are searched after.
328.TP
329.B \-nostdinc
330Do not search the standard system directories for header files.
331Only the directories you have specified with `\|\c
332.B \-I\c
333\&\|' options
334(and the current directory, if appropriate) are searched.
335.TP
336.B \-nostdinc++
337Do not search for header files in the C++ specific standard
338directories, but do still search the other standard directories.
339(This option is used when building libg++.)
340.TP
341.BI "\-D " "name"\c
342\&
343Predefine \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\&
351Predefine \c
352.I name\c
353\& as a macro, with definition \c
354.I definition\c
355\&.
356There are no restrictions on the contents of \c
357.I definition\c
358\&, but if
359you are invoking the preprocessor from a shell or shell-like program
360you may need to use the shell's quoting syntax to protect characters
361such as spaces that have a meaning in the shell syntax.  If you use more than
362one `\|\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\&
370Do not predefine \c
371.I name\c
372\&.  If both `\|\c
373.B \-U\c
374\&\|' and `\|\c
375.B \-D\c
376\&\|' are
377specified for one name, the `\|\c
378.B \-U\c
379\&\|' beats the `\|\c
380.B \-D\c
381\&\|' and the name
382is not predefined.
383.TP
384.B \-undef
385Do not predefine any nonstandard macros.
386.TP
387.BI "\-A " "name(" value )
388Assert (in the same way as the \c
389.B #assert\c
390\& directive)
391the predicate \c
392.I name\c
393\& with tokenlist \c
394.I value\c
395\&.  Remember to escape or quote the parentheses on
396shell command lines.
397
398You can use `\|\c
399.B \-A-\c
400\&\|' to disable all predefined assertions; it also
401undefines all predefined macros.
402.TP
403.B \-dM
404Instead of outputting the result of preprocessing, output a list of
405`\|\c
406.B #define\c
407\&\|' directives for all the macros defined during the
408execution of the preprocessor, including predefined macros.  This gives
409you a way of finding out what is predefined in your version of the
410preprocessor; assuming you have no file `\|\c
411.B foo.h\c
412\&\|', the command
413.sp
414.br
415touch\ foo.h;\ cpp\ \-dM\ foo.h
416.br
417.sp
418will show the values of any predefined macros.
419.TP
420.B \-dD
421Like `\|\c
422.B \-dM\c
423\&\|' except in two respects: it does \c
424.I not\c
425\& include the
426predefined macros, and it outputs \c
427.I both\c
428\& the `\|\c
429.B #define\c
430\&\|'
431directives and the result of preprocessing.  Both kinds of output go to
432the standard output file.
433.PP
434.TP
435.BR \-M\  [ \-MG ]
436Instead of outputting the result of preprocessing, output a rule
437suitable for \c
438.B make\c
439\& describing the dependencies of the main
440source file.  The preprocessor outputs one \c
441.B make\c
442\& rule containing
443the object file name for that source file, a colon, and the names of
444all the included files.  If there are many included files then the
445rule is split into several lines using `\|\c
446.B \\\\\c
447\&\|'-newline.
448
449`\|\c
450.B \-MG\c
451\&\|' says to treat missing header files as generated files and assume \c
452they live in the same directory as the source file.  It must be specified \c
453in addition to `\|\c
454.B \-M\c
455\&\|'.
456
457This feature is used in automatic updating of makefiles.
458.TP
459.BR \-MM\  [ \-MG ]
460Like `\|\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
474.BI \-MD\  file
475Like `\|\c
476.B \-M\c
477\&\|' but the dependency information is written to `\|\c
478.I file\c
479\&\|'.  This is in addition to compiling the file as
480specified\(em\&`\|\c
481.B \-MD\c
482\&\|' does not inhibit ordinary compilation the way
483`\|\c
484.B \-M\c
485\&\|' does.
486
487When 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
495In Mach, you can use the utility \c
496.B md\c
497\& to merge multiple files
498into a single dependency file suitable for using with the `\|\c
499.B make\c
500\&\|'
501command.
502.TP
503.BI \-MMD\  file
504Like `\|\c
505.B \-MD\c
506\&\|' except mention only user header files, not system
507header files.
508.TP
509.B \-H
510Print the name of each header file used, in addition to other normal
511activities.
512.TP
513.BI "\-imacros " "file"\c
514\&
515Process \c
516.I file\c
517\& as input, discarding the resulting output, before
518processing 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
526make the macros defined in \c
527.I file\c
528\& available for use in the main
529input.  The preprocessor evaluates any `\|\c
530.B \-D\c
531\&\|' and `\|\c
532.B \-U\c
533\&\|' options
534on the command line before processing `\|\c
535.B \-imacros \c
536.I file\c
537\&\|' \c
538\&.
539.TP
540.BI "\-include " "file"
541Process
542.I file
543as input, and include all the resulting output,
544before processing the regular input file. 
545.TP
546.BI "-idirafter " "dir"\c
547\&
548Add the directory \c
549.I dir\c
550\& to the second include path.  The directories
551on the second include path are searched when a header file is not found
552in 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\&
559Specify \c
560.I prefix\c
561\& as the prefix for subsequent `\|\c
562.B \-iwithprefix\c
563\&\|'
564options.
565.TP
566.BI "-iwithprefix " "dir"\c
567\&
568Add a directory to the second include path.  The directory's name is
569made by concatenating \c
570.I prefix\c
571\& and \c
572.I dir\c
573\&, where \c
574.I prefix\c
575\&
576was specified previously with `\|\c
577.B \-iprefix\c
578\&\|'.
579.TP
580.B \-lang-c
581.TP
582.B \-lang-c++
583.TP
584.B \-lang-objc
585.TP
586.B \-lang-objc++
587Specify the source language.  `\|\c
588.B \-lang-c++\c
589\&\|' makes the preprocessor
590handle C++ comment syntax, and includes extra default include
591directories 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
599these extensions, and `\|\c
600.B \-lang-objc++\c
601\&\|' enables both.
602
603These options are generated by the compiler driver \c
604.B gcc\c
605\&, but not
606passed from the `\|\c
607.B gcc\c
608\&\|' command line.
609.TP
610.B \-lint
611Look for commands to the program checker \c
612.B lint\c
613\& embedded in
614comments, and emit them preceded by `\|\c
615.B #pragma lint\c
616\&\|'.  For example,
617the comment `\|\c
618.B /* NOTREACHED */\c
619\&\|' becomes `\|\c
620.B #pragma lint
621NOTREACHED\c
622\&\|'.
623
624This 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 \-$
632Forbid the use of `\|\c
633.B $\c
634\&\|' in identifiers.  This is required for ANSI
635conformance.  \c
636.B gcc\c
637\& automatically supplies this option to the
638preprocessor if you specify `\|\c
639.B \-ansi\c
640\&\|', but \c
641.B gcc\c
642\& doesn't
643recognize the `\|\c
644.B \-$\c
645\&\|' option itself\(em\&to use it without the other
646effects of `\|\c
647.B \-ansi\c
648\&\|', you must call the preprocessor directly.
649.SH "SEE ALSO"
650.RB "`\|" Cpp "\|'"
651entry in
652.B info\c
653\&;
654.I The C Preprocessor\c
655, Richard M. Stallman.
656.br
657.BR gcc "(" 1 ");"
658.RB "`\|" Gcc "\|'"
659entry in
660.B info\c
661\&;
662.I
663Using and Porting GNU CC (for version 2.0)\c
664, Richard M. Stallman.
665.SH COPYING
666Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
667.PP
668Permission is granted to make and distribute verbatim copies of
669this manual provided the copyright notice and this permission notice
670are preserved on all copies.
671.PP
672Permission is granted to copy and distribute modified versions of this
673manual under the conditions for verbatim copying, provided that the
674entire resulting derived work is distributed under the terms of a
675permission notice identical to this one.
676.PP
677Permission is granted to copy and distribute translations of this
678manual into another language, under the above conditions for modified
679versions, except that this permission notice may be included in
680translations approved by the Free Software Foundation instead of in
681the original English.
Note: See TracBrowser for help on using the repository browser.