1<html lang="en"> 2<head> 3<title>Invocation - The C Preprocessor</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="The C Preprocessor"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="prev" href="Implementation-Details.html#Implementation-Details" title="Implementation Details"> 9<link rel="next" href="Environment-Variables.html#Environment-Variables" title="Environment Variables"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 131997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 142008, 2009, 2010, 2011 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation. A copy of 20the license is included in the 21section entitled ``GNU Free Documentation License''. 22 23This manual contains no Invariant Sections. The Front-Cover Texts are 24(a) (see below), and the Back-Cover Texts are (b) (see below). 25 26(a) The FSF's Front-Cover Text is: 27 28 A GNU Manual 29 30(b) The FSF's Back-Cover Text is: 31 32 You have freedom to copy and modify this GNU Manual, like GNU 33 software. Copies published by the Free Software Foundation raise 34 funds for GNU development. 35--> 36<meta http-equiv="Content-Style-Type" content="text/css"> 37<style type="text/css"><!-- 38 pre.display { font-family:inherit } 39 pre.format { font-family:inherit } 40 pre.smalldisplay { font-family:inherit; font-size:smaller } 41 pre.smallformat { font-family:inherit; font-size:smaller } 42 pre.smallexample { font-size:smaller } 43 pre.smalllisp { font-size:smaller } 44 span.sc { font-variant:small-caps } 45 span.roman { font-family:serif; font-weight:normal; } 46 span.sansserif { font-family:sans-serif; font-weight:normal; } 47--></style> 48<link rel="stylesheet" type="text/css" href="../cs.css"> 49</head> 50<body> 51<div class="node"> 52<a name="Invocation"></a> 53<p> 54Next: <a rel="next" accesskey="n" href="Environment-Variables.html#Environment-Variables">Environment Variables</a>, 55Previous: <a rel="previous" accesskey="p" href="Implementation-Details.html#Implementation-Details">Implementation Details</a>, 56Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> 57<hr> 58</div> 59 60<h2 class="chapter">12 Invocation</h2> 61 62<p><a name="index-invocation-118"></a><a name="index-command-line-119"></a> 63Most often when you use the C preprocessor you will not have to invoke it 64explicitly: the C compiler will do so automatically. However, the 65preprocessor is sometimes useful on its own. All the options listed 66here are also acceptable to the C compiler and have the same meaning, 67except that the C compiler has different rules for specifying the output 68file. 69 70 <p><em>Note:</em> Whether you use the preprocessor by way of <samp><span class="command">gcc</span></samp> 71or <samp><span class="command">cpp</span></samp>, the <dfn>compiler driver</dfn> is run first. This 72program's purpose is to translate your command into invocations of the 73programs that do the actual work. Their command line interfaces are 74similar but not identical to the documented interface, and may change 75without notice. 76 77<!-- man begin OPTIONS --> 78 <p>The C preprocessor expects two file names as arguments, <var>infile</var> and 79<var>outfile</var>. The preprocessor reads <var>infile</var> together with any 80other files it specifies with ‘<samp><span class="samp">#include</span></samp>’. All the output generated 81by the combined input files is written in <var>outfile</var>. 82 83 <p>Either <var>infile</var> or <var>outfile</var> may be <samp><span class="option">-</span></samp>, which as 84<var>infile</var> means to read from standard input and as <var>outfile</var> 85means to write to standard output. Also, if either file is omitted, it 86means the same as if <samp><span class="option">-</span></samp> had been specified for that file. 87 88 <p>Unless otherwise noted, or the option ends in ‘<samp><span class="samp">=</span></samp>’, all options 89which take an argument may have that argument appear either immediately 90after the option, or with a space between option and argument: 91<samp><span class="option">-Ifoo</span></samp> and <samp><span class="option">-I foo</span></samp> have the same effect. 92 93 <p><a name="index-grouping-options-120"></a><a name="index-options_002c-grouping-121"></a>Many options have multi-letter names; therefore multiple single-letter 94options may <em>not</em> be grouped: <samp><span class="option">-dM</span></samp> is very different from 95‘<samp><span class="samp">-d -M</span></samp>’<!-- /@w -->. 96 97 <p><a name="index-options-122"></a> 98 99<!-- Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, --> 100<!-- 2010, Free Software Foundation, Inc. --> 101<!-- This is part of the CPP and GCC manuals. --> 102<!-- For copying conditions, see the file gcc.texi. --> 103<!-- --> 104<!-- Options affecting the preprocessor --> 105<!-- --> 106<!-- If this file is included with the flag ``cppmanual'' set, it is --> 107<!-- formatted for inclusion in the CPP manual; otherwise the main GCC manual. --> 108 <dl> 109<dt><code>-D </code><var>name</var><dd><a name="index-D-123"></a>Predefine <var>name</var> as a macro, with definition <code>1</code>. 110 111 <br><dt><code>-D </code><var>name</var><code>=</code><var>definition</var><dd>The contents of <var>definition</var> are tokenized and processed as if 112they appeared during translation phase three in a ‘<samp><span class="samp">#define</span></samp>’ 113directive. In particular, the definition will be truncated by 114embedded newline characters. 115 116 <p>If you are invoking the preprocessor from a shell or shell-like 117program you may need to use the shell's quoting syntax to protect 118characters such as spaces that have a meaning in the shell syntax. 119 120 <p>If you wish to define a function-like macro on the command line, write 121its argument list with surrounding parentheses before the equals sign 122(if any). Parentheses are meaningful to most shells, so you will need 123to quote the option. With <samp><span class="command">sh</span></samp> and <samp><span class="command">csh</span></samp>, 124<samp><span class="option">-D'</span><var>name</var><span class="option">(</span><var>args<small class="dots">...</small></var><span class="option">)=</span><var>definition</var><span class="option">'</span></samp> works. 125 126 <p><samp><span class="option">-D</span></samp> and <samp><span class="option">-U</span></samp> options are processed in the order they 127are given on the command line. All <samp><span class="option">-imacros </span><var>file</var></samp> and 128<samp><span class="option">-include </span><var>file</var></samp> options are processed after all 129<samp><span class="option">-D</span></samp> and <samp><span class="option">-U</span></samp> options. 130 131 <br><dt><code>-U </code><var>name</var><dd><a name="index-U-124"></a>Cancel any previous definition of <var>name</var>, either built in or 132provided with a <samp><span class="option">-D</span></samp> option. 133 134 <br><dt><code>-undef</code><dd><a name="index-undef-125"></a>Do not predefine any system-specific or GCC-specific macros. The 135standard predefined macros remain defined. 136See <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">Standard Predefined Macros</a>. 137 138 <br><dt><code>-I </code><var>dir</var><dd><a name="index-I-126"></a>Add the directory <var>dir</var> to the list of directories to be searched 139for header files. 140See <a href="Search-Path.html#Search-Path">Search Path</a>. 141Directories named by <samp><span class="option">-I</span></samp> are searched before the standard 142system include directories. If the directory <var>dir</var> is a standard 143system include directory, the option is ignored to ensure that the 144default search order for system directories and the special treatment 145of system headers are not defeated 146(see <a href="System-Headers.html#System-Headers">System Headers</a>) 147. 148If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced 149by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. 150 151 <br><dt><code>-o </code><var>file</var><dd><a name="index-o-127"></a>Write output to <var>file</var>. This is the same as specifying <var>file</var> 152as the second non-option argument to <samp><span class="command">cpp</span></samp>. <samp><span class="command">gcc</span></samp> has a 153different interpretation of a second non-option argument, so you must 154use <samp><span class="option">-o</span></samp> to specify the output file. 155 156 <br><dt><code>-Wall</code><dd><a name="index-Wall-128"></a>Turns on all optional warnings which are desirable for normal code. 157At present this is <samp><span class="option">-Wcomment</span></samp>, <samp><span class="option">-Wtrigraphs</span></samp>, 158<samp><span class="option">-Wmultichar</span></samp> and a warning about integer promotion causing a 159change of sign in <code>#if</code> expressions. Note that many of the 160preprocessor's warnings are on by default and have no options to 161control them. 162 163 <br><dt><code>-Wcomment</code><dt><code>-Wcomments</code><dd><a name="index-Wcomment-129"></a><a name="index-Wcomments-130"></a>Warn whenever a comment-start sequence ‘<samp><span class="samp">/*</span></samp>’ appears in a ‘<samp><span class="samp">/*</span></samp>’ 164comment, or whenever a backslash-newline appears in a ‘<samp><span class="samp">//</span></samp>’ comment. 165(Both forms have the same effect.) 166 167 <br><dt><code>-Wtrigraphs</code><dd><a name="index-Wtrigraphs-131"></a><a name="Wtrigraphs"></a>Most trigraphs in comments cannot affect the meaning of the program. 168However, a trigraph that would form an escaped newline (‘<samp><span class="samp">??/</span></samp>’ at 169the end of a line) can, by changing where the comment begins or ends. 170Therefore, only trigraphs that would form escaped newlines produce 171warnings inside a comment. 172 173 <p>This option is implied by <samp><span class="option">-Wall</span></samp>. If <samp><span class="option">-Wall</span></samp> is not 174given, this option is still enabled unless trigraphs are enabled. To 175get trigraph conversion without warnings, but get the other 176<samp><span class="option">-Wall</span></samp> warnings, use ‘<samp><span class="samp">-trigraphs -Wall -Wno-trigraphs</span></samp>’. 177 178 <br><dt><code>-Wtraditional</code><dd><a name="index-Wtraditional-132"></a>Warn about certain constructs that behave differently in traditional and 179ISO C. Also warn about ISO C constructs that have no traditional C 180equivalent, and problematic constructs which should be avoided. 181See <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. 182 183 <br><dt><code>-Wundef</code><dd><a name="index-Wundef-133"></a>Warn whenever an identifier which is not a macro is encountered in an 184‘<samp><span class="samp">#if</span></samp>’ directive, outside of ‘<samp><span class="samp">defined</span></samp>’. Such identifiers are 185replaced with zero. 186 187 <br><dt><code>-Wunused-macros</code><dd><a name="index-Wunused_002dmacros-134"></a>Warn about macros defined in the main file that are unused. A macro 188is <dfn>used</dfn> if it is expanded or tested for existence at least once. 189The preprocessor will also warn if the macro has not been used at the 190time it is redefined or undefined. 191 192 <p>Built-in macros, macros defined on the command line, and macros 193defined in include files are not warned about. 194 195 <p><em>Note:</em> If a macro is actually used, but only used in skipped 196conditional blocks, then CPP will report it as unused. To avoid the 197warning in such a case, you might improve the scope of the macro's 198definition by, for example, moving it into the first skipped block. 199Alternatively, you could provide a dummy use with something like: 200 201 <pre class="smallexample"> #if defined the_macro_causing_the_warning 202 #endif 203</pre> 204 <br><dt><code>-Wendif-labels</code><dd><a name="index-Wendif_002dlabels-135"></a>Warn whenever an ‘<samp><span class="samp">#else</span></samp>’ or an ‘<samp><span class="samp">#endif</span></samp>’ are followed by text. 205This usually happens in code of the form 206 207 <pre class="smallexample"> #if FOO 208 ... 209 #else FOO 210 ... 211 #endif FOO 212</pre> 213 <p class="noindent">The second and third <code>FOO</code> should be in comments, but often are not 214in older programs. This warning is on by default. 215 216 <br><dt><code>-Werror</code><dd><a name="index-Werror-136"></a>Make all warnings into hard errors. Source code which triggers warnings 217will be rejected. 218 219 <br><dt><code>-Wsystem-headers</code><dd><a name="index-Wsystem_002dheaders-137"></a>Issue warnings for code in system headers. These are normally unhelpful 220in finding bugs in your own code, therefore suppressed. If you are 221responsible for the system library, you may want to see them. 222 223 <br><dt><code>-w</code><dd><a name="index-w-138"></a>Suppress all warnings, including those which GNU CPP issues by default. 224 225 <br><dt><code>-pedantic</code><dd><a name="index-pedantic-139"></a>Issue all the mandatory diagnostics listed in the C standard. Some of 226them are left out by default, since they trigger frequently on harmless 227code. 228 229 <br><dt><code>-pedantic-errors</code><dd><a name="index-pedantic_002derrors-140"></a>Issue all the mandatory diagnostics, and make all mandatory diagnostics 230into errors. This includes mandatory diagnostics that GCC issues 231without ‘<samp><span class="samp">-pedantic</span></samp>’ but treats as warnings. 232 233 <br><dt><code>-M</code><dd><a name="index-M-141"></a><a name="index-g_t_0040command_007bmake_007d-142"></a><a name="index-dependencies_002c-_0040command_007bmake_007d-143"></a>Instead of outputting the result of preprocessing, output a rule 234suitable for <samp><span class="command">make</span></samp> describing the dependencies of the main 235source file. The preprocessor outputs one <samp><span class="command">make</span></samp> rule containing 236the object file name for that source file, a colon, and the names of all 237the included files, including those coming from <samp><span class="option">-include</span></samp> or 238<samp><span class="option">-imacros</span></samp> command line options. 239 240 <p>Unless specified explicitly (with <samp><span class="option">-MT</span></samp> or <samp><span class="option">-MQ</span></samp>), the 241object file name consists of the name of the source file with any 242suffix replaced with object file suffix and with any leading directory 243parts removed. If there are many included files then the rule is 244split into several lines using ‘<samp><span class="samp">\</span></samp>’-newline. The rule has no 245commands. 246 247 <p>This option does not suppress the preprocessor's debug output, such as 248<samp><span class="option">-dM</span></samp>. To avoid mixing such debug output with the dependency 249rules you should explicitly specify the dependency output file with 250<samp><span class="option">-MF</span></samp>, or use an environment variable like 251<samp><span class="env">DEPENDENCIES_OUTPUT</span></samp> (see <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>). Debug output 252will still be sent to the regular output stream as normal. 253 254 <p>Passing <samp><span class="option">-M</span></samp> to the driver implies <samp><span class="option">-E</span></samp>, and suppresses 255warnings with an implicit <samp><span class="option">-w</span></samp>. 256 257 <br><dt><code>-MM</code><dd><a name="index-MM-144"></a>Like <samp><span class="option">-M</span></samp> but do not mention header files that are found in 258system header directories, nor header files that are included, 259directly or indirectly, from such a header. 260 261 <p>This implies that the choice of angle brackets or double quotes in an 262‘<samp><span class="samp">#include</span></samp>’ directive does not in itself determine whether that 263header will appear in <samp><span class="option">-MM</span></samp> dependency output. This is a 264slight change in semantics from GCC versions 3.0 and earlier. 265 266 <p><a name="dashMF"></a><br><dt><code>-MF </code><var>file</var><dd><a name="index-MF-145"></a>When used with <samp><span class="option">-M</span></samp> or <samp><span class="option">-MM</span></samp>, specifies a 267file to write the dependencies to. If no <samp><span class="option">-MF</span></samp> switch is given 268the preprocessor sends the rules to the same place it would have sent 269preprocessed output. 270 271 <p>When used with the driver options <samp><span class="option">-MD</span></samp> or <samp><span class="option">-MMD</span></samp>, 272<samp><span class="option">-MF</span></samp> overrides the default dependency output file. 273 274 <br><dt><code>-MG</code><dd><a name="index-MG-146"></a>In conjunction with an option such as <samp><span class="option">-M</span></samp> requesting 275dependency generation, <samp><span class="option">-MG</span></samp> assumes missing header files are 276generated files and adds them to the dependency list without raising 277an error. The dependency filename is taken directly from the 278<code>#include</code> directive without prepending any path. <samp><span class="option">-MG</span></samp> 279also suppresses preprocessed output, as a missing header file renders 280this useless. 281 282 <p>This feature is used in automatic updating of makefiles. 283 284 <br><dt><code>-MP</code><dd><a name="index-MP-147"></a>This option instructs CPP to add a phony target for each dependency 285other than the main file, causing each to depend on nothing. These 286dummy rules work around errors <samp><span class="command">make</span></samp> gives if you remove header 287files without updating the <samp><span class="file">Makefile</span></samp> to match. 288 289 <p>This is typical output: 290 291 <pre class="smallexample"> test.o: test.c test.h 292 293 test.h: 294</pre> 295 <br><dt><code>-MT </code><var>target</var><dd><a name="index-MT-148"></a> 296Change the target of the rule emitted by dependency generation. By 297default CPP takes the name of the main input file, deletes any 298directory components and any file suffix such as ‘<samp><span class="samp">.c</span></samp>’, and 299appends the platform's usual object suffix. The result is the target. 300 301 <p>An <samp><span class="option">-MT</span></samp> option will set the target to be exactly the string you 302specify. If you want multiple targets, you can specify them as a single 303argument to <samp><span class="option">-MT</span></samp>, or use multiple <samp><span class="option">-MT</span></samp> options. 304 305 <p>For example, <samp><span class="option">-MT '$(objpfx)foo.o'<!-- /@w --></span></samp> might give 306 307 <pre class="smallexample"> $(objpfx)foo.o: foo.c 308</pre> 309 <br><dt><code>-MQ </code><var>target</var><dd><a name="index-MQ-149"></a> 310Same as <samp><span class="option">-MT</span></samp>, but it quotes any characters which are special to 311Make. <samp><span class="option">-MQ '$(objpfx)foo.o'<!-- /@w --></span></samp> gives 312 313 <pre class="smallexample"> $$(objpfx)foo.o: foo.c 314</pre> 315 <p>The default target is automatically quoted, as if it were given with 316<samp><span class="option">-MQ</span></samp>. 317 318 <br><dt><code>-MD</code><dd><a name="index-MD-150"></a><samp><span class="option">-MD</span></samp> is equivalent to <samp><span class="option">-M -MF </span><var>file</var></samp>, except that 319<samp><span class="option">-E</span></samp> is not implied. The driver determines <var>file</var> based on 320whether an <samp><span class="option">-o</span></samp> option is given. If it is, the driver uses its 321argument but with a suffix of <samp><span class="file">.d</span></samp>, otherwise it takes the name 322of the input file, removes any directory components and suffix, and 323applies a <samp><span class="file">.d</span></samp> suffix. 324 325 <p>If <samp><span class="option">-MD</span></samp> is used in conjunction with <samp><span class="option">-E</span></samp>, any 326<samp><span class="option">-o</span></samp> switch is understood to specify the dependency output file 327(see <a href="dashMF.html#dashMF">-MF</a>), but if used without <samp><span class="option">-E</span></samp>, each <samp><span class="option">-o</span></samp> 328is understood to specify a target object file. 329 330 <p>Since <samp><span class="option">-E</span></samp> is not implied, <samp><span class="option">-MD</span></samp> can be used to generate 331a dependency output file as a side-effect of the compilation process. 332 333 <br><dt><code>-MMD</code><dd><a name="index-MMD-151"></a>Like <samp><span class="option">-MD</span></samp> except mention only user header files, not system 334header files. 335 336 <br><dt><code>-x c</code><dt><code>-x c++</code><dt><code>-x objective-c</code><dt><code>-x assembler-with-cpp</code><dd><a name="index-x-152"></a>Specify the source language: C, C++, Objective-C, or assembly. This has 337nothing to do with standards conformance or extensions; it merely 338selects which base syntax to expect. If you give none of these options, 339cpp will deduce the language from the extension of the source file: 340‘<samp><span class="samp">.c</span></samp>’, ‘<samp><span class="samp">.cc</span></samp>’, ‘<samp><span class="samp">.m</span></samp>’, or ‘<samp><span class="samp">.S</span></samp>’. Some other common 341extensions for C++ and assembly are also recognized. If cpp does not 342recognize the extension, it will treat the file as C; this is the most 343generic mode. 344 345 <p><em>Note:</em> Previous versions of cpp accepted a <samp><span class="option">-lang</span></samp> option 346which selected both the language and the standards conformance level. 347This option has been removed, because it conflicts with the <samp><span class="option">-l</span></samp> 348option. 349 350 <br><dt><code>-std=</code><var>standard</var><dt><code>-ansi</code><dd><a name="index-ansi-153"></a><a name="index-std_003d-154"></a>Specify the standard to which the code should conform. Currently CPP 351knows about C and C++ standards; others may be added in the future. 352 353 <p><var>standard</var> 354may be one of: 355 <dl> 356<dt><code>c90</code><dt><code>c89</code><dt><code>iso9899:1990</code><dd>The ISO C standard from 1990. ‘<samp><span class="samp">c90</span></samp>’ is the customary shorthand for 357this version of the standard. 358 359 <p>The <samp><span class="option">-ansi</span></samp> option is equivalent to <samp><span class="option">-std=c90</span></samp>. 360 361 <br><dt><code>iso9899:199409</code><dd>The 1990 C standard, as amended in 1994. 362 363 <br><dt><code>iso9899:1999</code><dt><code>c99</code><dt><code>iso9899:199x</code><dt><code>c9x</code><dd>The revised ISO C standard, published in December 1999. Before 364publication, this was known as C9X. 365 366 <br><dt><code>c1x</code><dd>The next version of the ISO C standard, still under development. 367 368 <br><dt><code>gnu90</code><dt><code>gnu89</code><dd>The 1990 C standard plus GNU extensions. This is the default. 369 370 <br><dt><code>gnu99</code><dt><code>gnu9x</code><dd>The 1999 C standard plus GNU extensions. 371 372 <br><dt><code>gnu1x</code><dd>The next version of the ISO C standard, still under development, plus 373GNU extensions. 374 375 <br><dt><code>c++98</code><dd>The 1998 ISO C++ standard plus amendments. 376 377 <br><dt><code>gnu++98</code><dd>The same as <samp><span class="option">-std=c++98</span></samp> plus GNU extensions. This is the 378default for C++ code. 379</dl> 380 381 <br><dt><code>-I-</code><dd><a name="index-I_002d-155"></a>Split the include path. Any directories specified with <samp><span class="option">-I</span></samp> 382options before <samp><span class="option">-I-</span></samp> are searched only for headers requested with 383<code>#include "</code><var>file</var><code>"<!-- /@w --></code>; they are not searched for 384<code>#include <</code><var>file</var><code>><!-- /@w --></code>. If additional directories are 385specified with <samp><span class="option">-I</span></samp> options after the <samp><span class="option">-I-</span></samp>, those 386directories are searched for all ‘<samp><span class="samp">#include</span></samp>’ directives. 387 388 <p>In addition, <samp><span class="option">-I-</span></samp> inhibits the use of the directory of the current 389file directory as the first search directory for <code>#include "</code><var>file</var><code>"<!-- /@w --></code>. 390See <a href="Search-Path.html#Search-Path">Search Path</a>. 391This option has been deprecated. 392 393 <br><dt><code>-nostdinc</code><dd><a name="index-nostdinc-156"></a>Do not search the standard system directories for header files. 394Only the directories you have specified with <samp><span class="option">-I</span></samp> options 395(and the directory of the current file, if appropriate) are searched. 396 397 <br><dt><code>-nostdinc++</code><dd><a name="index-nostdinc_002b_002b-157"></a>Do not search for header files in the C++-specific standard directories, 398but do still search the other standard directories. (This option is 399used when building the C++ library.) 400 401 <br><dt><code>-include </code><var>file</var><dd><a name="index-include-158"></a>Process <var>file</var> as if <code>#include "file"</code> appeared as the first 402line of the primary source file. However, the first directory searched 403for <var>file</var> is the preprocessor's working directory <em>instead of</em> 404the directory containing the main source file. If not found there, it 405is searched for in the remainder of the <code>#include "..."</code> search 406chain as normal. 407 408 <p>If multiple <samp><span class="option">-include</span></samp> options are given, the files are included 409in the order they appear on the command line. 410 411 <br><dt><code>-imacros </code><var>file</var><dd><a name="index-imacros-159"></a>Exactly like <samp><span class="option">-include</span></samp>, except that any output produced by 412scanning <var>file</var> is thrown away. Macros it defines remain defined. 413This allows you to acquire all the macros from a header without also 414processing its declarations. 415 416 <p>All files specified by <samp><span class="option">-imacros</span></samp> are processed before all files 417specified by <samp><span class="option">-include</span></samp>. 418 419 <br><dt><code>-idirafter </code><var>dir</var><dd><a name="index-idirafter-160"></a>Search <var>dir</var> for header files, but do it <em>after</em> all 420directories specified with <samp><span class="option">-I</span></samp> and the standard system directories 421have been exhausted. <var>dir</var> is treated as a system include directory. 422If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced 423by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. 424 425 <br><dt><code>-iprefix </code><var>prefix</var><dd><a name="index-iprefix-161"></a>Specify <var>prefix</var> as the prefix for subsequent <samp><span class="option">-iwithprefix</span></samp> 426options. If the prefix represents a directory, you should include the 427final ‘<samp><span class="samp">/</span></samp>’. 428 429 <br><dt><code>-iwithprefix </code><var>dir</var><dt><code>-iwithprefixbefore </code><var>dir</var><dd><a name="index-iwithprefix-162"></a><a name="index-iwithprefixbefore-163"></a>Append <var>dir</var> to the prefix specified previously with 430<samp><span class="option">-iprefix</span></samp>, and add the resulting directory to the include search 431path. <samp><span class="option">-iwithprefixbefore</span></samp> puts it in the same place <samp><span class="option">-I</span></samp> 432would; <samp><span class="option">-iwithprefix</span></samp> puts it where <samp><span class="option">-idirafter</span></samp> would. 433 434 <br><dt><code>-isysroot </code><var>dir</var><dd><a name="index-isysroot-164"></a>This option is like the <samp><span class="option">--sysroot</span></samp> option, but applies only to 435header files (except for Darwin targets, where it applies to both header 436files and libraries). See the <samp><span class="option">--sysroot</span></samp> option for more 437information. 438 439 <br><dt><code>-imultilib </code><var>dir</var><dd><a name="index-imultilib-165"></a>Use <var>dir</var> as a subdirectory of the directory containing 440target-specific C++ headers. 441 442 <br><dt><code>-isystem </code><var>dir</var><dd><a name="index-isystem-166"></a>Search <var>dir</var> for header files, after all directories specified by 443<samp><span class="option">-I</span></samp> but before the standard system directories. Mark it 444as a system directory, so that it gets the same special treatment as 445is applied to the standard system directories. 446See <a href="System-Headers.html#System-Headers">System Headers</a>. 447If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced 448by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. 449 450 <br><dt><code>-iquote </code><var>dir</var><dd><a name="index-iquote-167"></a>Search <var>dir</var> only for header files requested with 451<code>#include "</code><var>file</var><code>"<!-- /@w --></code>; they are not searched for 452<code>#include <</code><var>file</var><code>><!-- /@w --></code>, before all directories specified by 453<samp><span class="option">-I</span></samp> and before the standard system directories. 454See <a href="Search-Path.html#Search-Path">Search Path</a>. 455If <var>dir</var> begins with <code>=</code>, then the <code>=</code> will be replaced 456by the sysroot prefix; see <samp><span class="option">--sysroot</span></samp> and <samp><span class="option">-isysroot</span></samp>. 457 458 <br><dt><code>-fdirectives-only</code><dd><a name="index-fdirectives_002donly-168"></a>When preprocessing, handle directives, but do not expand macros. 459 460 <p>The option's behavior depends on the <samp><span class="option">-E</span></samp> and <samp><span class="option">-fpreprocessed</span></samp> 461options. 462 463 <p>With <samp><span class="option">-E</span></samp>, preprocessing is limited to the handling of directives 464such as <code>#define</code>, <code>#ifdef</code>, and <code>#error</code>. Other 465preprocessor operations, such as macro expansion and trigraph 466conversion are not performed. In addition, the <samp><span class="option">-dD</span></samp> option is 467implicitly enabled. 468 469 <p>With <samp><span class="option">-fpreprocessed</span></samp>, predefinition of command line and most 470builtin macros is disabled. Macros such as <code>__LINE__</code>, which are 471contextually dependent, are handled normally. This enables compilation of 472files previously preprocessed with <code>-E -fdirectives-only</code>. 473 474 <p>With both <samp><span class="option">-E</span></samp> and <samp><span class="option">-fpreprocessed</span></samp>, the rules for 475<samp><span class="option">-fpreprocessed</span></samp> take precedence. This enables full preprocessing of 476files previously preprocessed with <code>-E -fdirectives-only</code>. 477 478 <br><dt><code>-fdollars-in-identifiers</code><dd><a name="index-fdollars_002din_002didentifiers-169"></a><a name="fdollars_002din_002didentifiers"></a>Accept ‘<samp><span class="samp">$</span></samp>’ in identifiers. 479See <a href="Identifier-characters.html#Identifier-characters">Identifier characters</a>. 480 481 <br><dt><code>-fextended-identifiers</code><dd><a name="index-fextended_002didentifiers-170"></a>Accept universal character names in identifiers. This option is 482experimental; in a future version of GCC, it will be enabled by 483default for C99 and C++. 484 485 <br><dt><code>-fpreprocessed</code><dd><a name="index-fpreprocessed-171"></a>Indicate to the preprocessor that the input file has already been 486preprocessed. This suppresses things like macro expansion, trigraph 487conversion, escaped newline splicing, and processing of most directives. 488The preprocessor still recognizes and removes comments, so that you can 489pass a file preprocessed with <samp><span class="option">-C</span></samp> to the compiler without 490problems. In this mode the integrated preprocessor is little more than 491a tokenizer for the front ends. 492 493 <p><samp><span class="option">-fpreprocessed</span></samp> is implicit if the input file has one of the 494extensions ‘<samp><span class="samp">.i</span></samp>’, ‘<samp><span class="samp">.ii</span></samp>’ or ‘<samp><span class="samp">.mi</span></samp>’. These are the 495extensions that GCC uses for preprocessed files created by 496<samp><span class="option">-save-temps</span></samp>. 497 498 <br><dt><code>-ftabstop=</code><var>width</var><dd><a name="index-ftabstop-172"></a>Set the distance between tab stops. This helps the preprocessor report 499correct column numbers in warnings or errors, even if tabs appear on the 500line. If the value is less than 1 or greater than 100, the option is 501ignored. The default is 8. 502 503 <br><dt><code>-fexec-charset=</code><var>charset</var><dd><a name="index-fexec_002dcharset-173"></a><a name="index-character-set_002c-execution-174"></a>Set the execution character set, used for string and character 504constants. The default is UTF-8. <var>charset</var> can be any encoding 505supported by the system's <code>iconv</code> library routine. 506 507 <br><dt><code>-fwide-exec-charset=</code><var>charset</var><dd><a name="index-fwide_002dexec_002dcharset-175"></a><a name="index-character-set_002c-wide-execution-176"></a>Set the wide execution character set, used for wide string and 508character constants. The default is UTF-32 or UTF-16, whichever 509corresponds to the width of <code>wchar_t</code>. As with 510<samp><span class="option">-fexec-charset</span></samp>, <var>charset</var> can be any encoding supported 511by the system's <code>iconv</code> library routine; however, you will have 512problems with encodings that do not fit exactly in <code>wchar_t</code>. 513 514 <br><dt><code>-finput-charset=</code><var>charset</var><dd><a name="index-finput_002dcharset-177"></a><a name="index-character-set_002c-input-178"></a>Set the input character set, used for translation from the character 515set of the input file to the source character set used by GCC. If the 516locale does not specify, or GCC cannot get this information from the 517locale, the default is UTF-8. This can be overridden by either the locale 518or this command line option. Currently the command line option takes 519precedence if there's a conflict. <var>charset</var> can be any encoding 520supported by the system's <code>iconv</code> library routine. 521 522 <br><dt><code>-fworking-directory</code><dd><a name="index-fworking_002ddirectory-179"></a><a name="index-fno_002dworking_002ddirectory-180"></a>Enable generation of linemarkers in the preprocessor output that will 523let the compiler know the current working directory at the time of 524preprocessing. When this option is enabled, the preprocessor will 525emit, after the initial linemarker, a second linemarker with the 526current working directory followed by two slashes. GCC will use this 527directory, when it's present in the preprocessed input, as the 528directory emitted as the current working directory in some debugging 529information formats. This option is implicitly enabled if debugging 530information is enabled, but this can be inhibited with the negated 531form <samp><span class="option">-fno-working-directory</span></samp>. If the <samp><span class="option">-P</span></samp> flag is 532present in the command line, this option has no effect, since no 533<code>#line</code> directives are emitted whatsoever. 534 535 <br><dt><code>-fno-show-column</code><dd><a name="index-fno_002dshow_002dcolumn-181"></a>Do not print column numbers in diagnostics. This may be necessary if 536diagnostics are being scanned by a program that does not understand the 537column numbers, such as <samp><span class="command">dejagnu</span></samp>. 538 539 <br><dt><code>-A </code><var>predicate</var><code>=</code><var>answer</var><dd><a name="index-A-182"></a>Make an assertion with the predicate <var>predicate</var> and answer 540<var>answer</var>. This form is preferred to the older form <samp><span class="option">-A 541</span><var>predicate</var><span class="option">(</span><var>answer</var><span class="option">)</span></samp>, which is still supported, because 542it does not use shell special characters. 543See <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>. 544 545 <br><dt><code>-A -</code><var>predicate</var><code>=</code><var>answer</var><dd>Cancel an assertion with the predicate <var>predicate</var> and answer 546<var>answer</var>. 547 548 <br><dt><code>-dCHARS</code><dd><var>CHARS</var> is a sequence of one or more of the following characters, 549and must not be preceded by a space. Other characters are interpreted 550by the compiler proper, or reserved for future versions of GCC, and so 551are silently ignored. If you specify characters whose behavior 552conflicts, the result is undefined. 553 554 <dl> 555<dt>‘<samp><span class="samp">M</span></samp>’<dd><a name="index-dM-183"></a>Instead of the normal output, generate a list of ‘<samp><span class="samp">#define</span></samp>’ 556directives for all the macros defined during the execution of the 557preprocessor, including predefined macros. This gives you a way of 558finding out what is predefined in your version of the preprocessor. 559Assuming you have no file <samp><span class="file">foo.h</span></samp>, the command 560 561 <pre class="smallexample"> touch foo.h; cpp -dM foo.h 562</pre> 563 <p class="noindent">will show all the predefined macros. 564 565 <p>If you use <samp><span class="option">-dM</span></samp> without the <samp><span class="option">-E</span></samp> option, <samp><span class="option">-dM</span></samp> is 566interpreted as a synonym for <samp><span class="option">-fdump-rtl-mach</span></samp>. 567See <a href="../gcc/Debugging-Options.html#Debugging-Options">Debugging Options</a>. 568 569 <br><dt>‘<samp><span class="samp">D</span></samp>’<dd><a name="index-dD-184"></a>Like ‘<samp><span class="samp">M</span></samp>’ except in two respects: it does <em>not</em> include the 570predefined macros, and it outputs <em>both</em> the ‘<samp><span class="samp">#define</span></samp>’ 571directives and the result of preprocessing. Both kinds of output go to 572the standard output file. 573 574 <br><dt>‘<samp><span class="samp">N</span></samp>’<dd><a name="index-dN-185"></a>Like ‘<samp><span class="samp">D</span></samp>’, but emit only the macro names, not their expansions. 575 576 <br><dt>‘<samp><span class="samp">I</span></samp>’<dd><a name="index-dI-186"></a>Output ‘<samp><span class="samp">#include</span></samp>’ directives in addition to the result of 577preprocessing. 578 579 <br><dt>‘<samp><span class="samp">U</span></samp>’<dd><a name="index-dU-187"></a>Like ‘<samp><span class="samp">D</span></samp>’ except that only macros that are expanded, or whose 580definedness is tested in preprocessor directives, are output; the 581output is delayed until the use or test of the macro; and 582‘<samp><span class="samp">#undef</span></samp>’ directives are also output for macros tested but 583undefined at the time. 584</dl> 585 586 <br><dt><code>-P</code><dd><a name="index-P-188"></a>Inhibit generation of linemarkers in the output from the preprocessor. 587This might be useful when running the preprocessor on something that is 588not C code, and will be sent to a program which might be confused by the 589linemarkers. 590See <a href="Preprocessor-Output.html#Preprocessor-Output">Preprocessor Output</a>. 591 592 <br><dt><code>-C</code><dd><a name="index-C-189"></a>Do not discard comments. All comments are passed through to the output 593file, except for comments in processed directives, which are deleted 594along with the directive. 595 596 <p>You should be prepared for side effects when using <samp><span class="option">-C</span></samp>; it 597causes the preprocessor to treat comments as tokens in their own right. 598For example, comments appearing at the start of what would be a 599directive line have the effect of turning that line into an ordinary 600source line, since the first token on the line is no longer a ‘<samp><span class="samp">#</span></samp>’. 601 602 <br><dt><code>-CC</code><dd>Do not discard comments, including during macro expansion. This is 603like <samp><span class="option">-C</span></samp>, except that comments contained within macros are 604also passed through to the output file where the macro is expanded. 605 606 <p>In addition to the side-effects of the <samp><span class="option">-C</span></samp> option, the 607<samp><span class="option">-CC</span></samp> option causes all C++-style comments inside a macro 608to be converted to C-style comments. This is to prevent later use 609of that macro from inadvertently commenting out the remainder of 610the source line. 611 612 <p>The <samp><span class="option">-CC</span></samp> option is generally used to support lint comments. 613 614 <br><dt><code>-traditional-cpp</code><dd><a name="index-traditional_002dcpp-190"></a>Try to imitate the behavior of old-fashioned C preprocessors, as 615opposed to ISO C preprocessors. 616See <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. 617 618 <br><dt><code>-trigraphs</code><dd><a name="index-trigraphs-191"></a>Process trigraph sequences. 619See <a href="Initial-processing.html#Initial-processing">Initial processing</a>. 620 621 <br><dt><code>-remap</code><dd><a name="index-remap-192"></a>Enable special code to work around file systems which only permit very 622short file names, such as MS-DOS. 623 624 <dt><code>--help</code><dt><code>--target-help</code><dd><a name="index-help-193"></a><a name="index-target_002dhelp-194"></a>Print text describing all the command line options instead of 625preprocessing anything. 626 627 <br><dt><code>-v</code><dd><a name="index-v-195"></a>Verbose mode. Print out GNU CPP's version number at the beginning of 628execution, and report the final form of the include path. 629 630 <br><dt><code>-H</code><dd><a name="index-H-196"></a>Print the name of each header file used, in addition to other normal 631activities. Each name is indented to show how deep in the 632‘<samp><span class="samp">#include</span></samp>’ stack it is. Precompiled header files are also 633printed, even if they are found to be invalid; an invalid precompiled 634header file is printed with ‘<samp><span class="samp">...x</span></samp>’ and a valid one with ‘<samp><span class="samp">...!</span></samp>’ . 635 636 <br><dt><code>-version</code><dt><code>--version</code><dd><a name="index-version-197"></a>Print out GNU CPP's version number. With one dash, proceed to 637preprocess as normal. With two dashes, exit immediately. 638</dl> 639 <!-- man end --> 640 641 </body></html> 642 643