1 .\" $FreeBSD: src/contrib/gcc/cccp.1,v 1.3 1999/09/19 08:18:18 obrien Exp $
2 .\" $DragonFly: src/contrib/gcc/Attic/cccp.1,v 1.2 2003/06/17 04:23:59 dillon Exp $
3 .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation \-*-Text-*-
4 .\" See section COPYING for conditions for redistribution
5 .TH cpp 1 "April 30, 1993" "FreeBSD" "GNU Tools"
7 cpp \- The GNU C-Compatible Compiler Preprocessor.
32 .RB "[\|" "\-imacros\ "\c
35 .RB "[\|" "\-include\ "\c
38 .RB "[\|" "\-idirafter\ "\c
41 .RB "[\|" "\-iprefix\ "\c
44 .RB "[\|" "\-iwithprefix\ "\c
47 .RB "[\|" \-lang\-c "\|]"
48 .RB "[\|" \-lang\-c++ "\|]"
49 .RB "[\|" \-lang\-objc "\|]"
50 .RB "[\|" \-lang\-objc++ "\|]"
51 .RB "[\|" \-lint "\|]"
52 .RB "[\|" \-M\ [ \-MG "\|]]"
53 .RB "[\|" \-MM\ [ \-MG "\|]]"
60 .RB "[\|" \-nostdinc "\|]"
61 .RB "[\|" \-nostdinc++ "\|]"
63 .RB "[\|" \-pedantic "\|]"
64 .RB "[\|" \-pedantic\-errors "\|]"
65 .RB "[\|" \-traditional "\|]"
66 .RB "[\|" \-trigraphs "\|]"
70 .RB "[\|" \-undef "\|]"
71 .RB "[\|" \-Wtrigraphs "\|]"
72 .RB "[\|" \-Wcomment "\|]"
73 .RB "[\|" \-Wall "\|]"
74 .RB "[\|" \-Wtraditional "\|]"
85 The C preprocessor is a \c
87 \& that is used automatically by
88 the C compiler to transform your program before actual compilation. It is
89 called a macro processor because it allows you to define \c
92 which are brief abbreviations for longer constructs.
94 The C preprocessor provides four separate facilities that you can use as
98 Inclusion of header files. These are files of declarations that can be
99 substituted into your program.
102 Macro expansion. You can define \c
104 \&, which are abbreviations
105 for arbitrary fragments of C code, and then the C preprocessor will
106 replace the macros with their definitions throughout the program.
109 Conditional compilation. Using special preprocessing directives, you
110 can include or exclude parts of the program according to various
114 Line control. If you use a program to combine or rearrange source files into
115 an intermediate file which is then compiled, you can use line control
116 to inform the compiler of where each source line originally came from.
118 C preprocessors vary in some details. For a full explanation of the
119 GNU C preprocessor, see the
124 .I The C Preprocessor\c
125 \&. Both of these are built from the same documentation source file, `\|\c
128 preprocessor provides a superset of the features of ANSI Standard C.
130 ANSI Standard C requires the rejection of many harmless constructs commonly
131 used by today's C programs. Such incompatibility would be inconvenient for
132 users, so the GNU C preprocessor is configured to accept these constructs
133 by default. Strictly speaking, to get ANSI Standard C, you must use the
141 practice the consequences of having strict ANSI Standard C make it
142 undesirable to do this.
144 Most often when you use the C preprocessor you will not have to invoke it
145 explicitly: the C compiler will do so automatically. However, the
146 preprocessor is sometimes useful individually.
148 The C preprocessor expects two file names as arguments, \c
153 \&. The preprocessor reads \c
155 \& together with any other
156 files it specifies with `\|\c
158 \&\|'. All the output generated by the
159 combined input files is written in \c
172 means to read from standard input and as \c
175 standard output. Also, if \c
177 \& or both file names are omitted,
178 the standard output and standard input are used for the omitted file names.
180 Here is a table of command options accepted by the C preprocessor.
181 These options can also be given when compiling a C program; they are
182 passed along automatically to the preprocessor when it is invoked by
186 Inhibit generation of `\|\c
188 \&\|'-lines with line-number information in
189 the output from the preprocessor. This might be
190 useful when running the preprocessor on something that is not C code
191 and will be sent to a program which might be confused by the
197 Do not discard comments: pass them through to the output file.
198 Comments appearing in arguments of a macro call will be copied to the
199 output before the expansion of the macro call.
202 Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
205 Process ANSI standard trigraph sequences. These are three-character
206 sequences, all starting with `\|\c
208 \&\|', that are defined by ANSI C to
209 stand for single characters. For example, `\|\c
216 \&\|' is a character constant for a newline.
217 Strictly speaking, the GNU C preprocessor does not support all
218 programs in ANSI Standard C unless `\|\c
220 \&\|' is used, but if
221 you ever notice the difference it will be with relief.
223 You don't want to know any more about trigraphs.
226 Issue warnings required by the ANSI C standard in certain cases such
227 as when text other than a comment follows `\|\c
233 .B \-pedantic\-errors
236 \&\|', except that errors are produced rather than
240 Warn if any trigraphs are encountered (assuming they are enabled).
245 Warn whenever a comment-start sequence `\|\c
247 \&\|' appears in a comment.
248 (Both forms have the same effect).
261 Warn about certain constructs that behave differently in traditional and
264 .BI "\-I " directory\c
268 \& to the end of the list of
269 directories to be searched for header files.
270 This can be used to override a system header file, substituting your
271 own version, since these directories are searched before the system
272 header file directories. If you use more than one `\|\c
275 the directories are scanned in left-to-right order; the standard
276 system directories come after.
279 Any directories specified with `\|\c
281 \&\|' options before the `\|\c
284 option are searched only for the case of `\|\c
289 they are not searched for `\|\c
295 If additional directories are specified with `\|\c
300 \&\|', these directories are searched for all `\|\c
305 In addition, the `\|\c
307 \&\|' option inhibits the use of the current
308 directory as the first search directory for `\|\c
313 Therefore, the current directory is searched only if it is requested
314 explicitly with `\|\c
316 \&\|'. Specifying both `\|\c
321 allows you to control precisely which directories are searched before
322 the current one and which are searched after.
325 Do not search the standard system directories for header files.
326 Only the directories you have specified with `\|\c
329 (and the current directory, if appropriate) are searched.
332 Do not search for header files in the C++ specific standard
333 directories, but do still search the other standard directories.
334 (This option is used when building libg++.)
340 \& as a macro, with definition `\|\c
344 .BI "\-D " "name" = definition
348 \& as a macro, with definition \c
351 There are no restrictions on the contents of \c
354 you are invoking the preprocessor from a shell or shell-like program
355 you may need to use the shell's quoting syntax to protect characters
356 such as spaces that have a meaning in the shell syntax. If you use more than
361 \&, the rightmost definition takes effect.
372 specified for one name, the `\|\c
374 \&\|' beats the `\|\c
380 Do not predefine any nonstandard macros.
382 .BI "\-A " "name(" value )
383 Assert (in the same way as the \c
390 \&. Remember to escape or quote the parentheses on
395 \&\|' to disable all predefined assertions; it also
396 undefines all predefined macros.
399 Instead of outputting the result of preprocessing, output a list of
402 \&\|' directives for all the macros defined during the
403 execution of the preprocessor, including predefined macros. This gives
404 you a way of finding out what is predefined in your version of the
405 preprocessor; assuming you have no file `\|\c
410 touch\ foo.h;\ cpp\ \-dM\ foo.h
413 will show the values of any predefined macros.
418 \&\|' except in two respects: it does \c
421 predefined macros, and it outputs \c
426 directives and the result of preprocessing. Both kinds of output go to
427 the standard output file.
431 Instead of outputting the result of preprocessing, output a rule
434 \& describing the dependencies of the main
435 source file. The preprocessor outputs one \c
438 the object file name for that source file, a colon, and the names of
439 all the included files. If there are many included files then the
440 rule is split into several lines using `\|\c
446 \&\|' says to treat missing header files as generated files and assume \c
447 they live in the same directory as the source file. It must be specified \c
452 This feature is used in automatic updating of makefiles.
457 \&\|' but mention only the files included with `\|\c
462 \&\|'. System header files included with `\|\c
472 \&\|' but the dependency information is written to `\|\c
474 \&\|'. This is in addition to compiling the file as
477 \&\|' does not inhibit ordinary compilation the way
482 When invoking gcc, do not specify the `\|\c
484 \&\|' argument. Gcc will create file names made by replacing `\|\c
488 \&\|' at the end of the input file names.
490 In Mach, you can use the utility \c
492 \& to merge multiple files
493 into a single dependency file suitable for using with the `\|\c
501 \&\|' except mention only user header files, not system
505 Print the name of each header file used, in addition to other normal
508 .BI "\-imacros " "file"\c
512 \& as input, discarding the resulting output, before
513 processing the regular input file. Because the output generated from
516 \& is discarded, the only effect of `\|\c
521 make the macros defined in \c
523 \& available for use in the main
524 input. The preprocessor evaluates any `\|\c
529 on the command line before processing `\|\c
535 .BI "\-include " "file"
538 as input, and include all the resulting output,
539 before processing the regular input file.
541 .BI "-idirafter " "dir"\c
545 \& to the second include path. The directories
546 on the second include path are searched when a header file is not found
547 in any of the directories in the main include path (the one that
552 .BI "-iprefix " "prefix"\c
556 \& as the prefix for subsequent `\|\c
561 .BI "-iwithprefix " "dir"\c
563 Add a directory to the second include path. The directory's name is
564 made by concatenating \c
571 was specified previously with `\|\c
582 Specify the source language. `\|\c
584 \&\|' makes the preprocessor
585 handle C++ comment syntax, and includes extra default include
586 directories for C++, and `\|\c
588 \&\|' enables the Objective C
591 \&\|' directive. `\|\c
593 \&\|' explicitly turns off both of
594 these extensions, and `\|\c
598 These options are generated by the compiler driver \c
601 passed from the `\|\c
606 Look for commands to the program checker \c
609 comments, and emit them preceded by `\|\c
613 .B /* NOTREACHED */\c
619 This option is available only when you call \c
624 \& will not pass it from its command line.
627 Forbid the use of `\|\c
629 \&\|' in identifiers. This was formerly required for strict conformance
630 to the C Standard before the standard was corrected. \c
632 This option is available only when you call \c
636 \& will not pass it from its command line.
642 .I The C Preprocessor\c
643 , Richard M. Stallman.
651 Using and Porting GNU CC (for version 2.0)\c
652 , Richard M. Stallman.
654 Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
656 Permission is granted to make and distribute verbatim copies of
657 this manual provided the copyright notice and this permission notice
658 are preserved on all copies.
660 Permission is granted to copy and distribute modified versions of this
661 manual under the conditions for verbatim copying, provided that the
662 entire resulting derived work is distributed under the terms of a
663 permission notice identical to this one.
665 Permission is granted to copy and distribute translations of this
666 manual into another language, under the above conditions for modified
667 versions, except that this permission notice may be included in
668 translations approved by the Free Software Foundation instead of in
669 the original English.