]>
Commit | Line | Data |
---|---|---|
fd939e46 | 1 | .\" Automatically generated by Pod::Man version 1.1 |
445c435a | 2 | .\" Wed Jan 24 19:43:25 2001 |
fd939e46 JM |
3 | .\" |
4 | .\" Standard preamble: | |
5 | .\" ====================================================================== | |
6 | .de Sh \" Subsection heading | |
6251188c ZW |
7 | .br |
8 | .if t .Sp | |
9 | .ne 5 | |
10 | .PP | |
11 | \fB\\$1\fR | |
12 | .PP | |
13 | .. | |
fd939e46 | 14 | .de Sp \" Vertical space (when we can't use .PP) |
6251188c ZW |
15 | .if t .sp .5v |
16 | .if n .sp | |
17 | .. | |
fd939e46 | 18 | .de Ip \" List item |
6251188c ZW |
19 | .br |
20 | .ie \\n(.$>=3 .ne \\$3 | |
21 | .el .ne 3 | |
22 | .IP "\\$1" \\$2 | |
23 | .. | |
fd939e46 | 24 | .de Vb \" Begin verbatim text |
6251188c ZW |
25 | .ft CW |
26 | .nf | |
27 | .ne \\$1 | |
28 | .. | |
fd939e46 | 29 | .de Ve \" End verbatim text |
6251188c ZW |
30 | .ft R |
31 | ||
32 | .fi | |
33 | .. | |
fd939e46 JM |
34 | .\" Set up some character translations and predefined strings. \*(-- will |
35 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
36 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
37 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used | |
38 | .\" to do unbreakable dashes and therefore won't be available. \*(C` and | |
39 | .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> | |
6251188c | 40 | .tr \(*W-|\(bv\*(Tr |
fd939e46 | 41 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
6251188c | 42 | .ie n \{\ |
fd939e46 JM |
43 | . ds -- \(*W- |
44 | . ds PI pi | |
45 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
46 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
47 | . ds L" "" | |
48 | . ds R" "" | |
49 | . ds C` "" | |
50 | . ds C' "" | |
6251188c ZW |
51 | 'br\} |
52 | .el\{\ | |
fd939e46 JM |
53 | . ds -- \|\(em\| |
54 | . ds PI \(*p | |
55 | . ds L" `` | |
56 | . ds R" '' | |
6251188c | 57 | 'br\} |
fd939e46 JM |
58 | .\" |
59 | .\" If the F register is turned on, we'll generate index entries on stderr | |
60 | .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and | |
61 | .\" index entries marked with X<> in POD. Of course, you'll have to process | |
62 | .\" the output yourself in some meaningful fashion. | |
63 | .if \nF \{\ | |
64 | . de IX | |
65 | . tm Index:\\$1\t\\n%\t"\\$2" | |
6251188c | 66 | .. |
fd939e46 JM |
67 | . nr % 0 |
68 | . rr F | |
69 | .\} | |
70 | .\" | |
71 | .\" For nroff, turn off justification. Always turn off hyphenation; it | |
72 | .\" makes way too many mistakes in technical documents. | |
73 | .hy 0 | |
74 | .if n .na | |
75 | .\" | |
76 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
77 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
6251188c | 78 | .bd B 3 |
fd939e46 | 79 | . \" fudge factors for nroff and troff |
6251188c | 80 | .if n \{\ |
fd939e46 JM |
81 | . ds #H 0 |
82 | . ds #V .8m | |
83 | . ds #F .3m | |
84 | . ds #[ \f1 | |
85 | . ds #] \fP | |
6251188c ZW |
86 | .\} |
87 | .if t \{\ | |
fd939e46 JM |
88 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
89 | . ds #V .6m | |
90 | . ds #F 0 | |
91 | . ds #[ \& | |
92 | . ds #] \& | |
6251188c | 93 | .\} |
fd939e46 | 94 | . \" simple accents for nroff and troff |
6251188c | 95 | .if n \{\ |
fd939e46 JM |
96 | . ds ' \& |
97 | . ds ` \& | |
98 | . ds ^ \& | |
99 | . ds , \& | |
100 | . ds ~ ~ | |
101 | . ds / | |
6251188c ZW |
102 | .\} |
103 | .if t \{\ | |
fd939e46 JM |
104 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
105 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
106 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
107 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
108 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
109 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
6251188c | 110 | .\} |
fd939e46 | 111 | . \" troff and (daisy-wheel) nroff accents |
6251188c ZW |
112 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
113 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
6251188c ZW |
114 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
115 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
116 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
117 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
118 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
119 | .ds ae a\h'-(\w'a'u*4/10)'e | |
120 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
fd939e46 | 121 | . \" corrections for vroff |
6251188c ZW |
122 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
123 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
fd939e46 | 124 | . \" for low resolution devices (crt and lpr) |
6251188c ZW |
125 | .if \n(.H>23 .if \n(.V>19 \ |
126 | \{\ | |
fd939e46 JM |
127 | . ds : e |
128 | . ds 8 ss | |
129 | . ds o a | |
130 | . ds d- d\h'-1'\(ga | |
131 | . ds D- D\h'-1'\(hy | |
132 | . ds th \o'bp' | |
133 | . ds Th \o'LP' | |
134 | . ds ae ae | |
135 | . ds Ae AE | |
6251188c ZW |
136 | .\} |
137 | .rm #[ #] #H #V #F C | |
fd939e46 JM |
138 | .\" ====================================================================== |
139 | .\" | |
140 | .IX Title "CPP 1" | |
445c435a | 141 | .TH CPP 1 "gcc-2.97" "2001-01-24" "GNU" |
fd939e46 | 142 | .UC |
6251188c ZW |
143 | .SH "NAME" |
144 | cpp \- The C Preprocessor | |
145 | .SH "SYNOPSIS" | |
fd939e46 | 146 | .IX Header "SYNOPSIS" |
6251188c ZW |
147 | cpp [\fB\-P\fR] [\fB\-C\fR] [\fB\-gcc\fR] [\fB\-traditional\fR] |
148 | [\fB\-undef\fR] [\fB\-trigraphs\fR] [\fB\-pedantic\fR] | |
149 | [\fB\-W\fR\fIwarn\fR...] [\fB\-I\fR\fIdir\fR...] | |
150 | [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] | |
151 | [\fB\-A\fR\fIpredicate\fR(\fIanswer\fR)] | |
5490d604 JM |
152 | [\fB\-M\fR|\fB\-MM\fR][\fB\-MG\fR][\fB\-MF\fR\fIfilename\fR] |
153 | [\fB\-MP\fR][\fB\-MQ\fR\fItarget\fR...][\fB\-MT\fR\fItarget\fR...] | |
6251188c ZW |
154 | [\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR] |
155 | \fIinfile\fR \fIoutfile\fR | |
156 | .PP | |
157 | Only the most useful options are listed here; see below for the remainder. | |
158 | .SH "DESCRIPTION" | |
fd939e46 | 159 | .IX Header "DESCRIPTION" |
5ef865d5 ZW |
160 | The C preprocessor is a \fImacro processor\fR that is used automatically |
161 | by the C compiler to transform your program before actual compilation. | |
162 | It is called a macro processor because it allows you to define | |
fd939e46 | 163 | \&\fImacros\fR, which are brief abbreviations for longer constructs. |
6251188c | 164 | .PP |
5ef865d5 ZW |
165 | The C preprocessor is intended only for macro processing of C, \*(C+ and |
166 | Objective C source files. For macro processing of other files, you are | |
167 | strongly encouraged to use alternatives like M4, which will likely give | |
168 | you better results and avoid many problems. For example, normally the C | |
169 | preprocessor does not preserve arbitrary whitespace verbatim, but | |
170 | instead replaces each sequence with a single space. | |
171 | .PP | |
fd939e46 | 172 | For use on C-like source files, the C preprocessor provides four |
5ef865d5 | 173 | separate facilities that you can use as you see fit: |
6251188c ZW |
174 | .Ip "\(bu" 4 |
175 | Inclusion of header files. These are files of declarations that can be | |
176 | substituted into your program. | |
177 | .Ip "\(bu" 4 | |
178 | Macro expansion. You can define \fImacros\fR, which are abbreviations | |
179 | for arbitrary fragments of C code, and then the C preprocessor will | |
180 | replace the macros with their definitions throughout the program. | |
181 | .Ip "\(bu" 4 | |
182 | Conditional compilation. Using special preprocessing directives, you | |
183 | can include or exclude parts of the program according to various | |
184 | conditions. | |
185 | .Ip "\(bu" 4 | |
5ef865d5 ZW |
186 | Line control. If you use a program to combine or rearrange source files |
187 | into an intermediate file which is then compiled, you can use line | |
188 | control to inform the compiler of where each source line originally came | |
189 | from. | |
6251188c ZW |
190 | .PP |
191 | C preprocessors vary in some details. This manual discusses the \s-1GNU\s0 C | |
5ef865d5 ZW |
192 | preprocessor, which provides a small superset of the features of \s-1ISO\s0 |
193 | Standard C. | |
6251188c | 194 | .PP |
5ef865d5 ZW |
195 | In its default mode, the \s-1GNU\s0 C preprocessor does not do a few things |
196 | required by the standard. These are features which are rarely, if ever, | |
197 | used, and may cause surprising changes to the meaning of a program which | |
198 | does not expect them. To get strict \s-1ISO\s0 Standard C, you should use the | |
fd939e46 | 199 | \&\fB\-std=c89\fR or \fB\-std=c99\fR options, depending on which version |
5ef865d5 ZW |
200 | of the standard you want. To get all the mandatory diagnostics, you |
201 | must also use \fB\-pedantic\fR. | |
6251188c | 202 | .SH "OPTIONS" |
fd939e46 | 203 | .IX Header "OPTIONS" |
6251188c | 204 | The C preprocessor expects two file names as arguments, \fIinfile\fR and |
fd939e46 | 205 | \&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any |
5ef865d5 ZW |
206 | other files it specifies with \fB#include\fR. All the output generated |
207 | by the combined input files is written in \fIoutfile\fR. | |
6251188c | 208 | .PP |
fd939e46 JM |
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 | |
6251188c | 211 | means to write to standard output. Also, if either file is omitted, it |
fd939e46 | 212 | means the same as if \fB-\fR had been specified for that file. |
6251188c ZW |
213 | .PP |
214 | Here is a table of command options accepted by the C preprocessor. | |
215 | These options can also be given when compiling a C program; they are | |
216 | passed along automatically to the preprocessor when it is invoked by the | |
217 | compiler. | |
218 | .Ip "\fB\-P\fR" 4 | |
fd939e46 | 219 | .IX Item "-P" |
5ef865d5 ZW |
220 | Inhibit generation of \fB#\fR\-lines with line-number information in the |
221 | output from the preprocessor. This might be useful when running the | |
222 | preprocessor on something that is not C code and will be sent to a | |
223 | program which might be confused by the \fB#\fR\-lines. | |
6251188c | 224 | .Ip "\fB\-C\fR" 4 |
fd939e46 | 225 | .IX Item "-C" |
5ef865d5 ZW |
226 | Do not discard comments. All comments are passed through to the output |
227 | file, except for comments in processed directives, which are deleted | |
228 | along with the directive. Comments appearing in the expansion list of a | |
229 | macro will be preserved, and appear in place wherever the macro is | |
230 | invoked. | |
231 | .Sp | |
232 | You should be prepared for side effects when using \fB\-C\fR; it causes | |
233 | the preprocessor to treat comments as tokens in their own right. For | |
234 | example, macro redefinitions that were trivial when comments were | |
235 | replaced by a single space might become significant when comments are | |
236 | retained. Also, comments appearing at the start of what would be a | |
237 | directive line have the effect of turning that line into an ordinary | |
238 | source line, since the first token on the line is no longer a \fB#\fR. | |
6251188c | 239 | .Ip "\fB\-traditional\fR" 4 |
fd939e46 | 240 | .IX Item "-traditional" |
5ef865d5 ZW |
241 | Try to imitate the behavior of old-fashioned C, as opposed to \s-1ISO\s0 C. |
242 | .RS 4 | |
243 | .Ip "\(bu" 4 | |
244 | Traditional macro expansion pays no attention to single-quote or | |
245 | double-quote characters; macro argument symbols are replaced by the | |
6251188c ZW |
246 | argument values even when they appear within apparent string or |
247 | character constants. | |
5ef865d5 | 248 | .Ip "\(bu" 4 |
6251188c ZW |
249 | Traditionally, it is permissible for a macro expansion to end in the |
250 | middle of a string or character constant. The constant continues into | |
251 | the text surrounding the macro call. | |
5ef865d5 | 252 | .Ip "\(bu" 4 |
6251188c ZW |
253 | However, traditionally the end of the line terminates a string or |
254 | character constant, with no error. | |
5ef865d5 ZW |
255 | .Ip "\(bu" 4 |
256 | In traditional C, a comment is equivalent to no text at all. (In \s-1ISO\s0 | |
6251188c | 257 | C, a comment counts as whitespace.) |
5ef865d5 | 258 | .Ip "\(bu" 4 |
fd939e46 | 259 | Traditional C does not have the concept of a ``preprocessing number''. |
6251188c ZW |
260 | It considers \fB1.0e+4\fR to be three tokens: \fB1.0e\fR, \fB+\fR, |
261 | and \fB4\fR. | |
5ef865d5 | 262 | .Ip "\(bu" 4 |
6251188c ZW |
263 | A macro is not suppressed within its own definition, in traditional C. |
264 | Thus, any macro that is used recursively inevitably causes an error. | |
5ef865d5 | 265 | .Ip "\(bu" 4 |
6251188c ZW |
266 | The character \fB#\fR has no special meaning within a macro definition |
267 | in traditional C. | |
5ef865d5 | 268 | .Ip "\(bu" 4 |
6251188c ZW |
269 | In traditional C, the text at the end of a macro expansion can run |
270 | together with the text after the macro call, to produce a single token. | |
5ef865d5 ZW |
271 | (This is impossible in \s-1ISO\s0 C.) |
272 | .Ip "\(bu" 4 | |
273 | None of the \s-1GNU\s0 extensions to the preprocessor are available in | |
fd939e46 | 274 | \&\fB\-traditional\fR mode. |
5ef865d5 | 275 | .RE |
fd939e46 JM |
276 | .RS 4 |
277 | .Sp | |
5ef865d5 ZW |
278 | Use the \fB\-traditional\fR option when preprocessing Fortran code, so |
279 | that single-quotes and double-quotes within Fortran comment lines (which | |
280 | are generally not recognized as such by the preprocessor) do not cause | |
281 | diagnostics about unterminated character or string constants. | |
6251188c | 282 | .Sp |
5ef865d5 | 283 | However, this option does not prevent diagnostics about unterminated |
fd939e46 | 284 | comments when a C-style comment appears to start, but not end, within |
5ef865d5 | 285 | Fortran-style commentary. |
6251188c ZW |
286 | .Sp |
287 | So, the following Fortran comment lines are accepted with | |
fd939e46 | 288 | \&\fB\-traditional\fR: |
6251188c ZW |
289 | .Sp |
290 | .Vb 3 | |
291 | \& C This isn't an unterminated character constant | |
292 | \& C Neither is "20000000000, an octal constant | |
293 | \& C in some dialects of Fortran | |
294 | .Ve | |
5ef865d5 ZW |
295 | However, this type of comment line will likely produce a diagnostic, or |
296 | at least unexpected output from the preprocessor, due to the | |
297 | unterminated comment: | |
6251188c ZW |
298 | .Sp |
299 | .Vb 2 | |
300 | \& C Some Fortran compilers accept /* as starting | |
301 | \& C an inline comment. | |
302 | .Ve | |
fd939e46 | 303 | Note that \f(CW\*(C`g77\*(C'\fR automatically supplies the \fB\-traditional\fR |
5ef865d5 | 304 | option when it invokes the preprocessor. However, a future version of |
fd939e46 JM |
305 | \&\f(CW\*(C`g77\*(C'\fR might use a different, more-Fortran-aware preprocessor in |
306 | place of \f(CW\*(C`cpp\*(C'\fR. | |
307 | .RE | |
6251188c | 308 | .Ip "\fB\-trigraphs\fR" 4 |
fd939e46 | 309 | .IX Item "-trigraphs" |
5ef865d5 ZW |
310 | Process \s-1ISO\s0 standard trigraph sequences. These are three-character |
311 | sequences, all starting with \fB??\fR, that are defined by \s-1ISO\s0 C to | |
6251188c | 312 | stand for single characters. For example, \fB??/\fR stands for |
fd939e46 | 313 | \&\fB\e\fR, so \fB'??/n'\fR is a character constant for a newline. By |
5ef865d5 ZW |
314 | default, \s-1GCC\s0 ignores trigraphs, but in standard-conforming modes it |
315 | converts them. See the \fB\-std\fR option. | |
6251188c | 316 | .Sp |
5ef865d5 ZW |
317 | The nine trigraph sequences are |
318 | .RS 4 | |
fd939e46 JM |
319 | .Ip "\fB??(\fR" 4 |
320 | .IX Item "??(" | |
321 | -> \fB[\fR | |
322 | .Ip "\fB??)\fR" 4 | |
323 | .IX Item "??)" | |
324 | -> \fB]\fR | |
325 | .Ip "\fB??<\fR" 4 | |
326 | .IX Item "??<" | |
327 | -> \fB{\fR | |
328 | .Ip "\fB??>\fR" 4 | |
329 | .IX Item "??>" | |
330 | -> \fB}\fR | |
331 | .Ip "\fB??=\fR" 4 | |
332 | .IX Item "??=" | |
333 | -> \fB#\fR | |
334 | .Ip "\fB??/\fR" 4 | |
335 | .IX Item "??/" | |
336 | -> \fB\e\fR | |
337 | .Ip "\fB??'\fR" 4 | |
338 | .IX Item "??'" | |
339 | -> \fB^\fR | |
340 | .Ip "\fB??!\fR" 4 | |
341 | .IX Item "??!" | |
342 | -> \fB|\fR | |
343 | .Ip "\fB??-\fR" 4 | |
344 | .IX Item "??-" | |
345 | -> \fB~\fR | |
5ef865d5 | 346 | .RE |
fd939e46 JM |
347 | .RS 4 |
348 | .Sp | |
5ef865d5 ZW |
349 | Trigraph support is not popular, so many compilers do not implement it |
350 | properly. Portable code should not rely on trigraphs being either | |
351 | converted or ignored. | |
fd939e46 | 352 | .RE |
6251188c | 353 | .Ip "\fB\-pedantic\fR" 4 |
fd939e46 | 354 | .IX Item "-pedantic" |
5ef865d5 | 355 | Issue warnings required by the \s-1ISO\s0 C standard in certain cases such |
6251188c ZW |
356 | as when text other than a comment follows \fB#else\fR or \fB#endif\fR. |
357 | .Ip "\fB\-pedantic-errors\fR" 4 | |
fd939e46 | 358 | .IX Item "-pedantic-errors" |
6251188c ZW |
359 | Like \fB\-pedantic\fR, except that errors are produced rather than |
360 | warnings. | |
6251188c | 361 | .Ip "\fB\-Wcomment\fR" 4 |
fd939e46 JM |
362 | .IX Item "-Wcomment" |
363 | .PD 0 | |
5ef865d5 | 364 | .Ip "\fB\-Wcomments\fR" 4 |
fd939e46 JM |
365 | .IX Item "-Wcomments" |
366 | .PD | |
5ef865d5 | 367 | (Both forms have the same effect). |
6251188c | 368 | Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR |
5ef865d5 ZW |
369 | comment, or whenever a backslash-newline appears in a \fB//\fR comment. |
370 | .Ip "\fB\-Wtrigraphs\fR" 4 | |
fd939e46 | 371 | .IX Item "-Wtrigraphs" |
5ef865d5 | 372 | Warn if any trigraphs are encountered. This option used to take effect |
fd939e46 JM |
373 | only if \fB\-trigraphs\fR was also specified, but now works |
374 | independently. Warnings are not given for trigraphs within comments, as | |
375 | we feel this is obnoxious. | |
5ef865d5 | 376 | .Ip "\fB\-Wwhite-space\fR" 4 |
fd939e46 | 377 | .IX Item "-Wwhite-space" |
5ef865d5 ZW |
378 | Warn about possible white space confusion, e.g. white space between a |
379 | backslash and a newline. | |
6251188c | 380 | .Ip "\fB\-Wall\fR" 4 |
fd939e46 | 381 | .IX Item "-Wall" |
5ef865d5 ZW |
382 | Requests \fB\-Wcomment\fR, \fB\-Wtrigraphs\fR, and \fB\-Wwhite-space\fR |
383 | (but not \fB\-Wtraditional\fR or \fB\-Wundef\fR). | |
6251188c | 384 | .Ip "\fB\-Wtraditional\fR" 4 |
fd939e46 | 385 | .IX Item "-Wtraditional" |
6251188c | 386 | Warn about certain constructs that behave differently in traditional and |
fd939e46 | 387 | \&\s-1ISO\s0 C. |
6251188c | 388 | .Ip "\fB\-Wundef\fR" 4 |
fd939e46 | 389 | .IX Item "-Wundef" |
6251188c | 390 | Warn if an undefined identifier is evaluated in an \fB#if\fR directive. |
fd939e46 JM |
391 | .Ip "\fB\-I\fR \fIdirectory\fR" 4 |
392 | .IX Item "-I directory" | |
6251188c | 393 | Add the directory \fIdirectory\fR to the head of the list of |
fd939e46 | 394 | directories to be searched for header files. |
6251188c ZW |
395 | This can be used to override a system header file, substituting your |
396 | own version, since these directories are searched before the system | |
397 | header file directories. If you use more than one \fB\-I\fR option, | |
398 | the directories are scanned in left-to-right order; the standard | |
399 | system directories come after. | |
400 | .Ip "\fB\-I-\fR" 4 | |
fd939e46 | 401 | .IX Item "-I-" |
6251188c | 402 | Any directories specified with \fB\-I\fR options before the \fB\-I-\fR |
fd939e46 JM |
403 | option are searched only for the case of \fB#include "\fR\fIfile\fR\fB"\fR; |
404 | they are not searched for \fB#include <\fR\fIfile\fR\fB>\fR. | |
6251188c ZW |
405 | .Sp |
406 | If additional directories are specified with \fB\-I\fR options after | |
407 | the \fB\-I-\fR, these directories are searched for all \fB#include\fR | |
408 | directives. | |
409 | .Sp | |
410 | In addition, the \fB\-I-\fR option inhibits the use of the current | |
fd939e46 | 411 | directory as the first search directory for \fB#include "\fR\fIfile\fR\fB"\fR. |
6251188c ZW |
412 | Therefore, the current directory is searched only if it is requested |
413 | explicitly with \fB\-I.\fR. Specifying both \fB\-I-\fR and \fB\-I.\fR | |
414 | allows you to control precisely which directories are searched before | |
415 | the current one and which are searched after. | |
416 | .Ip "\fB\-nostdinc\fR" 4 | |
fd939e46 | 417 | .IX Item "-nostdinc" |
6251188c ZW |
418 | Do not search the standard system directories for header files. |
419 | Only the directories you have specified with \fB\-I\fR options | |
420 | (and the current directory, if appropriate) are searched. | |
5490d604 JM |
421 | .Sp |
422 | By using both \fB\-nostdinc\fR and \fB\-I-\fR, you can limit the include-file | |
423 | search path to only those directories you specify explicitly. | |
6251188c | 424 | .Ip "\fB\-nostdinc++\fR" 4 |
fd939e46 | 425 | .IX Item "-nostdinc++" |
6251188c | 426 | Do not search for header files in the \*(C+\-specific standard directories, |
5ef865d5 ZW |
427 | but do still search the other standard directories. (This option is |
428 | used when building the \*(C+ library.) | |
6251188c | 429 | .Ip "\fB\-remap\fR" 4 |
fd939e46 | 430 | .IX Item "-remap" |
6251188c ZW |
431 | When searching for a header file in a directory, remap file names if a |
432 | file named \fIheader.gcc\fR exists in that directory. This can be used | |
433 | to work around limitations of file systems with file name restrictions. | |
434 | The \fIheader.gcc\fR file should contain a series of lines with two | |
435 | tokens on each line: the first token is the name to map, and the second | |
436 | token is the actual name to use. | |
fd939e46 JM |
437 | .Ip "\fB\-D\fR \fIname\fR" 4 |
438 | .IX Item "-D name" | |
6251188c | 439 | Predefine \fIname\fR as a macro, with definition \fB1\fR. |
fd939e46 JM |
440 | .Ip "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4 |
441 | .IX Item "-D name=definition" | |
6251188c ZW |
442 | Predefine \fIname\fR as a macro, with definition \fIdefinition\fR. |
443 | There are no restrictions on the contents of \fIdefinition\fR, but if | |
444 | you are invoking the preprocessor from a shell or shell-like program you | |
445 | may need to use the shell's quoting syntax to protect characters such as | |
446 | spaces that have a meaning in the shell syntax. If you use more than | |
447 | one \fB\-D\fR for the same \fIname\fR, the rightmost definition takes | |
448 | effect. | |
5490d604 JM |
449 | .Sp |
450 | Any \fB\-D\fR and \fB\-U\fR options on the command line are processed in | |
451 | order, and always before \fB\-imacros\fR \fIfile\fR, regardless of the | |
452 | order in which they are written. | |
fd939e46 JM |
453 | .Ip "\fB\-U\fR \fIname\fR" 4 |
454 | .IX Item "-U name" | |
5490d604 JM |
455 | Do not predefine \fIname\fR. |
456 | .Sp | |
457 | Any \fB\-D\fR and \fB\-U\fR options on the command line are processed in | |
458 | order, and always before \fB\-imacros\fR \fIfile\fR, regardless of the | |
459 | order in which they are written. | |
6251188c | 460 | .Ip "\fB\-undef\fR" 4 |
fd939e46 | 461 | .IX Item "-undef" |
6251188c ZW |
462 | Do not predefine any nonstandard macros. |
463 | .Ip "\fB\-gcc\fR" 4 | |
fd939e46 | 464 | .IX Item "-gcc" |
3ea8083f | 465 | Define the macros \fI_\|_GNUC_\|_\fR, \fI_\|_GNUC_MINOR_\|_\fR and |
fd939e46 JM |
466 | \&\fI_\|_GNUC_PATCHLEVEL_\|_\fR. These are defined automatically when you use |
467 | \&\fBgcc \-E\fR; you can turn them off in that case with \fB\-no-gcc\fR. | |
468 | .Ip "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4 | |
469 | .IX Item "-A predicate=answer" | |
6251188c | 470 | Make an assertion with the predicate \fIpredicate\fR and answer |
fd939e46 JM |
471 | \&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR |
472 | \&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because | |
473 | it does not use shell special characters. | |
474 | .Ip "\fB\-A -\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4 | |
475 | .IX Item "-A -predicate=answer" | |
5ef865d5 | 476 | Disable an assertion with the predicate \fIpredicate\fR and answer |
fd939e46 | 477 | \&\fIanswer\fR. Specifying no predicate, by \fB\-A-\fR or \fB\-A -\fR, |
5ef865d5 ZW |
478 | disables all predefined assertions and all assertions preceding it on |
479 | the command line; and also undefines all predefined macros and all | |
480 | macros preceding it on the command line. | |
6251188c | 481 | .Ip "\fB\-dM\fR" 4 |
fd939e46 | 482 | .IX Item "-dM" |
6251188c | 483 | Instead of outputting the result of preprocessing, output a list of |
fd939e46 | 484 | \&\fB#define\fR directives for all the macros defined during the |
6251188c ZW |
485 | execution of the preprocessor, including predefined macros. This gives |
486 | you a way of finding out what is predefined in your version of the | |
487 | preprocessor; assuming you have no file \fBfoo.h\fR, the command | |
488 | .Sp | |
489 | .Vb 1 | |
490 | \& touch foo.h; cpp -dM foo.h | |
491 | .Ve | |
492 | will show the values of any predefined macros. | |
493 | .Ip "\fB\-dD\fR" 4 | |
fd939e46 | 494 | .IX Item "-dD" |
6251188c ZW |
495 | Like \fB\-dM\fR except in two respects: it does \fInot\fR include the |
496 | predefined macros, and it outputs \fIboth\fR the \fB#define\fR | |
497 | directives and the result of preprocessing. Both kinds of output go to | |
498 | the standard output file. | |
5ef865d5 | 499 | .Ip "\fB\-dN\fR" 4 |
fd939e46 | 500 | .IX Item "-dN" |
5ef865d5 | 501 | Like \fB\-dD\fR, but emit only the macro names, not their expansions. |
6251188c | 502 | .Ip "\fB\-dI\fR" 4 |
fd939e46 | 503 | .IX Item "-dI" |
5ef865d5 ZW |
504 | Output \fB#include\fR directives in addition to the result of |
505 | preprocessing. | |
5490d604 JM |
506 | .Ip "\fB\-M\fR" 4 |
507 | .IX Item "-M" | |
6251188c | 508 | Instead of outputting the result of preprocessing, output a rule |
fd939e46 JM |
509 | suitable for \f(CW\*(C`make\*(C'\fR describing the dependencies of the main source |
510 | file. The preprocessor outputs one \f(CW\*(C`make\*(C'\fR rule containing the | |
5ef865d5 | 511 | object file name for that source file, a colon, and the names of all the |
445c435a JM |
512 | included files, including those coming from \fB\-include\fR or |
513 | \&\fB\-imacros\fR command line options. If there are many included files | |
514 | then the rule is split into several lines using \fB\e\fR\-newline. | |
5490d604 JM |
515 | .Ip "\fB\-MM\fR" 4 |
516 | .IX Item "-MM" | |
517 | Like \fB\-M\fR, but mention only the files included with \fB#include | |
445c435a JM |
518 | "\fR\fIfile\fR\fB"\fR or with \fB\-include\fR or \fB\-imacros\fR command line |
519 | options. System header files included with \fB#include <\fR\fIfile\fR\fB>\fR | |
520 | are omitted. | |
5490d604 JM |
521 | .Ip "\fB\-MF\fR \fIfile\fR" 4 |
522 | .IX Item "-MF file" | |
523 | When used with \fB\-M\fR or \fB\-MM\fR, specifies a file to write the | |
524 | dependencies to. This allows the preprocessor to write the preprocessed | |
525 | file to stdout normally. If no \fB\-MF\fR switch is given, \s-1CPP\s0 sends | |
526 | the rules to stdout and suppresses normal preprocessed output. | |
527 | .Ip "\fB\-MG\fR" 4 | |
528 | .IX Item "-MG" | |
529 | When used with \fB\-M\fR or \fB\-MM\fR, \fB\-MG\fR says to treat missing | |
530 | header files as generated files and assume they live in the same | |
531 | directory as the source file. It suppresses preprocessed output, as a | |
532 | missing header file is ordinarily an error. | |
533 | .Sp | |
534 | This feature is used in automatic updating of makefiles. | |
535 | .Ip "\fB\-MP\fR" 4 | |
536 | .IX Item "-MP" | |
537 | This option instructs \s-1CPP\s0 to add a phony target for each dependency | |
538 | other than the main file, causing each to depend on nothing. These | |
539 | dummy rules work around errors \f(CW\*(C`make\*(C'\fR gives if you remove header | |
540 | files without updating the \f(CW\*(C`Makefile\*(C'\fR to match. | |
541 | .Sp | |
542 | This is typical output:\- | |
543 | .Sp | |
544 | .Vb 1 | |
545 | \& /tmp/test.o: /tmp/test.c /tmp/test.h | |
546 | .Ve | |
547 | .Vb 1 | |
548 | \& /tmp/test.h: | |
549 | .Ve | |
550 | .Ip "\fB\-MQ\fR \fItarget\fR" 4 | |
551 | .IX Item "-MQ target" | |
552 | .PD 0 | |
553 | .Ip "\fB\-MT\fR \fItarget\fR" 4 | |
554 | .IX Item "-MT target" | |
555 | .PD | |
556 | By default \s-1CPP\s0 uses the main file name, including any path, and appends | |
557 | the object suffix, normally ``.o'', to it to obtain the name of the | |
558 | target for dependency generation. With \fB\-MT\fR you can specify a | |
559 | target yourself, overriding the default one. | |
560 | .Sp | |
561 | If you want multiple targets, you can specify them as a single argument | |
562 | to \fB\-MT\fR, or use multiple \fB\-MT\fR options. | |
6251188c | 563 | .Sp |
5490d604 JM |
564 | The targets you specify are output in the order they appear on the |
565 | command line. \fB\-MQ\fR is identical to \fB\-MT\fR, except that the | |
566 | target name is quoted for Make, but with \fB\-MT\fR it isn't. For | |
567 | example, \-MT '$(objpfx)foo.o' gives | |
6251188c | 568 | .Sp |
5490d604 JM |
569 | .Vb 1 |
570 | \& $(objpfx)foo.o: /tmp/foo.c | |
571 | .Ve | |
572 | but \-MQ '$(objpfx)foo.o' gives | |
573 | .Sp | |
574 | .Vb 1 | |
575 | \& $$(objpfx)foo.o: /tmp/foo.c | |
576 | .Ve | |
577 | The default target is automatically quoted, as if it were given with | |
578 | \&\fB\-MQ\fR. | |
6251188c | 579 | .Ip "\fB\-H\fR" 4 |
fd939e46 | 580 | .IX Item "-H" |
6251188c ZW |
581 | Print the name of each header file used, in addition to other normal |
582 | activities. | |
fd939e46 JM |
583 | .Ip "\fB\-imacros\fR \fIfile\fR" 4 |
584 | .IX Item "-imacros file" | |
6251188c ZW |
585 | Process \fIfile\fR as input, discarding the resulting output, before |
586 | processing the regular input file. Because the output generated from | |
fd939e46 | 587 | \&\fIfile\fR is discarded, the only effect of \fB\-imacros\fR \fIfile\fR |
6251188c ZW |
588 | is to make the macros defined in \fIfile\fR available for use in the |
589 | main input. | |
fd939e46 JM |
590 | .Ip "\fB\-include\fR \fIfile\fR" 4 |
591 | .IX Item "-include file" | |
6251188c ZW |
592 | Process \fIfile\fR as input, and include all the resulting output, |
593 | before processing the regular input file. | |
fd939e46 JM |
594 | .Ip "\fB\-idirafter\fR \fIdir\fR" 4 |
595 | .IX Item "-idirafter dir" | |
6251188c ZW |
596 | Add the directory \fIdir\fR to the second include path. The directories |
597 | on the second include path are searched when a header file is not found | |
598 | in any of the directories in the main include path (the one that | |
fd939e46 JM |
599 | \&\fB\-I\fR adds to). |
600 | .Ip "\fB\-iprefix\fR \fIprefix\fR" 4 | |
601 | .IX Item "-iprefix prefix" | |
6251188c | 602 | Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR |
5ef865d5 ZW |
603 | options. If the prefix represents a directory, you should include the |
604 | final \fB/\fR. | |
fd939e46 JM |
605 | .Ip "\fB\-iwithprefix\fR \fIdir\fR" 4 |
606 | .IX Item "-iwithprefix dir" | |
6251188c | 607 | Add a directory to the second include path. The directory's name is |
5ef865d5 ZW |
608 | made by concatenating \fIprefix\fR and \fIdir\fR, where \fIprefix\fR was |
609 | specified previously with \fB\-iprefix\fR. | |
fd939e46 JM |
610 | .Ip "\fB\-isystem\fR \fIdir\fR" 4 |
611 | .IX Item "-isystem dir" | |
6251188c ZW |
612 | Add a directory to the beginning of the second include path, marking it |
613 | as a system directory, so that it gets the same special treatment as | |
5ef865d5 | 614 | is applied to the standard system directories. |
6251188c | 615 | .Ip "\fB\-x c\fR" 4 |
fd939e46 JM |
616 | .IX Item "-x c" |
617 | .PD 0 | |
6251188c | 618 | .Ip "\fB\-x c++\fR" 4 |
fd939e46 | 619 | .IX Item "-x c++" |
6251188c | 620 | .Ip "\fB\-x objective-c\fR" 4 |
fd939e46 | 621 | .IX Item "-x objective-c" |
6251188c | 622 | .Ip "\fB\-x assembler-with-cpp\fR" 4 |
fd939e46 JM |
623 | .IX Item "-x assembler-with-cpp" |
624 | .PD | |
6251188c ZW |
625 | Specify the source language: C, \*(C+, Objective-C, or assembly. This has |
626 | nothing to do with standards conformance or extensions; it merely | |
627 | selects which base syntax to expect. If you give none of these options, | |
628 | cpp will deduce the language from the extension of the source file: | |
629 | \&\fB.c\fR, \fB.cc\fR, \fB.m\fR, or \fB.S\fR. Some other common | |
630 | extensions for \*(C+ and assembly are also recognized. If cpp does not | |
631 | recognize the extension, it will treat the file as C; this is the most | |
632 | generic mode. | |
633 | .Sp | |
fd939e46 | 634 | \&\fBNote:\fR Previous versions of cpp accepted a \fB\-lang\fR option |
6251188c ZW |
635 | which selected both the language and the standards conformance level. |
636 | This option has been removed, because it conflicts with the \fB\-l\fR | |
637 | option. | |
fd939e46 JM |
638 | .Ip "\fB\-std=\fR\fIstandard\fR" 4 |
639 | .IX Item "-std=standard" | |
640 | .PD 0 | |
6251188c | 641 | .Ip "\fB\-ansi\fR" 4 |
fd939e46 JM |
642 | .IX Item "-ansi" |
643 | .PD | |
6251188c ZW |
644 | Specify the standard to which the code should conform. Currently cpp |
645 | only knows about the standards for C; other language standards will be | |
646 | added in the future. | |
647 | .Sp | |
fd939e46 | 648 | \&\fIstandard\fR |
6251188c | 649 | may be one of: |
5ef865d5 | 650 | .RS 4 |
fd939e46 JM |
651 | .if n .Ip "\f(CW""iso9899:1990""\fR" 4 |
652 | .el .Ip "\f(CWiso9899:1990\fR" 4 | |
653 | .IX Item "iso9899:1990" | |
5ef865d5 | 654 | .PD 0 |
fd939e46 JM |
655 | .if n .Ip "\f(CW""c89""\fR" 4 |
656 | .el .Ip "\f(CWc89\fR" 4 | |
657 | .IX Item "c89" | |
658 | .PD | |
5ef865d5 ZW |
659 | The \s-1ISO\s0 C standard from 1990. \fBc89\fR is the customary shorthand for |
660 | this version of the standard. | |
6251188c ZW |
661 | .Sp |
662 | The \fB\-ansi\fR option is equivalent to \fB\-std=c89\fR. | |
fd939e46 JM |
663 | .if n .Ip "\f(CW""iso9899:199409""\fR" 4 |
664 | .el .Ip "\f(CWiso9899:199409\fR" 4 | |
665 | .IX Item "iso9899:199409" | |
5ef865d5 | 666 | The 1990 C standard, as amended in 1994. |
fd939e46 JM |
667 | .if n .Ip "\f(CW""iso9899:1999""\fR" 4 |
668 | .el .Ip "\f(CWiso9899:1999\fR" 4 | |
669 | .IX Item "iso9899:1999" | |
670 | .PD 0 | |
671 | .if n .Ip "\f(CW""c99""\fR" 4 | |
672 | .el .Ip "\f(CWc99\fR" 4 | |
673 | .IX Item "c99" | |
674 | .if n .Ip "\f(CW""iso9899:199x""\fR" 4 | |
675 | .el .Ip "\f(CWiso9899:199x\fR" 4 | |
676 | .IX Item "iso9899:199x" | |
677 | .if n .Ip "\f(CW""c9x""\fR" 4 | |
678 | .el .Ip "\f(CWc9x\fR" 4 | |
679 | .IX Item "c9x" | |
680 | .PD | |
5ef865d5 ZW |
681 | The revised \s-1ISO\s0 C standard, published in December 1999. Before |
682 | publication, this was known as C9X. | |
fd939e46 JM |
683 | .if n .Ip "\f(CW""gnu89""\fR" 4 |
684 | .el .Ip "\f(CWgnu89\fR" 4 | |
685 | .IX Item "gnu89" | |
6251188c | 686 | The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. |
fd939e46 JM |
687 | .if n .Ip "\f(CW""gnu99""\fR" 4 |
688 | .el .Ip "\f(CWgnu99\fR" 4 | |
689 | .IX Item "gnu99" | |
690 | .PD 0 | |
691 | .if n .Ip "\f(CW""gnu9x""\fR" 4 | |
692 | .el .Ip "\f(CWgnu9x\fR" 4 | |
693 | .IX Item "gnu9x" | |
5ef865d5 | 694 | .PD |
fd939e46 JM |
695 | The 1999 C standard plus \s-1GNU\s0 extensions. |
696 | .RE | |
697 | .RS 4 | |
5ef865d5 | 698 | .RE |
fd939e46 JM |
699 | .Ip "\fB\-ftabstop=NUMBER\fR" 4 |
700 | .IX Item "-ftabstop=NUMBER" | |
701 | Set the distance between tab stops. This helps the preprocessor | |
5ef865d5 ZW |
702 | report correct column numbers in warnings or errors, even if tabs appear |
703 | on the line. Values less than 1 or greater than 100 are ignored. The | |
704 | default is 8. | |
6251188c | 705 | .Ip "\fB\-$\fR" 4 |
fd939e46 | 706 | .IX Item "-$" |
5ef865d5 ZW |
707 | Forbid the use of \fB$\fR in identifiers. The C standard allows |
708 | implementations to define extra characters that can appear in | |
709 | identifiers. By default the \s-1GNU\s0 C preprocessor permits \fB$\fR, a | |
710 | common extension. | |
6251188c | 711 | .SH "SEE ALSO" |
fd939e46 JM |
712 | .IX Header "SEE ALSO" |
713 | \&\fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and | |
714 | \&\fIbinutils\fR. | |
6251188c | 715 | .SH "COPYRIGHT" |
fd939e46 JM |
716 | .IX Header "COPYRIGHT" |
717 | Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, | |
5490d604 | 718 | 1997, 1998, 1999, 2000, 2001 |
6251188c ZW |
719 | Free Software Foundation, Inc. |
720 | .PP | |
721 | Permission is granted to make and distribute verbatim copies of | |
722 | this manual provided the copyright notice and this permission notice | |
723 | are preserved on all copies. | |
724 | .PP | |
725 | Permission is granted to copy and distribute modified versions of this | |
726 | manual under the conditions for verbatim copying, provided also that | |
727 | the entire resulting derived work is distributed under the terms of a | |
728 | permission notice identical to this one. | |
729 | .PP | |
730 | Permission is granted to copy and distribute translations of this manual | |
731 | into another language, under the above conditions for modified versions. |