2 .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation \-*-Text-*-
3 .\" See section COPYING for conditions for redistribution
4 .TH cpp 1 "April 30, 1993" "FreeBSD" "GNU Tools"
6 cpp \- The GNU C-Compatible Compiler Preprocessor.
31 .RB "[\|" "\-imacros\ "\c
34 .RB "[\|" "\-include\ "\c
37 .RB "[\|" "\-idirafter\ "\c
40 .RB "[\|" "\-iprefix\ "\c
43 .RB "[\|" "\-iwithprefix\ "\c
46 .RB "[\|" \-lang\-c "\|]"
47 .RB "[\|" \-lang\-c++ "\|]"
48 .RB "[\|" \-lang\-objc "\|]"
49 .RB "[\|" \-lang\-objc++ "\|]"
50 .RB "[\|" \-lint "\|]"
51 .RB "[\|" \-M\ [ \-MG "\|]]"
52 .RB "[\|" \-MM\ [ \-MG "\|]]"
59 .RB "[\|" \-nostdinc "\|]"
60 .RB "[\|" \-nostdinc++ "\|]"
62 .RB "[\|" \-pedantic "\|]"
63 .RB "[\|" \-pedantic\-errors "\|]"
64 .RB "[\|" \-traditional "\|]"
65 .RB "[\|" \-trigraphs "\|]"
69 .RB "[\|" \-undef "\|]"
70 .RB "[\|" \-Wtrigraphs "\|]"
71 .RB "[\|" \-Wcomment "\|]"
72 .RB "[\|" \-Wall "\|]"
73 .RB "[\|" \-Wtraditional "\|]"
84 The C preprocessor is a \c
86 \& that is used automatically by
87 the C compiler to transform your program before actual compilation. It is
88 called a macro processor because it allows you to define \c
91 which are brief abbreviations for longer constructs.
93 The C preprocessor provides four separate facilities that you can use as
97 Inclusion of header files. These are files of declarations that can be
98 substituted into your program.
101 Macro expansion. You can define \c
103 \&, which are abbreviations
104 for arbitrary fragments of C code, and then the C preprocessor will
105 replace the macros with their definitions throughout the program.
108 Conditional compilation. Using special preprocessing directives, you
109 can include or exclude parts of the program according to various
113 Line control. If you use a program to combine or rearrange source files into
114 an intermediate file which is then compiled, you can use line control
115 to inform the compiler of where each source line originally came from.
117 C preprocessors vary in some details. For a full explanation of the
118 GNU C preprocessor, see the
123 .I The C Preprocessor\c
124 \&. Both of these are built from the same documentation source file, `\|\c
127 preprocessor provides a superset of the features of ANSI Standard C.
129 ANSI Standard C requires the rejection of many harmless constructs commonly
130 used by today's C programs. Such incompatibility would be inconvenient for
131 users, so the GNU C preprocessor is configured to accept these constructs
132 by default. Strictly speaking, to get ANSI Standard C, you must use the
140 practice the consequences of having strict ANSI Standard C make it
141 undesirable to do this.
143 Most often when you use the C preprocessor you will not have to invoke it
144 explicitly: the C compiler will do so automatically. However, the
145 preprocessor is sometimes useful individually.
147 The C preprocessor expects two file names as arguments, \c
152 \&. The preprocessor reads \c
154 \& together with any other
155 files it specifies with `\|\c
157 \&\|'. All the output generated by the
158 combined input files is written in \c
171 means to read from standard input and as \c
174 standard output. Also, if \c
176 \& or both file names are omitted,
177 the standard output and standard input are used for the omitted file names.
179 Here is a table of command options accepted by the C preprocessor.
180 These options can also be given when compiling a C program; they are
181 passed along automatically to the preprocessor when it is invoked by
185 Inhibit generation of `\|\c
187 \&\|'-lines with line-number information in
188 the output from the preprocessor. This might be
189 useful when running the preprocessor on something that is not C code
190 and will be sent to a program which might be confused by the
196 Do not discard comments: pass them through to the output file.
197 Comments appearing in arguments of a macro call will be copied to the
198 output before the expansion of the macro call.
201 Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
204 Process ANSI standard trigraph sequences. These are three-character
205 sequences, all starting with `\|\c
207 \&\|', that are defined by ANSI C to
208 stand for single characters. For example, `\|\c
215 \&\|' is a character constant for a newline.
216 Strictly speaking, the GNU C preprocessor does not support all
217 programs in ANSI Standard C unless `\|\c
219 \&\|' is used, but if
220 you ever notice the difference it will be with relief.
222 You don't want to know any more about trigraphs.
225 Issue warnings required by the ANSI C standard in certain cases such
226 as when text other than a comment follows `\|\c
232 .B \-pedantic\-errors
235 \&\|', except that errors are produced rather than
239 Warn if any trigraphs are encountered (assuming they are enabled).
244 Warn whenever a comment-start sequence `\|\c
246 \&\|' appears in a comment.
247 (Both forms have the same effect).
260 Warn about certain constructs that behave differently in traditional and
263 .BI "\-I " directory\c
267 \& to the end of the list of
268 directories to be searched for header files.
269 This can be used to override a system header file, substituting your
270 own version, since these directories are searched before the system
271 header file directories. If you use more than one `\|\c
274 the directories are scanned in left-to-right order; the standard
275 system directories come after.
278 Any directories specified with `\|\c
280 \&\|' options before the `\|\c
283 option are searched only for the case of `\|\c
288 they are not searched for `\|\c
294 If additional directories are specified with `\|\c
299 \&\|', these directories are searched for all `\|\c
304 In addition, the `\|\c
306 \&\|' option inhibits the use of the current
307 directory as the first search directory for `\|\c
312 Therefore, the current directory is searched only if it is requested
313 explicitly with `\|\c
315 \&\|'. Specifying both `\|\c
320 allows you to control precisely which directories are searched before
321 the current one and which are searched after.
324 Do not search the standard system directories for header files.
325 Only the directories you have specified with `\|\c
328 (and the current directory, if appropriate) are searched.
331 Do not search for header files in the C++ specific standard
332 directories, but do still search the other standard directories.
333 (This option is used when building libg++.)
339 \& as a macro, with definition `\|\c
343 .BI "\-D " "name" = definition
347 \& as a macro, with definition \c
350 There are no restrictions on the contents of \c
353 you are invoking the preprocessor from a shell or shell-like program
354 you may need to use the shell's quoting syntax to protect characters
355 such as spaces that have a meaning in the shell syntax. If you use more than
360 \&, the rightmost definition takes effect.
371 specified for one name, the `\|\c
373 \&\|' beats the `\|\c
379 Do not predefine any nonstandard macros.
381 .BI "\-A " "name(" value )
382 Assert (in the same way as the \c
389 \&. Remember to escape or quote the parentheses on
394 \&\|' to disable all predefined assertions; it also
395 undefines all predefined macros.
398 Instead of outputting the result of preprocessing, output a list of
401 \&\|' directives for all the macros defined during the
402 execution of the preprocessor, including predefined macros. This gives
403 you a way of finding out what is predefined in your version of the
404 preprocessor; assuming you have no file `\|\c
409 touch\ foo.h;\ cpp\ \-dM\ foo.h
412 will show the values of any predefined macros.
417 \&\|' except in two respects: it does \c
420 predefined macros, and it outputs \c
425 directives and the result of preprocessing. Both kinds of output go to
426 the standard output file.
430 Instead of outputting the result of preprocessing, output a rule
433 \& describing the dependencies of the main
434 source file. The preprocessor outputs one \c
437 the object file name for that source file, a colon, and the names of
438 all the included files. If there are many included files then the
439 rule is split into several lines using `\|\c
445 \&\|' says to treat missing header files as generated files and assume \c
446 they live in the same directory as the source file. It must be specified \c
451 This feature is used in automatic updating of makefiles.
456 \&\|' but mention only the files included with `\|\c
461 \&\|'. System header files included with `\|\c
471 \&\|' but the dependency information is written to `\|\c
473 \&\|'. This is in addition to compiling the file as
476 \&\|' does not inhibit ordinary compilation the way
481 When invoking gcc, do not specify the `\|\c
483 \&\|' argument. Gcc will create file names made by replacing `\|\c
487 \&\|' at the end of the input file names.
489 In Mach, you can use the utility \c
491 \& to merge multiple files
492 into a single dependency file suitable for using with the `\|\c
500 \&\|' except mention only user header files, not system
504 Print the name of each header file used, in addition to other normal
507 .BI "\-imacros " "file"\c
511 \& as input, discarding the resulting output, before
512 processing the regular input file. Because the output generated from
515 \& is discarded, the only effect of `\|\c
520 make the macros defined in \c
522 \& available for use in the main
523 input. The preprocessor evaluates any `\|\c
528 on the command line before processing `\|\c
534 .BI "\-include " "file"
537 as input, and include all the resulting output,
538 before processing the regular input file.
540 .BI "-idirafter " "dir"\c
544 \& to the second include path. The directories
545 on the second include path are searched when a header file is not found
546 in any of the directories in the main include path (the one that
551 .BI "-iprefix " "prefix"\c
555 \& as the prefix for subsequent `\|\c
560 .BI "-iwithprefix " "dir"\c
562 Add a directory to the second include path. The directory's name is
563 made by concatenating \c
570 was specified previously with `\|\c
581 Specify the source language. `\|\c
583 \&\|' makes the preprocessor
584 handle C++ comment syntax, and includes extra default include
585 directories for C++, and `\|\c
587 \&\|' enables the Objective C
590 \&\|' directive. `\|\c
592 \&\|' explicitly turns off both of
593 these extensions, and `\|\c
597 These options are generated by the compiler driver \c
600 passed from the `\|\c
605 Look for commands to the program checker \c
608 comments, and emit them preceded by `\|\c
612 .B /* NOTREACHED */\c
618 This option is available only when you call \c
623 \& will not pass it from its command line.
626 Forbid the use of `\|\c
628 \&\|' in identifiers. This was formerly required for strict conformance
629 to the C Standard before the standard was corrected. \c
631 This option is available only when you call \c
635 \& will not pass it from its command line.
641 .I The C Preprocessor\c
642 , Richard M. Stallman.
650 Using and Porting GNU CC (for version 2.0)\c
651 , Richard M. Stallman.
653 Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
655 Permission is granted to make and distribute verbatim copies of
656 this manual provided the copyright notice and this permission notice
657 are preserved on all copies.
659 Permission is granted to copy and distribute modified versions of this
660 manual under the conditions for verbatim copying, provided that the
661 entire resulting derived work is distributed under the terms of a
662 permission notice identical to this one.
664 Permission is granted to copy and distribute translations of this
665 manual into another language, under the above conditions for modified
666 versions, except that this permission notice may be included in
667 translations approved by the Free Software Foundation instead of in
668 the original English.