1CPP(1) GNU CPP(1)
2
6 cpp - The C Preprocessor
7
9 cpp [--DDmacro[=defn]...] [--UUmacro]
10 [--IIdir...] [--WWwarn...]
11 [--MM⎪--MMMM] [--MMGG] [--MMFF filename]
12 [--MMPP] [--MMQQ target...] [--MMTT target...]
13 [--xx language] [--ssttdd==standard]
14 infile outfile
15 Only the most useful options are listed here; see below for the remain‐
17 der.
18
20 The C preprocessor, often known as cpp, is a macro processor that is
21 used automatically by the C compiler to transform your program before
22 compilation. It is called a macro processor because it allows you to
23 define macros, which are brief abbreviations for longer constructs.
24 The C preprocessor is intended to be used only with C, C++, and Objec‐
26 tive-C source code. In the past, it has been abused as a general text
27 processor. It will choke on input which does not obey C's lexical
28 rules. For example, apostrophes will be interpreted as the beginning
29 of character constants, and cause errors. Also, you cannot rely on it
30 preserving characteristics of the input which are not significant to C-
31 family languages. If a Makefile is preprocessed, all the hard tabs
32 will be removed, and the Makefile will not work.
33 Having said that, you can often get away with using cpp on things which
35 are not C. Other Algol-ish programming languages are often safe (Pas‐
36 cal, Ada, etc.) So is assembly, with caution. --ttrraaddiittiioonnaall mode pre‐
37 serves more white space, and is otherwise more permissive. Many of the
38 problems can be avoided by writing C or C++ style comments instead of
39 native language comments, and keeping macros simple.
40 Wherever possible, you should use a preprocessor geared to the language
42 you are writing in. Modern versions of the GNU assembler have macro
43 facilities. Most high level programming languages have their own con‐
44 ditional compilation and inclusion mechanism. If all else fails, try a
45 true general text processor, such as GNU M4.
46 C preprocessors vary in some details. This manual discusses the GNU C
48 preprocessor, which provides a small superset of the features of ISO
49 Standard C. In its default mode, the GNU C preprocessor does not do a
50 few things required by the standard. These are features which are
51 rarely, if ever, used, and may cause surprising changes to the meaning
52 of a program which does not expect them. To get strict ISO Standard C,
53 you should use the --ssttdd==cc8899 or --ssttdd==cc9999 options, depending on which
54 version of the standard you want. To get all the mandatory diagnos‐
55 tics, you must also use --ppeeddaannttiicc.
56
58 The C preprocessor expects two file names as arguments, infile and out‐
59 file. The preprocessor reads infile together with any other files it
60 specifies with ##iinncclluuddee. All the output generated by the combined
61 input files is written in outfile.
62 Either infile or outfile may be --, which as infile means to read from
64 standard input and as outfile means to write to standard output. Also,
65 if either file is omitted, it means the same as if -- had been specified
66 for that file.
67 Unless otherwise noted, or the option ends in ==, all options which take
69 an argument may have that argument appear either immediately after the
70 option, or with a space between option and argument: --IIffoooo and --II ffoooo
71 have the same effect.
72 Many options have multi-letter names; therefore multiple single-letter
74 options may not be grouped: --ddMM is very different from --dd --MM.
75 --DD name
77 Predefine name as a macro, with definition "1".
78 --DD name==definition
80 Predefine name as a macro, with definition definition. There are
81 no restrictions on the contents of definition, but if you are
82 invoking the preprocessor from a shell or shell-like program you
83 may need to use the shell's quoting syntax to protect characters
84 such as spaces that have a meaning in the shell syntax.
85 If you wish to define a function-like macro on the command line,
87 write its argument list with surrounding parentheses before the
88 equals sign (if any). Parentheses are meaningful to most shells,
89 so you will need to quote the option. With sshh and ccsshh,
90 --DD''name((args...))==definition'' works.
91 --DD and --UU options are processed in the order they are given on the
93 command line. All --iimmaaccrrooss file and --iinncclluuddee file options are pro‐
94 cessed after all --DD and --UU options.
95 --UU name
97 Cancel any previous definition of name, either built in or provided
98 with a --DD option.
99 --uunnddeeff
101 Do not predefine any system-specific macros. The common predefined
102 macros remain defined.
103 --II dir
105 Add the directory dir to the list of directories to be searched for
106 header files.
107 Directories named by --II are searched before the standard system
109 include directories.
110 It is dangerous to specify a standard system include directory in
112 an --II option. This defeats the special treatment of system headers
113 . It can also defeat the repairs to buggy system headers which GCC
114 makes when it is installed.
115 --oo file
117 Write output to file. This is the same as specifying file as the
118 second non-option argument to ccpppp. ggcccc has a different interpreta‐
119 tion of a second non-option argument, so you must use --oo to specify
120 the output file.
121 --WWaallll
123 Turns on all optional warnings which are desirable for normal code.
124 At present this is --WWccoommmmeenntt and --WWttrriiggrraapphhss. Note that many of
125 the preprocessor's warnings are on by default and have no options
126 to control them.
127 --WWccoommmmeenntt
129 --WWccoommmmeennttss
130 Warn whenever a comment-start sequence //** appears in a //** comment,
131 or whenever a backslash-newline appears in a //// comment. (Both
132 forms have the same effect.)
133 --WWttrriiggrraapphhss
135 Warn if any trigraphs are encountered. This option used to take
136 effect only if --ttrriiggrraapphhss was also specified, but now works inde‐
137 pendently. Warnings are not given for trigraphs within comments,
138 as they do not affect the meaning of the program.
139 --WWttrraaddiittiioonnaall
141 Warn about certain constructs that behave differently in tradi‐
142 tional and ISO C. Also warn about ISO C constructs that have no
143 traditional C equivalent, and problematic constructs which should
144 be avoided.
145 --WWiimmppoorrtt
147 Warn the first time ##iimmppoorrtt is used.
148 --WWuunnddeeff
150 Warn whenever an identifier which is not a macro is encountered in
151 an ##iiff directive, outside of ddeeffiinneedd. Such identifiers are
152 replaced with zero.
153 --WWeerrrroorr
155 Make all warnings into hard errors. Source code which triggers
156 warnings will be rejected.
157 --WWssyysstteemm--hheeaaddeerrss
159 Issue warnings for code in system headers. These are normally
160 unhelpful in finding bugs in your own code, therefore suppressed.
161 If you are responsible for the system library, you may want to see
162 them.
163 --ww Suppress all warnings, including those which GNU CPP issues by
165 default.
166 --ppeeddaannttiicc
168 Issue all the mandatory diagnostics listed in the C standard. Some
169 of them are left out by default, since they trigger frequently on
170 harmless code.
171 --ppeeddaannttiicc--eerrrroorrss
173 Issue all the mandatory diagnostics, and make all mandatory diag‐
174 nostics into errors. This includes mandatory diagnostics that GCC
175 issues without --ppeeddaannttiicc but treats as warnings.
176 --MM Instead of outputting the result of preprocessing, output a rule
178 suitable for mmaakkee describing the dependencies of the main source
179 file. The preprocessor outputs one mmaakkee rule containing the object
180 file name for that source file, a colon, and the names of all the
181 included files, including those coming from --iinncclluuddee or --iimmaaccrrooss
182 command line options.
183 Unless specified explicitly (with --MMTT or --MMQQ), the object file name
185 consists of the basename of the source file with any suffix
186 replaced with object file suffix. If there are many included files
187 then the rule is split into several lines using \\-newline. The
188 rule has no commands.
189 This option does not suppress the preprocessor's debug output, such
191 as --ddMM. To avoid mixing such debug output with the dependency
192 rules you should explicitly specify the dependency output file with
193 --MMFF, or use an environment variable like DDEEPPEENNDDEENNCCIIEESS__OOUUTTPPUUTT.
194 Debug output will still be sent to the regular output stream as
195 normal.
196 Passing --MM to the driver implies --EE.
198 --MMMM Like --MM but do not mention header files that are found in system
200 header directories, nor header files that are included, directly or
201 indirectly, from such a header.
202 This implies that the choice of angle brackets or double quotes in
204 an ##iinncclluuddee directive does not in itself determine whether that
205 header will appear in --MMMM dependency output. This is a slight
206 change in semantics from GCC versions 3.0 and earlier.
207 --MMFF file
209 @anchor{-MF} When used with --MM or --MMMM, specifies a file to write
210 the dependencies to. If no --MMFF switch is given the preprocessor
211 sends the rules to the same place it would have sent preprocessed
212 output.
213 When used with the driver options --MMDD or --MMMMDD, --MMFF overrides the
215 default dependency output file.
216 --MMGG When used with --MM or --MMMM, --MMGG says to treat missing header files as
218 generated files and assume they live in the same directory as the
219 source file. It suppresses preprocessed output, as a missing
220 header file is ordinarily an error.
221 This feature is used in automatic updating of makefiles.
223 --MMPP This option instructs CPP to add a phony target for each dependency
225 other than the main file, causing each to depend on nothing. These
226 dummy rules work around errors mmaakkee gives if you remove header
227 files without updating the Makefile to match.
228 This is typical output:
230 test.o: test.c test.h
232 test.h:
234 --MMTT target
237 Change the target of the rule emitted by dependency generation. By
238 default CPP takes the name of the main input file, including any
239 path, deletes any file suffix such as ..cc, and appends the plat‐
240 form's usual object suffix. The result is the target.
241 An --MMTT option will set the target to be exactly the string you
243 specify. If you want multiple targets, you can specify them as a
244 single argument to --MMTT, or use multiple --MMTT options.
245 For example, --MMTT ''$$((oobbjjppffxx))ffoooo..oo'' might give
247 $(objpfx)foo.o: foo.c
249 --MMQQ target
252 Same as --MMTT, but it quotes any characters which are special to
253 Make. --MMQQ ''$$((oobbjjppffxx))ffoooo..oo'' gives
254 $$(objpfx)foo.o: foo.c
256 The default target is automatically quoted, as if it were given
258 with --MMQQ.
259 --MMDD --MMDD is equivalent to --MM --MMFF file, except that --EE is not implied.
261 The driver determines file based on whether an --oo option is given.
262 If it is, the driver uses its argument but with a suffix of .d,
263 otherwise it take the basename of the input file and applies a .d
264 suffix.
265 If --MMDD is used in conjunction with --EE, any --oo switch is understood
267 to specify the dependency output file (but @pxref{-MF}), but if
268 used without --EE, each --oo is understood to specify a target object
269 file.
270 Since --EE is not implied, --MMDD can be used to generate a dependency
272 output file as a side-effect of the compilation process.
273 --MMMMDD
275 Like --MMDD except mention only user header files, not system -header
276 files.
277 --xx cc
279 --xx cc++++
280 --xx oobbjjeeccttiivvee--cc
281 --xx aasssseemmbblleerr--wwiitthh--ccpppp
282 Specify the source language: C, C++, Objective-C, or assembly.
283 This has nothing to do with standards conformance or extensions; it
284 merely selects which base syntax to expect. If you give none of
285 these options, cpp will deduce the language from the extension of
286 the source file: ..cc, ..cccc, ..mm, or ..SS. Some other common extensions
287 for C++ and assembly are also recognized. If cpp does not recog‐
288 nize the extension, it will treat the file as C; this is the most
289 generic mode.
290 NNoottee:: Previous versions of cpp accepted a --llaanngg option which
292 selected both the language and the standards conformance level.
293 This option has been removed, because it conflicts with the --ll
294 option.
295 --ssttdd==standard
297 --aannssii
298 Specify the standard to which the code should conform. Currently
299 cpp only knows about the standards for C; other language standards
300 will be added in the future.
301 standard may be one of:
303 ""iso9899:1990""
305 ""c89""
306 The ISO C standard from 1990. cc8899 is the customary shorthand
307 for this version of the standard.
308 The --aannssii option is equivalent to --ssttdd==cc8899.
310 ""iso9899:199409""
312 The 1990 C standard, as amended in 1994.
313 ""iso9899:1999""
315 ""c99""
316 ""iso9899:199x""
317 ""c9x""
318 The revised ISO C standard, published in December 1999. Before
319 publication, this was known as C9X.
320 ""gnu89""
322 The 1990 C standard plus GNU extensions. This is the default.
323 ""gnu99""
325 ""gnu9x""
326 The 1999 C standard plus GNU extensions.
327 --II-- Split the include path. Any directories specified with --II options
329 before --II-- are searched only for headers requested with
330 "#include "file""; they are not searched for "#include <file>". If
331 additional directories are specified with --II options after the --II--,
332 those directories are searched for all ##iinncclluuddee directives.
333 In addition, --II-- inhibits the use of the directory of the current
335 file directory as the first search directory for "#include "file"".
336 --nnoossttddiinncc
338 Do not search the standard system directories for header files.
339 Only the directories you have specified with --II options (and the
340 directory of the current file, if appropriate) are searched.
341 --nnoossttddiinncc++++
343 Do not search for header files in the C++-specific standard direc‐
344 tories, but do still search the other standard directories. (This
345 option is used when building the C++ library.)
346 --iinncclluuddee file
348 Process file as if "#include "file"" appeared as the first line of
349 the primary source file. However, the first directory searched for
350 file is the preprocessor's working directory instead of the direc‐
351 tory containing the main source file. If not found there, it is
352 searched for in the remainder of the "#include "..."" search chain
353 as normal.
354 If multiple --iinncclluuddee options are given, the files are included in
356 the order they appear on the command line.
357 --iimmaaccrrooss file
359 Exactly like --iinncclluuddee, except that any output produced by scanning
360 file is thrown away. Macros it defines remain defined. This
361 allows you to acquire all the macros from a header without also
362 processing its declarations.
363 All files specified by --iimmaaccrrooss are processed before all files
365 specified by --iinncclluuddee.
366 --iiddiirraafftteerr dir
368 Search dir for header files, but do it after all directories speci‐
369 fied with --II and the standard system directories have been
370 exhausted. dir is treated as a system include directory.
371 --iipprreeffiixx prefix
373 Specify prefix as the prefix for subsequent --iiwwiitthhpprreeffiixx options.
374 If the prefix represents a directory, you should include the final
375 //.
376 --iiwwiitthhpprreeffiixx dir
378 --iiwwiitthhpprreeffiixxbbeeffoorree dir
379 Append dir to the prefix specified previously with --iipprreeffiixx, and
380 add the resulting directory to the include search path. --iiwwiitthhpprree‐‐
381 ffiixxbbeeffoorree puts it in the same place --II would; --iiwwiitthhpprreeffiixx puts it
382 where --iiddiirraafftteerr would.
383 Use of these options is discouraged.
385 --iissyysstteemm dir
387 Search dir for header files, after all directories specified by --II
388 but before the standard system directories. Mark it as a system
389 directory, so that it gets the same special treatment as is applied
390 to the standard system directories.
391 --ffpprreepprroocceesssseedd
393 Indicate to the preprocessor that the input file has already been
394 preprocessed. This suppresses things like macro expansion, tri‐
395 graph conversion, escaped newline splicing, and processing of most
396 directives. The preprocessor still recognizes and removes com‐
397 ments, so that you can pass a file preprocessed with --CC to the com‐
398 piler without problems. In this mode the integrated preprocessor
399 is little more than a tokenizer for the front ends.
400 --ffpprreepprroocceesssseedd is implicit if the input file has one of the exten‐
402 sions ..ii, ..iiii or ..mmii. These are the extensions that GCC uses for
403 preprocessed files created by --ssaavvee--tteemmppss.
404 --ffttaabbssttoopp==width
406 Set the distance between tab stops. This helps the preprocessor
407 report correct column numbers in warnings or errors, even if tabs
408 appear on the line. If the value is less than 1 or greater than
409 100, the option is ignored. The default is 8.
410 --ffnnoo--sshhooww--ccoolluummnn
412 Do not print column numbers in diagnostics. This may be necessary
413 if diagnostics are being scanned by a program that does not under‐
414 stand the column numbers, such as ddeejjaaggnnuu.
415 --AA predicate==answer
417 Make an assertion with the predicate predicate and answer answer.
418 This form is preferred to the older form --AA predicate((answer)),
419 which is still supported, because it does not use shell special
420 characters.
421 --AA --predicate==answer
423 Cancel an assertion with the predicate predicate and answer answer.
424 --AA-- Cancel all predefined assertions and all assertions preceding it on
426 the command line. Also, undefine all predefined macros and all
427 macros preceding it on the command line. (This is a historical
428 wart and may change in the future.)
429 --ddCCHHAARRSS
431 CHARS is a sequence of one or more of the following characters, and
432 must not be preceded by a space. Other characters are interpreted
433 by the compiler proper, or reserved for future versions of GCC, and
434 so are silently ignored. If you specify characters whose behavior
435 conflicts, the result is undefined.
436 MM Instead of the normal output, generate a list of ##ddeeffiinnee direc‐
438 tives for all the macros defined during the execution of the
439 preprocessor, including predefined macros. This gives you a
440 way of finding out what is predefined in your version of the
441 preprocessor. Assuming you have no file foo.h, the command
442 touch foo.h; cpp -dM foo.h
444 will show all the predefined macros.
446 DD Like MM except in two respects: it does not include the prede‐
448 fined macros, and it outputs both the ##ddeeffiinnee directives and
449 the result of preprocessing. Both kinds of output go to the
450 standard output file.
451 NN Like DD, but emit only the macro names, not their expansions.
453 II Output ##iinncclluuddee directives in addition to the result of prepro‐
455 cessing.
456 --PP Inhibit generation of linemarkers in the output from the preproces‐
458 sor. This might be useful when running the preprocessor on some‐
459 thing that is not C code, and will be sent to a program which might
460 be confused by the linemarkers.
461 --CC Do not discard comments. All comments are passed through to the
463 output file, except for comments in processed directives, which are
464 deleted along with the directive.
465 You should be prepared for side effects when using --CC; it causes
467 the preprocessor to treat comments as tokens in their own right.
468 For example, comments appearing at the start of what would be a
469 directive line have the effect of turning that line into an ordi‐
470 nary source line, since the first token on the line is no longer a
471 ##.
472 --ggcccc
474 Define the macros __GNUC__, __GNUC_MINOR__ and __GNUC_PATCHLEVEL__.
475 These are defined automatically when you use ggcccc --EE; you can turn
476 them off in that case with --nnoo--ggcccc.
477 --ttrraaddiittiioonnaall
479 Try to imitate the behavior of old-fashioned C, as opposed to ISO
480 C.
481 --ttrriiggrraapphhss
483 Process trigraph sequences.
484 --rreemmaapp
486 Enable special code to work around file systems which only permit
487 very short file names, such as MS-DOS.
488 --$$ Forbid the use of $$ in identifiers. The C standard allows imple‐
490 mentations to define extra characters that can appear in identi‐
491 fiers. By default GNU CPP permits $$, a common extension.
492 --hh
494 ----hheellpp
495 ----ttaarrggeett--hheellpp
496 Print text describing all the command line options instead of pre‐
497 processing anything.
498 --vv Verbose mode. Print out GNU CPP's version number at the beginning
500 of execution, and report the final form of the include path.
501 --HH Print the name of each header file used, in addition to other nor‐
503 mal activities. Each name is indented to show how deep in the
504 ##iinncclluuddee stack it is.
505 --vveerrssiioonn
507 ----vveerrssiioonn
508 Print out GNU CPP's version number. With one dash, proceed to pre‐
509 process as normal. With two dashes, exit immediately.
510
512 This section describes the environment variables that affect how CPP
513 operates. You can use them to specify directories or prefixes to use
514 when searching for include files, or to control dependency output.
515 Note that you can also specify places to search using options such as
517 --II, and control dependency output with options like --MM. These take
518 precedence over environment variables, which in turn take precedence
519 over the configuration of GCC.
520 CCPPAATTHH
522 CC__IINNCCLLUUDDEE__PPAATTHH
523 CCPPLLUUSS__IINNCCLLUUDDEE__PPAATTHH
524 OOBBJJCC__IINNCCLLUUDDEE__PPAATTHH
525 Each variable's value is a list of directories separated by a spe‐
526 cial character, much like PPAATTHH, in which to look for header files.
527 The special character, "PATH_SEPARATOR", is target-dependent and
528 determined at GCC build time. For Windows-based targets it is a
529 semicolon, and for almost all other targets it is a colon.
530 CCPPAATTHH specifies a list of directories to be searched as if speci‐
532 fied with --II, but after any paths given with --II options on the com‐
533 mand line. The environment variable is used regardless of which
534 language is being preprocessed.
535 The remaining environment variables apply only when preprocessing
537 the particular language indicated. Each specifies a list of direc‐
538 tories to be searched as if specified with --iissyysstteemm, but after any
539 paths given with --iissyysstteemm options on the command line.
540 See also @ref{Search Path}.
542 DDEEPPEENNDDEENNCCIIEESS__OOUUTTPPUUTT
544 @anchor{DEPENDENCIES_OUTPUT} If this variable is set, its value
545 specifies how to output dependencies for Make based on the non-sys‐
546 tem header files processed by the compiler. System header files
547 are ignored in the dependency output.
548 The value of DDEEPPEENNDDEENNCCIIEESS__OOUUTTPPUUTT can be just a file name, in which
550 case the Make rules are written to that file, guessing the target
551 name from the source file name. Or the value can have the form
552 file target, in which case the rules are written to file file using
553 target as the target name.
554 In other words, this environment variable is equivalent to combin‐
556 ing the options --MMMM and --MMFF, with an optional --MMTT switch too.
557 SSUUNNPPRROO__DDEEPPEENNDDEENNCCIIEESS
559 This variable is the same as the environment variable DDEEPPEENNDDEENN‐‐
560 CCIIEESS__OOUUTTPPUUTT, except that system header files are not ignored, so it
561 implies --MM rather than --MMMM. However, the dependence on the main
562 input file is omitted.
563
565 gpl(7), gfdl(7), fsf-funding(7), gcc(1), as(1), ld(1), and the Info
566 entries for cpp, gcc, and binutils.
567
569 Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
570 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
571 Permission is granted to copy, distribute and/or modify this document
573 under the terms of the GNU Free Documentation License, Version 1.1 or
574 any later version published by the Free Software Foundation. A copy of
575 the license is included in the man page gfdl(7). This manual contains
576 no Invariant Sections. The Front-Cover Texts are (a) (see below), and
577 the Back-Cover Texts are (b) (see below).
578 (a) The FSF's Front-Cover Text is:
580 A GNU Manual
582 (b) The FSF's Back-Cover Text is:
584 You have freedom to copy and modify this GNU Manual, like GNU
586 software. Copies published by the Free Software Foundation raise
587 funds for GNU development.
5883rd Berkeley Distribution gcc-3.2.3 CPP(1)