1156Srgrimes@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
250472Speter@c Free Software Foundation, Inc.
374462Salfred@c This is part of the CPP and GCC manuals.
4156Srgrimes@c For copying conditions, see the file gcc.texi.
574462Salfred
6156Srgrimes@c ---------------------------------------------------------------------
7156Srgrimes@c Options affecting the preprocessor
8156Srgrimes@c ---------------------------------------------------------------------
9156Srgrimes
10156Srgrimes@c If this file is included with the flag ``cppmanual'' set, it is
11156Srgrimes@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
12156Srgrimes
13156Srgrimes@table @gcctabopt
14156Srgrimes@item -D @var{name}
15156Srgrimes@opindex D
16156SrgrimesPredefine @var{name} as a macro, with definition @code{1}.
17156Srgrimes
18156Srgrimes@item -D @var{name}=@var{definition}
19156SrgrimesThe contents of @var{definition} are tokenized and processed as if
20156Srgrimesthey appeared during translation phase three in a @samp{#define}
21156Srgrimesdirective.  In particular, the definition will be truncated by
22156Srgrimesembedded newline characters.
23156Srgrimes
24156SrgrimesIf you are invoking the preprocessor from a shell or shell-like
25156Srgrimesprogram you may need to use the shell's quoting syntax to protect
26156Srgrimescharacters such as spaces that have a meaning in the shell syntax.
27156Srgrimes
28156SrgrimesIf you wish to define a function-like macro on the command line, write
2925815Sjkhits argument list with surrounding parentheses before the equals sign
30156Srgrimes(if any).  Parentheses are meaningful to most shells, so you will need
31156Srgrimesto quote the option.  With @command{sh} and @command{csh},
3274462Salfred@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
33156Srgrimes
34156Srgrimes@option{-D} and @option{-U} options are processed in the order they
35156Srgrimesare given on the command line.  All @option{-imacros @var{file}} and
3674462Salfred@option{-include @var{file}} options are processed after all
3774462Salfred@option{-D} and @option{-U} options.
3874462Salfred
3974462Salfred@item -U @var{name}
4074462Salfred@opindex U
4174462SalfredCancel any previous definition of @var{name}, either built in or
4274462Salfredprovided with a @option{-D} option.
4374462Salfred
4474462Salfred@item -undef
4574462Salfred@opindex undef
4674462SalfredDo not predefine any system-specific or GCC-specific macros.  The
4774462Salfredstandard predefined macros remain defined.
4874462Salfred@ifset cppmanual
4974462Salfred@xref{Standard Predefined Macros}.
5074462Salfred@end ifset
5174462Salfred
5274462Salfred@item -I @var{dir}
5374462Salfred@opindex I
5474462SalfredAdd the directory @var{dir} to the list of directories to be searched
5574462Salfredfor header files.
5674462Salfred@ifset cppmanual
5774462Salfred@xref{Search Path}.
5874462Salfred@end ifset
5974462SalfredDirectories named by @option{-I} are searched before the standard
6074462Salfredsystem include directories.  If the directory @var{dir} is a standard
6174462Salfredsystem include directory, the option is ignored to ensure that the
6274462Salfreddefault search order for system directories and the special treatment
6374462Salfredof system headers are not defeated
6474462Salfred@ifset cppmanual
6574462Salfred(@pxref{System Headers})
66460Srgrimes@end ifset
6715041Sjoerg.
68
69@item -o @var{file}
70@opindex o
71Write output to @var{file}.  This is the same as specifying @var{file}
72as the second non-option argument to @command{cpp}.  @command{gcc} has a
73different interpretation of a second non-option argument, so you must
74use @option{-o} to specify the output file.
75
76@item -Wall
77@opindex Wall
78Turns on all optional warnings which are desirable for normal code.
79At present this is @option{-Wcomment}, @option{-Wtrigraphs},
80@option{-Wmultichar} and a warning about integer promotion causing a
81change of sign in @code{#if} expressions.  Note that many of the
82preprocessor's warnings are on by default and have no options to
83control them.
84
85@item -Wcomment
86@itemx -Wcomments
87@opindex Wcomment
88@opindex Wcomments
89Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
90comment, or whenever a backslash-newline appears in a @samp{//} comment.
91(Both forms have the same effect.)
92
93@item -Wtrigraphs
94@opindex Wtrigraphs
95@anchor{Wtrigraphs}
96Most trigraphs in comments cannot affect the meaning of the program.
97However, a trigraph that would form an escaped newline (@samp{??/} at
98the end of a line) can, by changing where the comment begins or ends.
99Therefore, only trigraphs that would form escaped newlines produce
100warnings inside a comment.
101
102This option is implied by @option{-Wall}.  If @option{-Wall} is not
103given, this option is still enabled unless trigraphs are enabled.  To
104get trigraph conversion without warnings, but get the other
105@option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}.
106
107@item -Wtraditional
108@opindex Wtraditional
109Warn about certain constructs that behave differently in traditional and
110ISO C@.  Also warn about ISO C constructs that have no traditional C
111equivalent, and problematic constructs which should be avoided.
112@ifset cppmanual
113@xref{Traditional Mode}.
114@end ifset
115
116@item -Wimport
117@opindex Wimport
118Warn the first time @samp{#import} is used.
119
120@item -Wundef
121@opindex Wundef
122Warn whenever an identifier which is not a macro is encountered in an
123@samp{#if} directive, outside of @samp{defined}.  Such identifiers are
124replaced with zero.
125
126@item -Wunused-macros
127@opindex Wunused-macros
128Warn about macros defined in the main file that are unused.  A macro
129is @dfn{used} if it is expanded or tested for existence at least once.
130The preprocessor will also warn if the macro has not been used at the
131time it is redefined or undefined.
132
133Built-in macros, macros defined on the command line, and macros
134defined in include files are not warned about.
135
136@emph{Note:} If a macro is actually used, but only used in skipped
137conditional blocks, then CPP will report it as unused.  To avoid the
138warning in such a case, you might improve the scope of the macro's
139definition by, for example, moving it into the first skipped block.
140Alternatively, you could provide a dummy use with something like:
141
142@smallexample
143#if defined the_macro_causing_the_warning
144#endif
145@end smallexample
146
147@item -Wendif-labels
148@opindex Wendif-labels
149Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
150This usually happens in code of the form
151
152@smallexample
153#if FOO
154@dots{}
155#else FOO
156@dots{}
157#endif FOO
158@end smallexample
159
160@noindent
161The second and third @code{FOO} should be in comments, but often are not
162in older programs.  This warning is on by default.
163
164@item -Werror
165@opindex Werror
166Make all warnings into hard errors.  Source code which triggers warnings
167will be rejected.
168
169@item -Wsystem-headers
170@opindex Wsystem-headers
171Issue warnings for code in system headers.  These are normally unhelpful
172in finding bugs in your own code, therefore suppressed.  If you are
173responsible for the system library, you may want to see them.
174
175@item -w
176@opindex w
177Suppress all warnings, including those which GNU CPP issues by default.
178
179@item -pedantic
180@opindex pedantic
181Issue all the mandatory diagnostics listed in the C standard.  Some of
182them are left out by default, since they trigger frequently on harmless
183code.
184
185@item -pedantic-errors
186@opindex pedantic-errors
187Issue all the mandatory diagnostics, and make all mandatory diagnostics
188into errors.  This includes mandatory diagnostics that GCC issues
189without @samp{-pedantic} but treats as warnings.
190
191@item -M
192@opindex M
193@cindex make
194@cindex dependencies, make
195Instead of outputting the result of preprocessing, output a rule
196suitable for @command{make} describing the dependencies of the main
197source file.  The preprocessor outputs one @command{make} rule containing
198the object file name for that source file, a colon, and the names of all
199the included files, including those coming from @option{-include} or
200@option{-imacros} command line options.
201
202Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
203object file name consists of the basename of the source file with any
204suffix replaced with object file suffix.  If there are many included
205files then the rule is split into several lines using @samp{\}-newline.
206The rule has no commands.
207
208This option does not suppress the preprocessor's debug output, such as
209@option{-dM}.  To avoid mixing such debug output with the dependency
210rules you should explicitly specify the dependency output file with
211@option{-MF}, or use an environment variable like
212@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}).  Debug output
213will still be sent to the regular output stream as normal.
214
215Passing @option{-M} to the driver implies @option{-E}, and suppresses
216warnings with an implicit @option{-w}.
217
218@item -MM
219@opindex MM
220Like @option{-M} but do not mention header files that are found in
221system header directories, nor header files that are included,
222directly or indirectly, from such a header.
223
224This implies that the choice of angle brackets or double quotes in an
225@samp{#include} directive does not in itself determine whether that
226header will appear in @option{-MM} dependency output.  This is a
227slight change in semantics from GCC versions 3.0 and earlier.
228
229@anchor{dashMF}
230@item -MF @var{file}
231@opindex MF
232When used with @option{-M} or @option{-MM}, specifies a
233file to write the dependencies to.  If no @option{-MF} switch is given
234the preprocessor sends the rules to the same place it would have sent
235preprocessed output.
236
237When used with the driver options @option{-MD} or @option{-MMD},
238@option{-MF} overrides the default dependency output file.
239
240@item -MG
241@opindex MG
242In conjunction with an option such as @option{-M} requesting
243dependency generation, @option{-MG} assumes missing header files are
244generated files and adds them to the dependency list without raising
245an error.  The dependency filename is taken directly from the
246@code{#include} directive without prepending any path.  @option{-MG}
247also suppresses preprocessed output, as a missing header file renders
248this useless.
249
250This feature is used in automatic updating of makefiles.
251
252@item -MP
253@opindex MP
254This option instructs CPP to add a phony target for each dependency
255other than the main file, causing each to depend on nothing.  These
256dummy rules work around errors @command{make} gives if you remove header
257files without updating the @file{Makefile} to match.
258
259This is typical output:
260
261@smallexample
262test.o: test.c test.h
263
264test.h:
265@end smallexample
266
267@item -MT @var{target}
268@opindex MT
269
270Change the target of the rule emitted by dependency generation.  By
271default CPP takes the name of the main input file, including any path,
272deletes any file suffix such as @samp{.c}, and appends the platform's
273usual object suffix.  The result is the target.
274
275An @option{-MT} option will set the target to be exactly the string you
276specify.  If you want multiple targets, you can specify them as a single
277argument to @option{-MT}, or use multiple @option{-MT} options.
278
279For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
280
281@smallexample
282$(objpfx)foo.o: foo.c
283@end smallexample
284
285@item -MQ @var{target}
286@opindex MQ
287
288Same as @option{-MT}, but it quotes any characters which are special to
289Make.  @option{@w{-MQ '$(objpfx)foo.o'}} gives
290
291@smallexample
292$$(objpfx)foo.o: foo.c
293@end smallexample
294
295The default target is automatically quoted, as if it were given with
296@option{-MQ}.
297
298@item -MD
299@opindex MD
300@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
301@option{-E} is not implied.  The driver determines @var{file} based on
302whether an @option{-o} option is given.  If it is, the driver uses its
303argument but with a suffix of @file{.d}, otherwise it take the
304basename of the input file and applies a @file{.d} suffix.
305
306If @option{-MD} is used in conjunction with @option{-E}, any
307@option{-o} switch is understood to specify the dependency output file
308(@pxref{dashMF,,-MF}), but if used without @option{-E}, each @option{-o}
309is understood to specify a target object file.
310
311Since @option{-E} is not implied, @option{-MD} can be used to generate
312a dependency output file as a side-effect of the compilation process.
313
314@item -MMD
315@opindex MMD
316Like @option{-MD} except mention only user header files, not system
317header files.
318
319@ifclear cppmanual
320@item -fpch-deps
321@opindex fpch-deps
322When using precompiled headers (@pxref{Precompiled Headers}), this flag
323will cause the dependency-output flags to also list the files from the
324precompiled header's dependencies.  If not specified only the
325precompiled header would be listed and not the files that were used to
326create it because those files are not consulted when a precompiled
327header is used.
328
329@item -fpch-preprocess
330@opindex fpch-preprocess
331This option allows use of a precompiled header (@pxref{Precompiled
332Headers}) together with @option{-E}.  It inserts a special @code{#pragma},
333@code{#pragma GCC pch_preprocess "<filename>"} in the output to mark
334the place where the precompiled header was found, and its filename.  When
335@option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} and
336loads the PCH@.
337
338This option is off by default, because the resulting preprocessed output
339is only really suitable as input to GCC@.  It is switched on by
340@option{-save-temps}.
341
342You should not write this @code{#pragma} in your own code, but it is
343safe to edit the filename if the PCH file is available in a different
344location.  The filename may be absolute or it may be relative to GCC's
345current directory.
346
347@end ifclear
348@item -x c
349@itemx -x c++
350@itemx -x assembler-with-cpp
351@opindex x
352Specify the source language: C, C++, or assembly.  This has nothing to
353do with standards conformance or extensions; it merely selects which
354base syntax to expect.  If you give none of these options, cpp will
355deduce the language from the extension of the source file: @samp{.c},
356@samp{.cc}, or @samp{.S}.  Some other common extensions for C++ and
357assembly are also recognized.  If cpp does not recognize the extension,
358it will treat the file as C; this is the most generic mode.
359
360@emph{Note:} Previous versions of cpp accepted a @option{-lang} option
361which selected both the language and the standards conformance level.
362This option has been removed, because it conflicts with the @option{-l}
363option.
364
365@item -std=@var{standard}
366@itemx -ansi
367@opindex ansi
368@opindex std=
369Specify the standard to which the code should conform.  Currently CPP
370knows about C and C++ standards; others may be added in the future.
371
372@var{standard}
373may be one of:
374@table @code
375@item iso9899:1990
376@itemx c89
377The ISO C standard from 1990.  @samp{c89} is the customary shorthand for
378this version of the standard.
379
380The @option{-ansi} option is equivalent to @option{-std=c89}.
381
382@item iso9899:199409
383The 1990 C standard, as amended in 1994.
384
385@item iso9899:1999
386@itemx c99
387@itemx iso9899:199x
388@itemx c9x
389The revised ISO C standard, published in December 1999.  Before
390publication, this was known as C9X@.
391
392@item gnu89
393The 1990 C standard plus GNU extensions.  This is the default.
394
395@item gnu99
396@itemx gnu9x
397The 1999 C standard plus GNU extensions.
398
399@item c++98
400The 1998 ISO C++ standard plus amendments.
401
402@item gnu++98
403The same as @option{-std=c++98} plus GNU extensions.  This is the
404default for C++ code.
405@end table
406
407@item -I-
408@opindex I-
409Split the include path.  Any directories specified with @option{-I}
410options before @option{-I-} are searched only for headers requested with
411@code{@w{#include "@var{file}"}}; they are not searched for
412@code{@w{#include <@var{file}>}}.  If additional directories are
413specified with @option{-I} options after the @option{-I-}, those
414directories are searched for all @samp{#include} directives.
415
416In addition, @option{-I-} inhibits the use of the directory of the current
417file directory as the first search directory for @code{@w{#include
418"@var{file}"}}.
419@ifset cppmanual
420@xref{Search Path}.
421@end ifset
422This option has been deprecated.
423
424@item -nostdinc
425@opindex nostdinc
426Do not search the standard system directories for header files.
427Only the directories you have specified with @option{-I} options
428(and the directory of the current file, if appropriate) are searched.
429
430@item -nostdinc++
431@opindex nostdinc++
432Do not search for header files in the C++-specific standard directories,
433but do still search the other standard directories.  (This option is
434used when building the C++ library.)
435
436@item -include @var{file}
437@opindex include
438Process @var{file} as if @code{#include "file"} appeared as the first
439line of the primary source file.  However, the first directory searched
440for @var{file} is the preprocessor's working directory @emph{instead of}
441the directory containing the main source file.  If not found there, it
442is searched for in the remainder of the @code{#include "@dots{}"} search
443chain as normal.
444
445If multiple @option{-include} options are given, the files are included
446in the order they appear on the command line.
447
448@item -imacros @var{file}
449@opindex imacros
450Exactly like @option{-include}, except that any output produced by
451scanning @var{file} is thrown away.  Macros it defines remain defined.
452This allows you to acquire all the macros from a header without also
453processing its declarations.
454
455All files specified by @option{-imacros} are processed before all files
456specified by @option{-include}.
457
458@item -idirafter @var{dir}
459@opindex idirafter
460Search @var{dir} for header files, but do it @emph{after} all
461directories specified with @option{-I} and the standard system directories
462have been exhausted.  @var{dir} is treated as a system include directory.
463
464@item -iprefix @var{prefix}
465@opindex iprefix
466Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
467options.  If the prefix represents a directory, you should include the
468final @samp{/}.
469
470@item -iwithprefix @var{dir}
471@itemx -iwithprefixbefore @var{dir}
472@opindex iwithprefix
473@opindex iwithprefixbefore
474Append @var{dir} to the prefix specified previously with
475@option{-iprefix}, and add the resulting directory to the include search
476path.  @option{-iwithprefixbefore} puts it in the same place @option{-I}
477would; @option{-iwithprefix} puts it where @option{-idirafter} would.
478
479@item -isysroot @var{dir}
480@opindex isysroot
481This option is like the @option{--sysroot} option, but applies only to
482header files.  See the @option{--sysroot} option for more information.
483
484@item -imultilib @var{dir}
485@opindex imultilib
486Use @var{dir} as a subdirectory of the directory containing
487target-specific C++ headers.
488
489@item -isystem @var{dir}
490@opindex isystem
491Search @var{dir} for header files, after all directories specified by
492@option{-I} but before the standard system directories.  Mark it
493as a system directory, so that it gets the same special treatment as
494is applied to the standard system directories.
495@ifset cppmanual
496@xref{System Headers}.
497@end ifset
498
499@item -iquote @var{dir}
500@opindex iquote
501Search @var{dir} only for header files requested with
502@code{@w{#include "@var{file}"}}; they are not searched for
503@code{@w{#include <@var{file}>}}, before all directories specified by
504@option{-I} and before the standard system directories.
505@ifset cppmanual
506@xref{Search Path}.
507@end ifset
508
509@item -fdirectives-only
510@opindex fdirectives-only
511This option provides a simplified preprocessor to improve the
512performance of distributed build systems such as distcc.  It's
513behavior depends on a number of other flags.
514
515If the @option{-E} option is enabled, it suppresses things like macro
516expansion, trigraph conversion, and escaped newline splicing
517outside of directives.  All directives are processed normally, except that
518macro definitions are output similar to the @option{-dD} option.
519
520If the @option{-fpreprocessed} option is enabled, it suppresses
521predefinition of most builtin and command line macros.  This
522prevents duplicate definition of macros output with the @option{-E}
523option.
524
525@item -fdollars-in-identifiers
526@opindex fdollars-in-identifiers
527@anchor{fdollars-in-identifiers}
528Accept @samp{$} in identifiers.
529@ifset cppmanual
530  @xref{Identifier characters}.
531@end ifset
532
533@item -fextended-identifiers
534@opindex fextended-identifiers
535Accept universal character names in identifiers.  This option is
536experimental; in a future version of GCC, it will be enabled by
537default for C99 and C++.
538
539@item -fpreprocessed
540@opindex fpreprocessed
541Indicate to the preprocessor that the input file has already been
542preprocessed.  This suppresses things like macro expansion, trigraph
543conversion, escaped newline splicing, and processing of most directives.
544The preprocessor still recognizes and removes comments, so that you can
545pass a file preprocessed with @option{-C} to the compiler without
546problems.  In this mode the integrated preprocessor is little more than
547a tokenizer for the front ends.
548
549@option{-fpreprocessed} is implicit if the input file has one of the
550extensions @samp{.i}, @samp{.ii} or @samp{.mi}.  These are the
551extensions that GCC uses for preprocessed files created by
552@option{-save-temps}.
553
554@item -ftabstop=@var{width}
555@opindex ftabstop
556Set the distance between tab stops.  This helps the preprocessor report
557correct column numbers in warnings or errors, even if tabs appear on the
558line.  If the value is less than 1 or greater than 100, the option is
559ignored.  The default is 8.
560
561@item -fexec-charset=@var{charset}
562@opindex fexec-charset
563@cindex character set, execution
564Set the execution character set, used for string and character
565constants.  The default is UTF-8.  @var{charset} can be any encoding
566supported by the system's @code{iconv} library routine.
567
568@item -fwide-exec-charset=@var{charset}
569@opindex fwide-exec-charset
570@cindex character set, wide execution
571Set the wide execution character set, used for wide string and
572character constants.  The default is UTF-32 or UTF-16, whichever
573corresponds to the width of @code{wchar_t}.  As with
574@option{-fexec-charset}, @var{charset} can be any encoding supported
575by the system's @code{iconv} library routine; however, you will have
576problems with encodings that do not fit exactly in @code{wchar_t}.
577
578@item -finput-charset=@var{charset}
579@opindex finput-charset
580@cindex character set, input
581Set the input character set, used for translation from the character
582set of the input file to the source character set used by GCC@.  If the
583locale does not specify, or GCC cannot get this information from the
584locale, the default is UTF-8.  This can be overridden by either the locale
585or this command line option.  Currently the command line option takes
586precedence if there's a conflict.  @var{charset} can be any encoding
587supported by the system's @code{iconv} library routine.
588
589@item -fworking-directory
590@opindex fworking-directory
591@opindex fno-working-directory
592Enable generation of linemarkers in the preprocessor output that will
593let the compiler know the current working directory at the time of
594preprocessing.  When this option is enabled, the preprocessor will
595emit, after the initial linemarker, a second linemarker with the
596current working directory followed by two slashes.  GCC will use this
597directory, when it's present in the preprocessed input, as the
598directory emitted as the current working directory in some debugging
599information formats.  This option is implicitly enabled if debugging
600information is enabled, but this can be inhibited with the negated
601form @option{-fno-working-directory}.  If the @option{-P} flag is
602present in the command line, this option has no effect, since no
603@code{#line} directives are emitted whatsoever.
604
605@item -fno-show-column
606@opindex fno-show-column
607Do not print column numbers in diagnostics.  This may be necessary if
608diagnostics are being scanned by a program that does not understand the
609column numbers, such as @command{dejagnu}.
610
611@item -A @var{predicate}=@var{answer}
612@opindex A
613Make an assertion with the predicate @var{predicate} and answer
614@var{answer}.  This form is preferred to the older form @option{-A
615@var{predicate}(@var{answer})}, which is still supported, because
616it does not use shell special characters.
617@ifset cppmanual
618@xref{Assertions}.
619@end ifset
620
621@item -A -@var{predicate}=@var{answer}
622Cancel an assertion with the predicate @var{predicate} and answer
623@var{answer}.
624
625@item -dCHARS
626@var{CHARS} is a sequence of one or more of the following characters,
627and must not be preceded by a space.  Other characters are interpreted
628by the compiler proper, or reserved for future versions of GCC, and so
629are silently ignored.  If you specify characters whose behavior
630conflicts, the result is undefined.
631
632@table @samp
633@item M
634@opindex dM
635Instead of the normal output, generate a list of @samp{#define}
636directives for all the macros defined during the execution of the
637preprocessor, including predefined macros.  This gives you a way of
638finding out what is predefined in your version of the preprocessor.
639Assuming you have no file @file{foo.h}, the command
640
641@smallexample
642touch foo.h; cpp -dM foo.h
643@end smallexample
644
645@noindent
646will show all the predefined macros.
647
648If you use @option{-dM} without the @option{-E} option, @option{-dM} is
649interpreted as a synonym for @option{-fdump-rtl-mach}.
650@xref{Debugging Options, , ,gcc}.
651
652@item D
653@opindex dD
654Like @samp{M} except in two respects: it does @emph{not} include the
655predefined macros, and it outputs @emph{both} the @samp{#define}
656directives and the result of preprocessing.  Both kinds of output go to
657the standard output file.
658
659@item N
660@opindex dN
661Like @samp{D}, but emit only the macro names, not their expansions.
662
663@item I
664@opindex dI
665Output @samp{#include} directives in addition to the result of
666preprocessing.
667@end table
668
669@item -P
670@opindex P
671Inhibit generation of linemarkers in the output from the preprocessor.
672This might be useful when running the preprocessor on something that is
673not C code, and will be sent to a program which might be confused by the
674linemarkers.
675@ifset cppmanual
676@xref{Preprocessor Output}.
677@end ifset
678
679@item -C
680@opindex C
681Do not discard comments.  All comments are passed through to the output
682file, except for comments in processed directives, which are deleted
683along with the directive.
684
685You should be prepared for side effects when using @option{-C}; it
686causes the preprocessor to treat comments as tokens in their own right.
687For example, comments appearing at the start of what would be a
688directive line have the effect of turning that line into an ordinary
689source line, since the first token on the line is no longer a @samp{#}.
690
691@item -CC
692Do not discard comments, including during macro expansion.  This is
693like @option{-C}, except that comments contained within macros are
694also passed through to the output file where the macro is expanded.
695
696In addition to the side-effects of the @option{-C} option, the
697@option{-CC} option causes all C++-style comments inside a macro
698to be converted to C-style comments.  This is to prevent later use
699of that macro from inadvertently commenting out the remainder of
700the source line.
701
702The @option{-CC} option is generally used to support lint comments.
703
704@item -traditional-cpp
705@opindex traditional-cpp
706Try to imitate the behavior of old-fashioned C preprocessors, as
707opposed to ISO C preprocessors.
708@ifset cppmanual
709@xref{Traditional Mode}.
710@end ifset
711
712@item -trigraphs
713@opindex trigraphs
714Process trigraph sequences.
715@ifset cppmanual
716@xref{Initial processing}.
717@end ifset
718@ifclear cppmanual
719These are three-character sequences, all starting with @samp{??}, that
720are defined by ISO C to stand for single characters.  For example,
721@samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character
722constant for a newline.  By default, GCC ignores trigraphs, but in
723standard-conforming modes it converts them.  See the @option{-std} and
724@option{-ansi} options.
725
726The nine trigraphs and their replacements are
727
728@smallexample
729Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
730Replacement:      [    ]    @{    @}    #    \    ^    |    ~
731@end smallexample
732@end ifclear
733
734@item -remap
735@opindex remap
736Enable special code to work around file systems which only permit very
737short file names, such as MS-DOS@.
738
739@itemx --help
740@itemx --target-help
741@opindex help
742@opindex target-help
743Print text describing all the command line options instead of
744preprocessing anything.
745
746@item -v
747@opindex v
748Verbose mode.  Print out GNU CPP's version number at the beginning of
749execution, and report the final form of the include path.
750
751@item -H
752@opindex H
753Print the name of each header file used, in addition to other normal
754activities.  Each name is indented to show how deep in the
755@samp{#include} stack it is.  Precompiled header files are also
756printed, even if they are found to be invalid; an invalid precompiled
757header file is printed with @samp{...x} and a valid one with @samp{...!} .
758
759@item -version
760@itemx --version
761@opindex version
762Print out GNU CPP's version number.  With one dash, proceed to
763preprocess as normal.  With two dashes, exit immediately.
764@end table
765