1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
62 . tm Index:\\$1\t\\n%\t"\\$2"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89 . \" simple accents for nroff and troff
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
133 .\" ========================================================================
136 .TH CPP 1 "2019-02-22" "gcc-8.3.0" "GNU"
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
142 cpp \- The C Preprocessor
144 .IX Header "SYNOPSIS"
145 cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR]
146 [\fB\-I\fR\fIdir\fR...] [\fB\-iquote\fR\fIdir\fR...]
147 [\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR]
148 [\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...]
149 [\fB\-MT\fR \fItarget\fR...]
150 \fIinfile\fR [[\fB\-o\fR] \fIoutfile\fR]
152 Only the most useful options are given above; see below for a more
153 complete list of preprocessor-specific options.
154 In addition, \fBcpp\fR accepts most \fBgcc\fR driver options, which
155 are not listed here. Refer to the \s-1GCC\s0 documentation for details.
157 .IX Header "DESCRIPTION"
158 The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR
159 that is used automatically by the C compiler to transform your program
160 before compilation. It is called a macro processor because it allows
161 you to define \fImacros\fR, which are brief abbreviations for longer
164 The C preprocessor is intended to be used only with C, \*(C+, and
165 Objective-C source code. In the past, it has been abused as a general
166 text processor. It will choke on input which does not obey C's lexical
167 rules. For example, apostrophes will be interpreted as the beginning of
168 character constants, and cause errors. Also, you cannot rely on it
169 preserving characteristics of the input which are not significant to
170 C\-family languages. If a Makefile is preprocessed, all the hard tabs
171 will be removed, and the Makefile will not work.
173 Having said that, you can often get away with using cpp on things which
174 are not C. Other Algol-ish programming languages are often safe
175 (Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR
176 mode preserves more white space, and is otherwise more permissive. Many
177 of the problems can be avoided by writing C or \*(C+ style comments
178 instead of native language comments, and keeping macros simple.
180 Wherever possible, you should use a preprocessor geared to the language
181 you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro
182 facilities. Most high level programming languages have their own
183 conditional compilation and inclusion mechanism. If all else fails,
184 try a true general text processor, such as \s-1GNU M4.\s0
186 C preprocessors vary in some details. This manual discusses the \s-1GNU C\s0
187 preprocessor, which provides a small superset of the features of \s-1ISO\s0
188 Standard C. In its default mode, the \s-1GNU C\s0 preprocessor does not do a
189 few things required by the standard. These are features which are
190 rarely, if ever, used, and may cause surprising changes to the meaning
191 of a program which does not expect them. To get strict \s-1ISO\s0 Standard C,
192 you should use the \fB\-std=c90\fR, \fB\-std=c99\fR,
193 \&\fB\-std=c11\fR or \fB\-std=c17\fR options, depending
194 on which version of the standard you want. To get all the mandatory
195 diagnostics, you must also use \fB\-pedantic\fR.
197 This manual describes the behavior of the \s-1ISO\s0 preprocessor. To
198 minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's
199 behavior does not conflict with traditional semantics, the
200 traditional preprocessor should behave the same way. The various
201 differences that do exist are detailed in the section \fBTraditional
204 For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this
205 manual refer to \s-1GNU CPP.\s0
208 The \fBcpp\fR command expects two file names as arguments, \fIinfile\fR and
209 \&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any
210 other files it specifies with \fB#include\fR. All the output generated
211 by the combined input files is written in \fIoutfile\fR.
213 Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as
214 \&\fIinfile\fR means to read from standard input and as \fIoutfile\fR
215 means to write to standard output. If either file is omitted, it
216 means the same as if \fB\-\fR had been specified for that file.
217 You can also use the \fB\-o\fR \fIoutfile\fR option to specify the
220 Unless otherwise noted, or the option ends in \fB=\fR, all options
221 which take an argument may have that argument appear either immediately
222 after the option, or with a space between option and argument:
223 \&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect.
225 Many options have multi-letter names; therefore multiple single-letter
226 options may \fInot\fR be grouped: \fB\-dM\fR is very different from
228 .IP "\fB\-D\fR \fIname\fR" 4
230 Predefine \fIname\fR as a macro, with definition \f(CW1\fR.
231 .IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
232 .IX Item "-D name=definition"
233 The contents of \fIdefinition\fR are tokenized and processed as if
234 they appeared during translation phase three in a \fB#define\fR
235 directive. In particular, the definition is truncated by
236 embedded newline characters.
238 If you are invoking the preprocessor from a shell or shell-like
239 program you may need to use the shell's quoting syntax to protect
240 characters such as spaces that have a meaning in the shell syntax.
242 If you wish to define a function-like macro on the command line, write
243 its argument list with surrounding parentheses before the equals sign
244 (if any). Parentheses are meaningful to most shells, so you should
245 quote the option. With \fBsh\fR and \fBcsh\fR,
246 \&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works.
248 \&\fB\-D\fR and \fB\-U\fR options are processed in the order they
249 are given on the command line. All \fB\-imacros\fR \fIfile\fR and
250 \&\fB\-include\fR \fIfile\fR options are processed after all
251 \&\fB\-D\fR and \fB\-U\fR options.
252 .IP "\fB\-U\fR \fIname\fR" 4
254 Cancel any previous definition of \fIname\fR, either built in or
255 provided with a \fB\-D\fR option.
256 .IP "\fB\-include\fR \fIfile\fR" 4
257 .IX Item "-include file"
258 Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first
259 line of the primary source file. However, the first directory searched
260 for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR
261 the directory containing the main source file. If not found there, it
262 is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search
265 If multiple \fB\-include\fR options are given, the files are included
266 in the order they appear on the command line.
267 .IP "\fB\-imacros\fR \fIfile\fR" 4
268 .IX Item "-imacros file"
269 Exactly like \fB\-include\fR, except that any output produced by
270 scanning \fIfile\fR is thrown away. Macros it defines remain defined.
271 This allows you to acquire all the macros from a header without also
272 processing its declarations.
274 All files specified by \fB\-imacros\fR are processed before all files
275 specified by \fB\-include\fR.
276 .IP "\fB\-undef\fR" 4
278 Do not predefine any system-specific or GCC-specific macros. The
279 standard predefined macros remain defined.
280 .IP "\fB\-pthread\fR" 4
282 Define additional macros required for using the \s-1POSIX\s0 threads library.
283 You should use this option consistently for both compilation and linking.
284 This option is supported on GNU/Linux targets, most other Unix derivatives,
285 and also on x86 Cygwin and MinGW targets.
288 Instead of outputting the result of preprocessing, output a rule
289 suitable for \fBmake\fR describing the dependencies of the main
290 source file. The preprocessor outputs one \fBmake\fR rule containing
291 the object file name for that source file, a colon, and the names of all
292 the included files, including those coming from \fB\-include\fR or
293 \&\fB\-imacros\fR command-line options.
295 Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the
296 object file name consists of the name of the source file with any
297 suffix replaced with object file suffix and with any leading directory
298 parts removed. If there are many included files then the rule is
299 split into several lines using \fB\e\fR\-newline. The rule has no
302 This option does not suppress the preprocessor's debug output, such as
303 \&\fB\-dM\fR. To avoid mixing such debug output with the dependency
304 rules you should explicitly specify the dependency output file with
305 \&\fB\-MF\fR, or use an environment variable like
306 \&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output
307 is still sent to the regular output stream as normal.
309 Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses
310 warnings with an implicit \fB\-w\fR.
313 Like \fB\-M\fR but do not mention header files that are found in
314 system header directories, nor header files that are included,
315 directly or indirectly, from such a header.
317 This implies that the choice of angle brackets or double quotes in an
318 \&\fB#include\fR directive does not in itself determine whether that
319 header appears in \fB\-MM\fR dependency output.
320 .IP "\fB\-MF\fR \fIfile\fR" 4
322 When used with \fB\-M\fR or \fB\-MM\fR, specifies a
323 file to write the dependencies to. If no \fB\-MF\fR switch is given
324 the preprocessor sends the rules to the same place it would send
327 When used with the driver options \fB\-MD\fR or \fB\-MMD\fR,
328 \&\fB\-MF\fR overrides the default dependency output file.
330 If \fIfile\fR is \fI\-\fR, then the dependencies are written to \fIstdout\fR.
333 In conjunction with an option such as \fB\-M\fR requesting
334 dependency generation, \fB\-MG\fR assumes missing header files are
335 generated files and adds them to the dependency list without raising
336 an error. The dependency filename is taken directly from the
337 \&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR
338 also suppresses preprocessed output, as a missing header file renders
341 This feature is used in automatic updating of makefiles.
344 This option instructs \s-1CPP\s0 to add a phony target for each dependency
345 other than the main file, causing each to depend on nothing. These
346 dummy rules work around errors \fBmake\fR gives if you remove header
347 files without updating the \fIMakefile\fR to match.
349 This is typical output:
352 \& test.o: test.c test.h
356 .IP "\fB\-MT\fR \fItarget\fR" 4
357 .IX Item "-MT target"
358 Change the target of the rule emitted by dependency generation. By
359 default \s-1CPP\s0 takes the name of the main input file, deletes any
360 directory components and any file suffix such as \fB.c\fR, and
361 appends the platform's usual object suffix. The result is the target.
363 An \fB\-MT\fR option sets the target to be exactly the string you
364 specify. If you want multiple targets, you can specify them as a single
365 argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options.
367 For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give
370 \& $(objpfx)foo.o: foo.c
372 .IP "\fB\-MQ\fR \fItarget\fR" 4
373 .IX Item "-MQ target"
374 Same as \fB\-MT\fR, but it quotes any characters which are special to
375 Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives
378 \& $$(objpfx)foo.o: foo.c
381 The default target is automatically quoted, as if it were given with
385 \&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that
386 \&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on
387 whether an \fB\-o\fR option is given. If it is, the driver uses its
388 argument but with a suffix of \fI.d\fR, otherwise it takes the name
389 of the input file, removes any directory components and suffix, and
390 applies a \fI.d\fR suffix.
392 If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any
393 \&\fB\-o\fR switch is understood to specify the dependency output file, but if used without \fB\-E\fR, each \fB\-o\fR
394 is understood to specify a target object file.
396 Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate
397 a dependency output file as a side effect of the compilation process.
400 Like \fB\-MD\fR except mention only user header files, not system
402 .IP "\fB\-fpreprocessed\fR" 4
403 .IX Item "-fpreprocessed"
404 Indicate to the preprocessor that the input file has already been
405 preprocessed. This suppresses things like macro expansion, trigraph
406 conversion, escaped newline splicing, and processing of most directives.
407 The preprocessor still recognizes and removes comments, so that you can
408 pass a file preprocessed with \fB\-C\fR to the compiler without
409 problems. In this mode the integrated preprocessor is little more than
410 a tokenizer for the front ends.
412 \&\fB\-fpreprocessed\fR is implicit if the input file has one of the
413 extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the
414 extensions that \s-1GCC\s0 uses for preprocessed files created by
415 \&\fB\-save\-temps\fR.
416 .IP "\fB\-fdirectives\-only\fR" 4
417 .IX Item "-fdirectives-only"
418 When preprocessing, handle directives, but do not expand macros.
420 The option's behavior depends on the \fB\-E\fR and \fB\-fpreprocessed\fR
423 With \fB\-E\fR, preprocessing is limited to the handling of directives
424 such as \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`#ifdef\*(C'\fR, and \f(CW\*(C`#error\*(C'\fR. Other
425 preprocessor operations, such as macro expansion and trigraph
426 conversion are not performed. In addition, the \fB\-dD\fR option is
429 With \fB\-fpreprocessed\fR, predefinition of command line and most
430 builtin macros is disabled. Macros such as \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, which are
431 contextually dependent, are handled normally. This enables compilation of
432 files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR.
434 With both \fB\-E\fR and \fB\-fpreprocessed\fR, the rules for
435 \&\fB\-fpreprocessed\fR take precedence. This enables full preprocessing of
436 files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR.
437 .IP "\fB\-fdollars\-in\-identifiers\fR" 4
438 .IX Item "-fdollars-in-identifiers"
439 Accept \fB$\fR in identifiers.
440 .IP "\fB\-fextended\-identifiers\fR" 4
441 .IX Item "-fextended-identifiers"
442 Accept universal character names in identifiers. This option is
443 enabled by default for C99 (and later C standard versions) and \*(C+.
444 .IP "\fB\-fno\-canonical\-system\-headers\fR" 4
445 .IX Item "-fno-canonical-system-headers"
446 When preprocessing, do not shorten system header paths with canonicalization.
447 .IP "\fB\-ftabstop=\fR\fIwidth\fR" 4
448 .IX Item "-ftabstop=width"
449 Set the distance between tab stops. This helps the preprocessor report
450 correct column numbers in warnings or errors, even if tabs appear on the
451 line. If the value is less than 1 or greater than 100, the option is
452 ignored. The default is 8.
453 .IP "\fB\-ftrack\-macro\-expansion\fR[\fB=\fR\fIlevel\fR]" 4
454 .IX Item "-ftrack-macro-expansion[=level]"
455 Track locations of tokens across macro expansions. This allows the
456 compiler to emit diagnostic about the current macro expansion stack
457 when a compilation error occurs in a macro expansion. Using this
458 option makes the preprocessor and the compiler consume more
459 memory. The \fIlevel\fR parameter can be used to choose the level of
460 precision of token location tracking thus decreasing the memory
461 consumption if necessary. Value \fB0\fR of \fIlevel\fR de-activates
462 this option. Value \fB1\fR tracks tokens locations in a
463 degraded mode for the sake of minimal memory overhead. In this mode
464 all tokens resulting from the expansion of an argument of a
465 function-like macro have the same location. Value \fB2\fR tracks
466 tokens locations completely. This value is the most memory hungry.
467 When this option is given no argument, the default parameter value is
470 Note that \f(CW\*(C`\-ftrack\-macro\-expansion=2\*(C'\fR is activated by default.
471 .IP "\fB\-fmacro\-prefix\-map=\fR\fIold\fR\fB=\fR\fInew\fR" 4
472 .IX Item "-fmacro-prefix-map=old=new"
473 When preprocessing files residing in directory \fI\fIold\fI\fR,
474 expand the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_BASE_FILE_\|_\*(C'\fR macros as if the
475 files resided in directory \fI\fInew\fI\fR instead. This can be used
476 to change an absolute path to a relative path by using \fI.\fR for
477 \&\fInew\fR which can result in more reproducible builds that are
478 location independent. This option also affects
479 \&\f(CW\*(C`_\|_builtin_FILE()\*(C'\fR during compilation. See also
480 \&\fB\-ffile\-prefix\-map\fR.
481 .IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4
482 .IX Item "-fexec-charset=charset"
483 Set the execution character set, used for string and character
484 constants. The default is \s-1UTF\-8.\s0 \fIcharset\fR can be any encoding
485 supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
486 .IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4
487 .IX Item "-fwide-exec-charset=charset"
488 Set the wide execution character set, used for wide string and
489 character constants. The default is \s-1UTF\-32\s0 or \s-1UTF\-16,\s0 whichever
490 corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR. As with
491 \&\fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported
492 by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have
493 problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR.
494 .IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4
495 .IX Item "-finput-charset=charset"
496 Set the input character set, used for translation from the character
497 set of the input file to the source character set used by \s-1GCC.\s0 If the
498 locale does not specify, or \s-1GCC\s0 cannot get this information from the
499 locale, the default is \s-1UTF\-8.\s0 This can be overridden by either the locale
500 or this command-line option. Currently the command-line option takes
501 precedence if there's a conflict. \fIcharset\fR can be any encoding
502 supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
503 .IP "\fB\-fworking\-directory\fR" 4
504 .IX Item "-fworking-directory"
505 Enable generation of linemarkers in the preprocessor output that
506 let the compiler know the current working directory at the time of
507 preprocessing. When this option is enabled, the preprocessor
508 emits, after the initial linemarker, a second linemarker with the
509 current working directory followed by two slashes. \s-1GCC\s0 uses this
510 directory, when it's present in the preprocessed input, as the
511 directory emitted as the current working directory in some debugging
512 information formats. This option is implicitly enabled if debugging
513 information is enabled, but this can be inhibited with the negated
514 form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is
515 present in the command line, this option has no effect, since no
516 \&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever.
517 .IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
518 .IX Item "-A predicate=answer"
519 Make an assertion with the predicate \fIpredicate\fR and answer
520 \&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR
521 \&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because
522 it does not use shell special characters.
523 .IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
524 .IX Item "-A -predicate=answer"
525 Cancel an assertion with the predicate \fIpredicate\fR and answer
529 Do not discard comments. All comments are passed through to the output
530 file, except for comments in processed directives, which are deleted
531 along with the directive.
533 You should be prepared for side effects when using \fB\-C\fR; it
534 causes the preprocessor to treat comments as tokens in their own right.
535 For example, comments appearing at the start of what would be a
536 directive line have the effect of turning that line into an ordinary
537 source line, since the first token on the line is no longer a \fB#\fR.
540 Do not discard comments, including during macro expansion. This is
541 like \fB\-C\fR, except that comments contained within macros are
542 also passed through to the output file where the macro is expanded.
544 In addition to the side effects of the \fB\-C\fR option, the
545 \&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro
546 to be converted to C\-style comments. This is to prevent later use
547 of that macro from inadvertently commenting out the remainder of
550 The \fB\-CC\fR option is generally used to support lint comments.
553 Inhibit generation of linemarkers in the output from the preprocessor.
554 This might be useful when running the preprocessor on something that is
555 not C code, and will be sent to a program which might be confused by the
557 .IP "\fB\-traditional\fR" 4
558 .IX Item "-traditional"
560 .IP "\fB\-traditional\-cpp\fR" 4
561 .IX Item "-traditional-cpp"
563 Try to imitate the behavior of pre-standard C preprocessors, as
564 opposed to \s-1ISO C\s0 preprocessors.
566 Note that \s-1GCC\s0 does not otherwise attempt to emulate a pre-standard
567 C compiler, and these options are only supported with the \fB\-E\fR
568 switch, or when invoking \s-1CPP\s0 explicitly.
569 .IP "\fB\-trigraphs\fR" 4
570 .IX Item "-trigraphs"
571 Support \s-1ISO C\s0 trigraphs.
572 These are three-character sequences, all starting with \fB??\fR, that
573 are defined by \s-1ISO C\s0 to stand for single characters. For example,
574 \&\fB??/\fR stands for \fB\e\fR, so \fB'??/n'\fR is a character
575 constant for a newline.
577 By default, \s-1GCC\s0 ignores trigraphs, but in
578 standard-conforming modes it converts them. See the \fB\-std\fR and
579 \&\fB\-ansi\fR options.
580 .IP "\fB\-remap\fR" 4
582 Enable special code to work around file systems which only permit very
583 short file names, such as MS-DOS.
586 Print the name of each header file used, in addition to other normal
587 activities. Each name is indented to show how deep in the
588 \&\fB#include\fR stack it is. Precompiled header files are also
589 printed, even if they are found to be invalid; an invalid precompiled
590 header file is printed with \fB...x\fR and a valid one with \fB...!\fR .
591 .IP "\fB\-d\fR\fIletters\fR" 4
593 Says to make debugging dumps during compilation as specified by
594 \&\fIletters\fR. The flags documented here are those relevant to the
595 preprocessor. Other \fIletters\fR are interpreted
596 by the compiler proper, or reserved for future versions of \s-1GCC,\s0 and so
597 are silently ignored. If you specify \fIletters\fR whose behavior
598 conflicts, the result is undefined.
602 Instead of the normal output, generate a list of \fB#define\fR
603 directives for all the macros defined during the execution of the
604 preprocessor, including predefined macros. This gives you a way of
605 finding out what is predefined in your version of the preprocessor.
606 Assuming you have no file \fIfoo.h\fR, the command
609 \& touch foo.h; cpp \-dM foo.h
612 shows all the predefined macros.
615 Like \fB\-dM\fR except in two respects: it does \fInot\fR include the
616 predefined macros, and it outputs \fIboth\fR the \fB#define\fR
617 directives and the result of preprocessing. Both kinds of output go to
618 the standard output file.
621 Like \fB\-dD\fR, but emit only the macro names, not their expansions.
624 Output \fB#include\fR directives in addition to the result of
628 Like \fB\-dD\fR except that only macros that are expanded, or whose
629 definedness is tested in preprocessor directives, are output; the
630 output is delayed until the use or test of the macro; and
631 \&\fB#undef\fR directives are also output for macros tested but
632 undefined at the time.
636 .IP "\fB\-fdebug\-cpp\fR" 4
637 .IX Item "-fdebug-cpp"
638 This option is only useful for debugging \s-1GCC.\s0 When used from \s-1CPP\s0 or with
639 \&\fB\-E\fR, it dumps debugging information about location maps. Every
640 token in the output is preceded by the dump of the map its location
643 When used from \s-1GCC\s0 without \fB\-E\fR, this option has no effect.
644 .IP "\fB\-I\fR \fIdir\fR" 4
647 .IP "\fB\-iquote\fR \fIdir\fR" 4
648 .IX Item "-iquote dir"
649 .IP "\fB\-isystem\fR \fIdir\fR" 4
650 .IX Item "-isystem dir"
651 .IP "\fB\-idirafter\fR \fIdir\fR" 4
652 .IX Item "-idirafter dir"
654 Add the directory \fIdir\fR to the list of directories to be searched
655 for header files during preprocessing.
657 If \fIdir\fR begins with \fB=\fR or \f(CW$SYSROOT\fR, then the \fB=\fR
658 or \f(CW$SYSROOT\fR is replaced by the sysroot prefix; see
659 \&\fB\-\-sysroot\fR and \fB\-isysroot\fR.
661 Directories specified with \fB\-iquote\fR apply only to the quote
662 form of the directive, \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR.
663 Directories specified with \fB\-I\fR, \fB\-isystem\fR,
664 or \fB\-idirafter\fR apply to lookup for both the
665 \&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR and
666 \&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR directives.
668 You can specify any number or combination of these options on the
669 command line to search for header files in several directories.
670 The lookup order is as follows:
674 For the quote form of the include directive, the directory of the current
675 file is searched first.
678 For the quote form of the include directive, the directories specified
679 by \fB\-iquote\fR options are searched in left-to-right order,
680 as they appear on the command line.
683 Directories specified with \fB\-I\fR options are scanned in
687 Directories specified with \fB\-isystem\fR options are scanned in
691 Standard system directories are scanned.
694 Directories specified with \fB\-idirafter\fR options are scanned in
699 You can use \fB\-I\fR to override a system header
700 file, substituting your own version, since these directories are
701 searched before the standard system header file directories.
703 not use this option to add directories that contain vendor-supplied
704 system header files; use \fB\-isystem\fR for that.
706 The \fB\-isystem\fR and \fB\-idirafter\fR options also mark the directory
707 as a system directory, so that it gets the same special treatment that
708 is applied to the standard system directories.
710 If a standard system include directory, or a directory specified with
711 \&\fB\-isystem\fR, is also specified with \fB\-I\fR, the \fB\-I\fR
712 option is ignored. The directory is still searched but as a
713 system directory at its normal position in the system include chain.
714 This is to ensure that \s-1GCC\s0's procedure to fix buggy system headers and
715 the ordering for the \f(CW\*(C`#include_next\*(C'\fR directive are not inadvertently
717 If you really need to change the search order for system directories,
718 use the \fB\-nostdinc\fR and/or \fB\-isystem\fR options.
722 Split the include path.
723 This option has been deprecated. Please use \fB\-iquote\fR instead for
724 \&\fB\-I\fR directories before the \fB\-I\-\fR and remove the \fB\-I\-\fR
727 Any directories specified with \fB\-I\fR
728 options before \fB\-I\-\fR are searched only for headers requested with
729 \&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for
730 \&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are
731 specified with \fB\-I\fR options after the \fB\-I\-\fR, those
732 directories are searched for all \fB#include\fR directives.
734 In addition, \fB\-I\-\fR inhibits the use of the directory of the current
735 file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. There is no way to override this effect of \fB\-I\-\fR.
736 .IP "\fB\-iprefix\fR \fIprefix\fR" 4
737 .IX Item "-iprefix prefix"
738 Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR
739 options. If the prefix represents a directory, you should include the
741 .IP "\fB\-iwithprefix\fR \fIdir\fR" 4
742 .IX Item "-iwithprefix dir"
744 .IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4
745 .IX Item "-iwithprefixbefore dir"
747 Append \fIdir\fR to the prefix specified previously with
748 \&\fB\-iprefix\fR, and add the resulting directory to the include search
749 path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR
750 would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would.
751 .IP "\fB\-isysroot\fR \fIdir\fR" 4
752 .IX Item "-isysroot dir"
753 This option is like the \fB\-\-sysroot\fR option, but applies only to
754 header files (except for Darwin targets, where it applies to both header
755 files and libraries). See the \fB\-\-sysroot\fR option for more
757 .IP "\fB\-imultilib\fR \fIdir\fR" 4
758 .IX Item "-imultilib dir"
759 Use \fIdir\fR as a subdirectory of the directory containing
760 target-specific \*(C+ headers.
761 .IP "\fB\-nostdinc\fR" 4
763 Do not search the standard system directories for header files.
764 Only the directories explicitly specified with \fB\-I\fR,
765 \&\fB\-iquote\fR, \fB\-isystem\fR, and/or \fB\-idirafter\fR
766 options (and the directory of the current file, if appropriate)
768 .IP "\fB\-nostdinc++\fR" 4
769 .IX Item "-nostdinc++"
770 Do not search for header files in the \*(C+\-specific standard directories,
771 but do still search the other standard directories. (This option is
772 used when building the \*(C+ library.)
773 .IP "\fB\-Wcomment\fR" 4
776 .IP "\fB\-Wcomments\fR" 4
777 .IX Item "-Wcomments"
779 Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR
780 comment, or whenever a backslash-newline appears in a \fB//\fR comment.
781 This warning is enabled by \fB\-Wall\fR.
782 .IP "\fB\-Wtrigraphs\fR" 4
783 .IX Item "-Wtrigraphs"
784 Warn if any trigraphs are encountered that might change the meaning of
785 the program. Trigraphs within comments are not warned about,
786 except those that would form escaped newlines.
788 This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not
789 given, this option is still enabled unless trigraphs are enabled. To
790 get trigraph conversion without warnings, but get the other
791 \&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR.
792 .IP "\fB\-Wundef\fR" 4
794 Warn if an undefined identifier is evaluated in an \f(CW\*(C`#if\*(C'\fR directive.
795 Such identifiers are replaced with zero.
796 .IP "\fB\-Wexpansion\-to\-defined\fR" 4
797 .IX Item "-Wexpansion-to-defined"
798 Warn whenever \fBdefined\fR is encountered in the expansion of a macro
799 (including the case where the macro is expanded by an \fB#if\fR directive).
800 Such usage is not portable.
801 This warning is also enabled by \fB\-Wpedantic\fR and \fB\-Wextra\fR.
802 .IP "\fB\-Wunused\-macros\fR" 4
803 .IX Item "-Wunused-macros"
804 Warn about macros defined in the main file that are unused. A macro
805 is \fIused\fR if it is expanded or tested for existence at least once.
806 The preprocessor also warns if the macro has not been used at the
807 time it is redefined or undefined.
809 Built-in macros, macros defined on the command line, and macros
810 defined in include files are not warned about.
812 \&\fINote:\fR If a macro is actually used, but only used in skipped
813 conditional blocks, then the preprocessor reports it as unused. To avoid the
814 warning in such a case, you might improve the scope of the macro's
815 definition by, for example, moving it into the first skipped block.
816 Alternatively, you could provide a dummy use with something like:
819 \& #if defined the_macro_causing_the_warning
822 .IP "\fB\-Wno\-endif\-labels\fR" 4
823 .IX Item "-Wno-endif-labels"
824 Do not warn whenever an \f(CW\*(C`#else\*(C'\fR or an \f(CW\*(C`#endif\*(C'\fR are followed by text.
825 This sometimes happens in older programs with code of the form
835 The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments.
836 This warning is on by default.
838 .IX Header "ENVIRONMENT"
839 This section describes the environment variables that affect how \s-1CPP\s0
840 operates. You can use them to specify directories or prefixes to use
841 when searching for include files, or to control dependency output.
843 Note that you can also specify places to search using options such as
844 \&\fB\-I\fR, and control dependency output with options like
845 \&\fB\-M\fR. These take precedence over
846 environment variables, which in turn take precedence over the
847 configuration of \s-1GCC.\s0
848 .IP "\fB\s-1CPATH\s0\fR" 4
851 .IP "\fBC_INCLUDE_PATH\fR" 4
852 .IX Item "C_INCLUDE_PATH"
853 .IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4
854 .IX Item "CPLUS_INCLUDE_PATH"
855 .IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4
856 .IX Item "OBJC_INCLUDE_PATH"
858 Each variable's value is a list of directories separated by a special
859 character, much like \fB\s-1PATH\s0\fR, in which to look for header files.
860 The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and
861 determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a
862 semicolon, and for almost all other targets it is a colon.
864 \&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if
865 specified with \fB\-I\fR, but after any paths given with \fB\-I\fR
866 options on the command line. This environment variable is used
867 regardless of which language is being preprocessed.
869 The remaining environment variables apply only when preprocessing the
870 particular language indicated. Each specifies a list of directories
871 to be searched as if specified with \fB\-isystem\fR, but after any
872 paths given with \fB\-isystem\fR options on the command line.
874 In all these variables, an empty element instructs the compiler to
875 search its current working directory. Empty elements can appear at the
876 beginning or end of a path. For instance, if the value of
877 \&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same
878 effect as \fB\-I.\ \-I/special/include\fR.
879 .IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4
880 .IX Item "DEPENDENCIES_OUTPUT"
881 If this variable is set, its value specifies how to output
882 dependencies for Make based on the non-system header files processed
883 by the compiler. System header files are ignored in the dependency
886 The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in
887 which case the Make rules are written to that file, guessing the target
888 name from the source file name. Or the value can have the form
889 \&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to
890 file \fIfile\fR using \fItarget\fR as the target name.
892 In other words, this environment variable is equivalent to combining
893 the options \fB\-MM\fR and \fB\-MF\fR,
894 with an optional \fB\-MT\fR switch too.
895 .IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4
896 .IX Item "SUNPRO_DEPENDENCIES"
897 This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above),
898 except that system header files are not ignored, so it implies
899 \&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the
900 main input file is omitted.
901 .IP "\fB\s-1SOURCE_DATE_EPOCH\s0\fR" 4
902 .IX Item "SOURCE_DATE_EPOCH"
903 If this variable is set, its value specifies a \s-1UNIX\s0 timestamp to be
904 used in replacement of the current date and time in the \f(CW\*(C`_\|_DATE_\|_\*(C'\fR
905 and \f(CW\*(C`_\|_TIME_\|_\*(C'\fR macros, so that the embedded timestamps become
908 The value of \fB\s-1SOURCE_DATE_EPOCH\s0\fR must be a \s-1UNIX\s0 timestamp,
909 defined as the number of seconds (excluding leap seconds) since
910 01 Jan 1970 00:00:00 represented in \s-1ASCII\s0; identical to the output of
911 \&\fB\f(CB@command\fB{date +%s\fR} on GNU/Linux and other systems that support the
912 \&\f(CW%s\fR extension in the \f(CW\*(C`date\*(C'\fR command.
914 The value should be a known timestamp such as the last modification
915 time of the source or package and it should be set by the build
918 .IX Header "SEE ALSO"
919 \&\fBgpl\fR\|(7), \fBgfdl\fR\|(7), \fBfsf\-funding\fR\|(7),
920 \&\fBgcc\fR\|(1), and the Info entries for \fIcpp\fR and \fIgcc\fR.
922 .IX Header "COPYRIGHT"
923 Copyright (c) 1987\-2018 Free Software Foundation, Inc.
925 Permission is granted to copy, distribute and/or modify this document
926 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
927 any later version published by the Free Software Foundation. A copy of
928 the license is included in the
929 man page \fBgfdl\fR\|(7).
930 This manual contains no Invariant Sections. The Front-Cover Texts are
931 (a) (see below), and the Back-Cover Texts are (b) (see below).
933 (a) The \s-1FSF\s0's Front-Cover Text is:
939 (b) The \s-1FSF\s0's Back-Cover Text is:
942 \& You have freedom to copy and modify this GNU Manual, like GNU
943 \& software. Copies published by the Free Software Foundation raise
944 \& funds for GNU development.
projects / dragonfly.git / blob