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