| @@ -1,935 +1,1006 @@ | | | @@ -1,935 +1,1006 @@ |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 | | 1 | .\" $NetBSD: cpp.1,v 1.2 2009/04/30 00:45:47 joerg Exp $ |
2 | .\" | | 2 | .Dd April 30, 2009 |
3 | .\" Standard preamble: | | 3 | .Dt CPP 1 |
4 | .\" ======================================================================== | | 4 | .Os |
5 | .de Sh \" Subsection heading | | 5 | .Sh NAME |
6 | .br | | 6 | .Nm cpp |
7 | .if t .Sp | | 7 | .Nd The C Preprocessor |
8 | .ne 5 | | 8 | .Sh SYNOPSIS |
9 | .PP | | 9 | .Nm |
10 | \fB\\$1\fR | | 10 | .Op Fl D Ns Ar macro Ns = Ns Ar defn... |
11 | .PP | | 11 | .Op Fl U Ns Ar macro |
12 | .. | | 12 | .Op Fl I Ns Ar dir... |
13 | .de Sp \" Vertical space (when we can't use .PP) | | 13 | .Op Fl iquote Ns Ar dir... |
14 | .if t .sp .5v | | 14 | .Op Fl W Ns Ar warn... |
15 | .if n .sp | | 15 | .Op Fl M | Fl MM |
16 | .. | | 16 | .Op Fl MG |
17 | .de Vb \" Begin verbatim text | | 17 | .Op Fl MF Ar filename |
18 | .ft CW | | 18 | .Op Fl MP |
19 | .nf | | 19 | .Op Fl MQ Ar target... |
20 | .ne \\$1 | | 20 | .Op Fl MT Ar target... |
21 | .. | | 21 | .Op Fl P |
22 | .de Ve \" End verbatim text | | 22 | .Op Fl fno-working-directory |
23 | .ft R | | 23 | .Op Fl x Ar language |
24 | .fi | | 24 | .Op Fl std= Ns Ar standard |
25 | .. | | 25 | .Ar infile |
26 | .\" Set up some character translations and predefined strings. \*(-- will | | 26 | .Ar outfile |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | | 27 | .Pp |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | | | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | | | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | | | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | | | |
32 | .tr \(*W-|\(bv\*(Tr | | | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | | | |
34 | .ie n \{\ | | | |
35 | . ds -- \(*W- | | | |
36 | . ds PI pi | | | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | | | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | | | |
39 | . ds L" "" | | | |
40 | . ds R" "" | | | |
41 | . ds C` "" | | | |
42 | . ds C' "" | | | |
43 | 'br\} | | | |
44 | .el\{\ | | | |
45 | . ds -- \|\(em\| | | | |
46 | . ds PI \(*p | | | |
47 | . ds L" `` | | | |
48 | . ds R" '' | | | |
49 | 'br\} | | | |
50 | .\" | | | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | | | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | | | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | | | |
54 | .\" output yourself in some meaningful fashion. | | | |
55 | .if \nF \{\ | | | |
56 | . de IX | | | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | | | |
58 | .. | | | |
59 | . nr % 0 | | | |
60 | . rr F | | | |
61 | .\} | | | |
62 | .\" | | | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | | | |
64 | .\" way too many mistakes in technical documents. | | | |
65 | .hy 0 | | | |
66 | .if n .na | | | |
67 | .\" | | | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | | | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | | | |
70 | . \" fudge factors for nroff and troff | | | |
71 | .if n \{\ | | | |
72 | . ds #H 0 | | | |
73 | . ds #V .8m | | | |
74 | . ds #F .3m | | | |
75 | . ds #[ \f1 | | | |
76 | . ds #] \fP | | | |
77 | .\} | | | |
78 | .if t \{\ | | | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | | | |
80 | . ds #V .6m | | | |
81 | . ds #F 0 | | | |
82 | . ds #[ \& | | | |
83 | . ds #] \& | | | |
84 | .\} | | | |
85 | . \" simple accents for nroff and troff | | | |
86 | .if n \{\ | | | |
87 | . ds ' \& | | | |
88 | . ds ` \& | | | |
89 | . ds ^ \& | | | |
90 | . ds , \& | | | |
91 | . ds ~ ~ | | | |
92 | . ds / | | | |
93 | .\} | | | |
94 | .if t \{\ | | | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | | | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | | | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | | | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | | | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | | | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | | | |
101 | .\} | | | |
102 | . \" troff and (daisy-wheel) nroff accents | | | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | | | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | | | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | | | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | | | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | | | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | | | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | | | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | | | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | | | |
112 | . \" corrections for vroff | | | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | | | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | | | |
115 | . \" for low resolution devices (crt and lpr) | | | |
116 | .if \n(.H>23 .if \n(.V>19 \ | | | |
117 | \{\ | | | |
118 | . ds : e | | | |
119 | . ds 8 ss | | | |
120 | . ds o a | | | |
121 | . ds d- d\h'-1'\(ga | | | |
122 | . ds D- D\h'-1'\(hy | | | |
123 | . ds th \o'bp' | | | |
124 | . ds Th \o'LP' | | | |
125 | . ds ae ae | | | |
126 | . ds Ae AE | | | |
127 | .\} | | | |
128 | .rm #[ #] #H #V #F C | | | |
129 | .\" ======================================================================== | | | |
130 | .\" | | | |
131 | .IX Title "CPP 1" | | | |
132 | .TH CPP 1 "2006-05-06" "gcc-4.1.1" "GNU" | | | |
133 | .SH "NAME" | | | |
134 | cpp \- The C Preprocessor | | | |
135 | .SH "SYNOPSIS" | | | |
136 | .IX Header "SYNOPSIS" | | | |
137 | cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] | | | |
138 | [\fB\-I\fR\fIdir\fR...] [\fB\-iquote\fR\fIdir\fR...] | | | |
139 | [\fB\-W\fR\fIwarn\fR...] | | | |
140 | [\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR] | | | |
141 | [\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...] | | | |
142 | [\fB\-MT\fR \fItarget\fR...] | | | |
143 | [\fB\-P\fR] [\fB\-fno\-working\-directory\fR] | | | |
144 | [\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR] | | | |
145 | \fIinfile\fR \fIoutfile\fR | | | |
146 | .PP | | | |
147 | Only the most useful options are listed here; see below for the remainder. | | 28 | Only the most useful options are listed here; see below for the remainder. |
148 | .SH "DESCRIPTION" | | 29 | .Sh DESCRIPTION |
149 | .IX Header "DESCRIPTION" | | 30 | The C preprocessor, often known as |
150 | The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR | | 31 | .Nm , |
151 | that is used automatically by the C compiler to transform your program | | 32 | is a |
152 | before compilation. It is called a macro processor because it allows | | 33 | .Em macro processor |
153 | you to define \fImacros\fR, which are brief abbreviations for longer | | 34 | that is used automatically by the C compiler to transform your program before compilation. |
154 | constructs. | | 35 | It is called a macro processor because it allows you to define |
155 | .PP | | 36 | .Em macros , |
156 | The C preprocessor is intended to be used only with C, \*(C+, and | | 37 | which are brief abbreviations for longer constructs. |
157 | Objective-C source code. In the past, it has been abused as a general | | 38 | .Pp |
158 | text processor. It will choke on input which does not obey C's lexical | | 39 | The C preprocessor is intended to be used only with C, C++, and Objective-C source code. |
159 | rules. For example, apostrophes will be interpreted as the beginning of | | 40 | In the past, it has been abused as a general text processor. |
160 | character constants, and cause errors. Also, you cannot rely on it | | 41 | It will choke on input which does not obey C's lexical rules. |
161 | preserving characteristics of the input which are not significant to | | 42 | For example, apostrophes will be interpreted as the beginning of character constants, and cause errors. |
162 | C\-family languages. If a Makefile is preprocessed, all the hard tabs | | 43 | Also, you cannot rely on it preserving characteristics of the input which are not significant to C-family languages. |
163 | will be removed, and the Makefile will not work. | | 44 | If a Makefile is preprocessed, all the hard tabs will be removed, and the Makefile will not work. |
164 | .PP | | 45 | .Pp |
165 | Having said that, you can often get away with using cpp on things which | | 46 | Having said that, you can often get away with using cpp on things which are not C. |
166 | are not C. Other Algol-ish programming languages are often safe | | 47 | Other Algol-ish programming languages are often safe (Pascal, Ada, etc.) So is assembly, with caution. |
167 | (Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR | | 48 | .Fl traditional-cpp |
168 | mode preserves more white space, and is otherwise more permissive. Many | | 49 | mode preserves more white space, and is otherwise more permissive. |
169 | of the problems can be avoided by writing C or \*(C+ style comments | | 50 | Many of the problems can be avoided by writing C or C++ style comments instead of native language comments, and keeping macros simple. |
170 | instead of native language comments, and keeping macros simple. | | 51 | .Pp |
171 | .PP | | 52 | Wherever possible, you should use a preprocessor geared to the language you are writing in. |
172 | Wherever possible, you should use a preprocessor geared to the language | | 53 | Modern versions of the GNU assembler have macro facilities. |
173 | you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro | | 54 | Most high level programming languages have their own conditional compilation and inclusion mechanism. |
174 | facilities. Most high level programming languages have their own | | 55 | If all else fails, try a true general text processor, such as GNU M4. |
175 | conditional compilation and inclusion mechanism. If all else fails, | | 56 | .Pp |
176 | try a true general text processor, such as \s-1GNU\s0 M4. | | 57 | C preprocessors vary in some details. |
177 | .PP | | 58 | This manual discusses the GNU C preprocessor, which provides a small superset of the features of ISO Standard C. |
178 | C preprocessors vary in some details. This manual discusses the \s-1GNU\s0 C | | 59 | In its default mode, the GNU C preprocessor does not do a few things required by the standard. |
179 | preprocessor, which provides a small superset of the features of \s-1ISO\s0 | | 60 | These are features which are rarely, if ever, used, and may cause surprising changes to the meaning of a program which does not expect them. |
180 | Standard C. In its default mode, the \s-1GNU\s0 C preprocessor does not do a | | 61 | To get strict ISO Standard C, you should use the |
181 | few things required by the standard. These are features which are | | 62 | .Fl std=c89 |
182 | rarely, if ever, used, and may cause surprising changes to the meaning | | 63 | or |
183 | of a program which does not expect them. To get strict \s-1ISO\s0 Standard C, | | 64 | .Fl std=c99 |
184 | you should use the \fB\-std=c89\fR or \fB\-std=c99\fR options, depending | | 65 | options, depending on which version of the standard you want. |
185 | on which version of the standard you want. To get all the mandatory | | 66 | To get all the mandatory diagnostics, you must also use |
186 | diagnostics, you must also use \fB\-pedantic\fR. | | 67 | .Fl pedantic . |
187 | .PP | | 68 | .Pp |
188 | This manual describes the behavior of the \s-1ISO\s0 preprocessor. To | | 69 | This manual describes the behavior of the ISO preprocessor. |
189 | minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's | | 70 | To minimize gratuitous differences, where the ISO preprocessor's behavior does not conflict with traditional semantics, the traditional preprocessor should behave the same way. |
190 | behavior does not conflict with traditional semantics, the | | 71 | The various differences that do exist are detailed in the section |
191 | traditional preprocessor should behave the same way. The various | | 72 | .Sy Traditional Mode . |
192 | differences that do exist are detailed in the section \fBTraditional | | 73 | .Pp |
193 | Mode\fR. | | 74 | For clarity, unless noted otherwise, references to |
194 | .PP | | 75 | .Sy CPP |
195 | For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this | | 76 | in this manual refer to GNU CPP. |
196 | manual refer to \s-1GNU\s0 \s-1CPP\s0. | | 77 | .Sh OPTIONS |
197 | .SH "OPTIONS" | | 78 | The C preprocessor expects two file names as arguments, |
198 | .IX Header "OPTIONS" | | 79 | .Em infile |
199 | The C preprocessor expects two file names as arguments, \fIinfile\fR and | | 80 | and |
200 | \&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any | | 81 | .Em outfile . |
201 | other files it specifies with \fB#include\fR. All the output generated | | 82 | The preprocessor reads |
202 | by the combined input files is written in \fIoutfile\fR. | | 83 | .Em infile |
203 | .PP | | 84 | together with any other files it specifies with |
204 | Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as | | 85 | .Sy #include . |
205 | \&\fIinfile\fR means to read from standard input and as \fIoutfile\fR | | 86 | All the output generated by the combined input files is written in |
206 | means to write to standard output. Also, if either file is omitted, it | | 87 | .Em outfile . |
207 | means the same as if \fB\-\fR had been specified for that file. | | 88 | .Pp |
208 | .PP | | 89 | Either |
209 | Unless otherwise noted, or the option ends in \fB=\fR, all options | | 90 | .Em infile |
210 | which take an argument may have that argument appear either immediately | | 91 | or |
211 | after the option, or with a space between option and argument: | | 92 | .Em outfile |
212 | \&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect. | | 93 | may be |
213 | .PP | | 94 | .Sy - , |
214 | Many options have multi-letter names; therefore multiple single-letter | | 95 | which as |
215 | options may \fInot\fR be grouped: \fB\-dM\fR is very different from | | 96 | .Em infile |
216 | \&\fB\-d\ \-M\fR. | | 97 | means to read from standard input and as |
217 | .IP "\fB\-D\fR \fIname\fR" 4 | | 98 | .Em outfile |
218 | .IX Item "-D name" | | 99 | means to write to standard output. |
219 | Predefine \fIname\fR as a macro, with definition \f(CW1\fR. | | 100 | Also, if either file is omitted, it means the same as if |
220 | .IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4 | | 101 | .Sy - |
221 | .IX Item "-D name=definition" | | 102 | had been specified for that file. |
222 | The contents of \fIdefinition\fR are tokenized and processed as if | | 103 | .Pp |
223 | they appeared during translation phase three in a \fB#define\fR | | 104 | Unless otherwise noted, or the option ends in |
224 | directive. In particular, the definition will be truncated by | | 105 | .Sy = , |
225 | embedded newline characters. | | 106 | all options which take an argument may have that argument appear either immediately after the option, or with a space between option and argument: |
226 | .Sp | | 107 | .Fl Ifoo |
227 | If you are invoking the preprocessor from a shell or shell-like | | 108 | and |
228 | program you may need to use the shell's quoting syntax to protect | | 109 | .Fl I Ar foo |
229 | characters such as spaces that have a meaning in the shell syntax. | | 110 | have the same effect. |
230 | .Sp | | 111 | .Pp |
231 | If you wish to define a function-like macro on the command line, write | | 112 | Many options have multi-letter names; therefore multiple single-letter options may |
232 | its argument list with surrounding parentheses before the equals sign | | 113 | .Em not |
233 | (if any). Parentheses are meaningful to most shells, so you will need | | 114 | be grouped: |
234 | to quote the option. With \fBsh\fR and \fBcsh\fR, | | 115 | .Fl dM |
235 | \&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works. | | 116 | is very different from |
236 | .Sp | | 117 | .Fl d Fl M . |
237 | \&\fB\-D\fR and \fB\-U\fR options are processed in the order they | | 118 | .Pp |
238 | are given on the command line. All \fB\-imacros\fR \fIfile\fR and | | 119 | .Bl -tag -width xx -compact |
239 | \&\fB\-include\fR \fIfile\fR options are processed after all | | 120 | .It Fl D Ar name |
240 | \&\fB\-D\fR and \fB\-U\fR options. | | 121 | Predefine |
241 | .IP "\fB\-U\fR \fIname\fR" 4 | | 122 | .Em name |
242 | .IX Item "-U name" | | 123 | as a macro, with definition |
243 | Cancel any previous definition of \fIname\fR, either built in or | | 124 | .Va 1 . |
244 | provided with a \fB\-D\fR option. | | 125 | .Pp |
245 | .IP "\fB\-undef\fR" 4 | | 126 | .It Fl D Ar name Ns = Ns Ar definition |
246 | .IX Item "-undef" | | 127 | The contents of |
247 | Do not predefine any system-specific or GCC-specific macros. The | | 128 | .Em definition |
248 | standard predefined macros remain defined. | | 129 | are tokenized and processed as if they appeared during translation phase three in a |
249 | .IP "\fB\-I\fR \fIdir\fR" 4 | | 130 | .Sy #define |
250 | .IX Item "-I dir" | | 131 | directive. |
251 | Add the directory \fIdir\fR to the list of directories to be searched | | 132 | In particular, the definition will be truncated by embedded newline characters. |
252 | for header files. | | 133 | .Pp |
253 | .Sp | | 134 | If you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax. |
254 | Directories named by \fB\-I\fR are searched before the standard | | 135 | .Pp |
255 | system include directories. If the directory \fIdir\fR is a standard | | 136 | If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). |
256 | system include directory, the option is ignored to ensure that the | | 137 | Parentheses are meaningful to most shells, so you will need to quote the option. |
257 | default search order for system directories and the special treatment | | 138 | With |
258 | of system headers are not defeated | | 139 | .Nm sh |
259 | \&. | | 140 | and |
260 | .IP "\fB\-o\fR \fIfile\fR" 4 | | 141 | .Nm csh , |
261 | .IX Item "-o file" | | 142 | .Sy -D'name(args...)=definition' |
262 | Write output to \fIfile\fR. This is the same as specifying \fIfile\fR | | 143 | works. |
263 | as the second non-option argument to \fBcpp\fR. \fBgcc\fR has a | | 144 | .Pp |
264 | different interpretation of a second non-option argument, so you must | | 145 | .Fl D |
265 | use \fB\-o\fR to specify the output file. | | 146 | and |
266 | .IP "\fB\-Wall\fR" 4 | | 147 | .Fl U |
267 | .IX Item "-Wall" | | 148 | options are processed in the order they are given on the command line. |
| | | 149 | All |
| | | 150 | .Fl imacros Ar file |
| | | 151 | and |
| | | 152 | .Fl include Ar file |
| | | 153 | options are processed after all |
| | | 154 | .Fl D |
| | | 155 | and |
| | | 156 | .Fl U |
| | | 157 | options. |
| | | 158 | .Pp |
| | | 159 | .It Fl U Ar name |
| | | 160 | Cancel any previous definition of |
| | | 161 | .Em name , |
| | | 162 | either built in or provided with a |
| | | 163 | .Fl D |
| | | 164 | option. |
| | | 165 | .Pp |
| | | 166 | .It Fl undef |
| | | 167 | Do not predefine any system-specific or GCC-specific macros. |
| | | 168 | The standard predefined macros remain defined. |
| | | 169 | .Pp |
| | | 170 | .It Fl I Ar dir |
| | | 171 | Add the directory |
| | | 172 | .Em dir |
| | | 173 | to the list of directories to be searched for header files. |
| | | 174 | .Pp |
| | | 175 | Directories named by |
| | | 176 | .Fl I |
| | | 177 | are searched before the standard system include directories. |
| | | 178 | If the directory |
| | | 179 | .Em dir |
| | | 180 | is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated . |
| | | 181 | .Pp |
| | | 182 | .It Fl o Ar file |
| | | 183 | Write output to |
| | | 184 | .Em file . |
| | | 185 | This is the same as specifying |
| | | 186 | .Em file |
| | | 187 | as the second non-option argument to |
| | | 188 | .Nm cpp . |
| | | 189 | .Nm gcc |
| | | 190 | has a different interpretation of a second non-option argument, so you must use |
| | | 191 | .Fl o |
| | | 192 | to specify the output file. |
| | | 193 | .Pp |
| | | 194 | .It Fl Wall |
268 | Turns on all optional warnings which are desirable for normal code. | | 195 | Turns on all optional warnings which are desirable for normal code. |
269 | At present this is \fB\-Wcomment\fR, \fB\-Wtrigraphs\fR, | | 196 | At present this is |
270 | \&\fB\-Wmultichar\fR and a warning about integer promotion causing a | | 197 | .Fl Wcomment , |
271 | change of sign in \f(CW\*(C`#if\*(C'\fR expressions. Note that many of the | | 198 | .Fl Wtrigraphs , |
272 | preprocessor's warnings are on by default and have no options to | | 199 | .Fl Wmultichar |
273 | control them. | | 200 | and a warning about integer promotion causing a change of sign in |
274 | .IP "\fB\-Wcomment\fR" 4 | | 201 | .Va #if |
275 | .IX Item "-Wcomment" | | 202 | expressions. |
276 | .PD 0 | | 203 | Note that many of the preprocessor's warnings are on by default and have no options to control them. |
277 | .IP "\fB\-Wcomments\fR" 4 | | 204 | .Pp |
278 | .IX Item "-Wcomments" | | 205 | .It Fl Wcomment |
279 | .PD | | 206 | .It Fl Wcomments |
280 | Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR | | 207 | Warn whenever a comment-start sequence |
281 | comment, or whenever a backslash-newline appears in a \fB//\fR comment. | | 208 | .Sy /* |
| | | 209 | appears in a |
| | | 210 | .Sy /* |
| | | 211 | comment, or whenever a backslash-newline appears in a |
| | | 212 | .Sy // |
| | | 213 | comment. |
282 | (Both forms have the same effect.) | | 214 | (Both forms have the same effect.) |
283 | .IP "\fB\-Wtrigraphs\fR" 4 | | 215 | .Pp |
284 | .IX Item "-Wtrigraphs" | | 216 | .It Fl Wtrigraphs |
285 | @anchor{Wtrigraphs} | | 217 | @anchor{Wtrigraphs} Most trigraphs in comments cannot affect the meaning of the program. |
286 | Most trigraphs in comments cannot affect the meaning of the program. | | 218 | However, a trigraph that would form an escaped newline |
287 | However, a trigraph that would form an escaped newline (\fB??/\fR at | | 219 | .Sy ( ??/ |
288 | the end of a line) can, by changing where the comment begins or ends. | | 220 | at the end of a line) can, by changing where the comment begins or ends. |
289 | Therefore, only trigraphs that would form escaped newlines produce | | 221 | Therefore, only trigraphs that would form escaped newlines produce warnings inside a comment. |
290 | warnings inside a comment. | | 222 | .Pp |
291 | .Sp | | 223 | This option is implied by |
292 | This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not | | 224 | .Fl Wall . |
293 | given, this option is still enabled unless trigraphs are enabled. To | | 225 | If |
294 | get trigraph conversion without warnings, but get the other | | 226 | .Fl Wall |
295 | \&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR. | | 227 | is not given, this option is still enabled unless trigraphs are enabled. |
296 | .IP "\fB\-Wtraditional\fR" 4 | | 228 | To get trigraph conversion without warnings, but get the other |
297 | .IX Item "-Wtraditional" | | 229 | .Fl Wall |
298 | Warn about certain constructs that behave differently in traditional and | | 230 | warnings, use |
299 | \&\s-1ISO\s0 C. Also warn about \s-1ISO\s0 C constructs that have no traditional C | | 231 | .Fl trigraphs Fl Wall Fl Wno-trigraphs . |
300 | equivalent, and problematic constructs which should be avoided. | | 232 | .Pp |
301 | .IP "\fB\-Wimport\fR" 4 | | 233 | .It Fl Wtraditional |
302 | .IX Item "-Wimport" | | 234 | Warn about certain constructs that behave differently in traditional and ISO C. |
303 | Warn the first time \fB#import\fR is used. | | 235 | Also warn about ISO C constructs that have no traditional C equivalent, and problematic constructs which should be avoided. |
304 | .IP "\fB\-Wundef\fR" 4 | | 236 | .Pp |
305 | .IX Item "-Wundef" | | 237 | .It Fl Wimport |
| | | 238 | Warn the first time |
| | | 239 | .Sy #import |
| | | 240 | is used. |
| | | 241 | .Pp |
| | | 242 | .It Fl Wundef |
306 | Warn whenever an identifier which is not a macro is encountered in an | | 243 | Warn whenever an identifier which is not a macro is encountered in an |
307 | \&\fB#if\fR directive, outside of \fBdefined\fR. Such identifiers are | | 244 | .Sy #if |
308 | replaced with zero. | | 245 | directive, outside of |
309 | .IP "\fB\-Wunused\-macros\fR" 4 | | 246 | .Sy defined . |
310 | .IX Item "-Wunused-macros" | | 247 | Such identifiers are replaced with zero. |
311 | Warn about macros defined in the main file that are unused. A macro | | 248 | .Pp |
312 | is \fIused\fR if it is expanded or tested for existence at least once. | | 249 | .It Fl Wunused-macros |
313 | The preprocessor will also warn if the macro has not been used at the | | 250 | Warn about macros defined in the main file that are unused. |
314 | time it is redefined or undefined. | | 251 | A macro is |
315 | .Sp | | 252 | .Em used |
316 | Built-in macros, macros defined on the command line, and macros | | 253 | if it is expanded or tested for existence at least once. |
317 | defined in include files are not warned about. | | 254 | The preprocessor will also warn if the macro has not been used at the time it is redefined or undefined. |
318 | .Sp | | 255 | .Pp |
319 | \&\fINote:\fR If a macro is actually used, but only used in skipped | | 256 | Built-in macros, macros defined on the command line, and macros defined in include files are not warned about. |
320 | conditional blocks, then \s-1CPP\s0 will report it as unused. To avoid the | | 257 | .Pp |
321 | warning in such a case, you might improve the scope of the macro's | | 258 | .Em Note: |
322 | definition by, for example, moving it into the first skipped block. | | 259 | If a macro is actually used, but only used in skipped conditional blocks, then CPP will report it as unused. |
| | | 260 | To avoid the warning in such a case, you might improve the scope of the macro's definition by, for example, moving it into the first skipped block. |
323 | Alternatively, you could provide a dummy use with something like: | | 261 | Alternatively, you could provide a dummy use with something like: |
324 | .Sp | | 262 | .Pp |
325 | .Vb 2 | | 263 | .Bd -literal -offset indent |
326 | \& #if defined the_macro_causing_the_warning | | 264 | #if defined the_macro_causing_the_warning |
327 | \& #endif | | 265 | #endif |
328 | .Ve | | 266 | .Ed |
329 | .IP "\fB\-Wendif\-labels\fR" 4 | | 267 | .Pp |
330 | .IX Item "-Wendif-labels" | | 268 | .It Fl Wendif-labels |
331 | Warn whenever an \fB#else\fR or an \fB#endif\fR are followed by text. | | 269 | Warn whenever an |
| | | 270 | .Sy #else |
| | | 271 | or an |
| | | 272 | .Sy #endif |
| | | 273 | are followed by text. |
332 | This usually happens in code of the form | | 274 | This usually happens in code of the form |
333 | .Sp | | 275 | .Pp |
334 | .Vb 5 | | 276 | .Bd -literal -offset indent |
335 | \& #if FOO | | 277 | #if FOO |
336 | \& ... | | 278 | \&... |
337 | \& #else FOO | | 279 | #else FOO |
338 | \& ... | | 280 | \&... |
339 | \& #endif FOO | | 281 | #endif FOO |
340 | .Ve | | 282 | .Ed |
341 | .Sp | | 283 | The second and third |
342 | The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments, but often are not | | 284 | .Va FOO |
343 | in older programs. This warning is on by default. | | 285 | should be in comments, but often are not in older programs. |
344 | .IP "\fB\-Werror\fR" 4 | | 286 | This warning is on by default. |
345 | .IX Item "-Werror" | | 287 | .Pp |
346 | Make all warnings into hard errors. Source code which triggers warnings | | 288 | .It Fl Werror |
347 | will be rejected. | | 289 | Make all warnings into hard errors. |
348 | .IP "\fB\-Wsystem\-headers\fR" 4 | | 290 | Source code which triggers warnings will be rejected. |
349 | .IX Item "-Wsystem-headers" | | 291 | .Pp |
350 | Issue warnings for code in system headers. These are normally unhelpful | | 292 | .It Fl Wsystem-headers |
351 | in finding bugs in your own code, therefore suppressed. If you are | | 293 | Issue warnings for code in system headers. |
352 | responsible for the system library, you may want to see them. | | 294 | These are normally unhelpful in finding bugs in your own code, therefore suppressed. |
353 | .IP "\fB\-w\fR" 4 | | 295 | If you are responsible for the system library, you may want to see them. |
354 | .IX Item "-w" | | 296 | .Pp |
355 | Suppress all warnings, including those which \s-1GNU\s0 \s-1CPP\s0 issues by default. | | 297 | .It Fl w |
356 | .IP "\fB\-pedantic\fR" 4 | | 298 | Suppress all warnings, including those which GNU CPP issues by default. |
357 | .IX Item "-pedantic" | | 299 | .Pp |
358 | Issue all the mandatory diagnostics listed in the C standard. Some of | | 300 | .It Fl pedantic |
359 | them are left out by default, since they trigger frequently on harmless | | 301 | Issue all the mandatory diagnostics listed in the C standard. |
360 | code. | | 302 | Some of them are left out by default, since they trigger frequently on harmless code. |
361 | .IP "\fB\-pedantic\-errors\fR" 4 | | 303 | .Pp |
362 | .IX Item "-pedantic-errors" | | 304 | .It Fl pedantic-errors |
363 | Issue all the mandatory diagnostics, and make all mandatory diagnostics | | 305 | Issue all the mandatory diagnostics, and make all mandatory diagnostics into errors. |
364 | into errors. This includes mandatory diagnostics that \s-1GCC\s0 issues | | 306 | This includes mandatory diagnostics that GCC issues without |
365 | without \fB\-pedantic\fR but treats as warnings. | | 307 | .Fl pedantic |
366 | .IP "\fB\-M\fR" 4 | | 308 | but treats as warnings. |
367 | .IX Item "-M" | | 309 | .Pp |
368 | Instead of outputting the result of preprocessing, output a rule | | 310 | .It Fl M |
369 | suitable for \fBmake\fR describing the dependencies of the main | | 311 | Instead of outputting the result of preprocessing, output a rule suitable for |
370 | source file. The preprocessor outputs one \fBmake\fR rule containing | | 312 | .Sy make |
371 | the object file name for that source file, a colon, and the names of all | | 313 | describing the dependencies of the main source file. |
372 | the included files, including those coming from \fB\-include\fR or | | 314 | The preprocessor outputs one |
373 | \&\fB\-imacros\fR command line options. | | 315 | .Sy make |
374 | .Sp | | 316 | rule containing the object file name for that source file, a colon, and the names of all the included files, including those coming from |
375 | Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the | | 317 | .Fl include |
376 | object file name consists of the basename of the source file with any | | 318 | or |
377 | suffix replaced with object file suffix. If there are many included | | 319 | .Fl imacros |
378 | files then the rule is split into several lines using \fB\e\fR\-newline. | | 320 | command line options. |
| | | 321 | .Pp |
| | | 322 | Unless specified explicitly (with |
| | | 323 | .Fl MT |
| | | 324 | or |
| | | 325 | .Fl MQ ) , |
| | | 326 | the object file name consists of the basename of the source file with any suffix replaced with object file suffix. |
| | | 327 | If there are many included files then the rule is split into several lines using |
| | | 328 | .Sy \e |
| | | 329 | -newline. |
379 | The rule has no commands. | | 330 | The rule has no commands. |
380 | .Sp | | 331 | .Pp |
381 | This option does not suppress the preprocessor's debug output, such as | | 332 | This option does not suppress the preprocessor's debug output, such as |
382 | \&\fB\-dM\fR. To avoid mixing such debug output with the dependency | | 333 | .Fl dM . |
383 | rules you should explicitly specify the dependency output file with | | 334 | To avoid mixing such debug output with the dependency rules you should explicitly specify the dependency output file with |
384 | \&\fB\-MF\fR, or use an environment variable like | | 335 | .Fl MF , |
385 | \&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output | | 336 | or use an environment variable like |
386 | will still be sent to the regular output stream as normal. | | 337 | .Sy DEPENDENCIES_OUTPUT . |
387 | .Sp | | 338 | Debug output will still be sent to the regular output stream as normal. |
388 | Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses | | 339 | .Pp |
389 | warnings with an implicit \fB\-w\fR. | | 340 | Passing |
390 | .IP "\fB\-MM\fR" 4 | | 341 | .Fl M |
391 | .IX Item "-MM" | | 342 | to the driver implies |
392 | Like \fB\-M\fR but do not mention header files that are found in | | 343 | .Fl E , |
393 | system header directories, nor header files that are included, | | 344 | and suppresses warnings with an implicit |
394 | directly or indirectly, from such a header. | | 345 | .Fl w . |
395 | .Sp | | 346 | .Pp |
| | | 347 | .It Fl MM |
| | | 348 | Like |
| | | 349 | .Fl M |
| | | 350 | but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header. |
| | | 351 | .Pp |
396 | This implies that the choice of angle brackets or double quotes in an | | 352 | This implies that the choice of angle brackets or double quotes in an |
397 | \&\fB#include\fR directive does not in itself determine whether that | | 353 | .Sy #include |
398 | header will appear in \fB\-MM\fR dependency output. This is a | | 354 | directive does not in itself determine whether that header will appear in |
399 | slight change in semantics from \s-1GCC\s0 versions 3.0 and earlier. | | 355 | .Fl MM |
400 | .Sp | | 356 | dependency output. |
| | | 357 | This is a slight change in semantics from GCC versions 3.0 and earlier. |
| | | 358 | .Pp |
401 | @anchor{dashMF} | | 359 | @anchor{dashMF} |
402 | .IP "\fB\-MF\fR \fIfile\fR" 4 | | 360 | .Pp |
403 | .IX Item "-MF file" | | 361 | .It Fl MF Ar file |
404 | When used with \fB\-M\fR or \fB\-MM\fR, specifies a | | 362 | When used with |
405 | file to write the dependencies to. If no \fB\-MF\fR switch is given | | 363 | .Fl M |
406 | the preprocessor sends the rules to the same place it would have sent | | 364 | or |
407 | preprocessed output. | | 365 | .Fl MM , |
408 | .Sp | | 366 | specifies a file to write the dependencies to. |
409 | When used with the driver options \fB\-MD\fR or \fB\-MMD\fR, | | 367 | If no |
410 | \&\fB\-MF\fR overrides the default dependency output file. | | 368 | .Fl MF |
411 | .IP "\fB\-MG\fR" 4 | | 369 | switch is given the preprocessor sends the rules to the same place it would have sent preprocessed output. |
412 | .IX Item "-MG" | | 370 | .Pp |
413 | In conjunction with an option such as \fB\-M\fR requesting | | 371 | When used with the driver options |
414 | dependency generation, \fB\-MG\fR assumes missing header files are | | 372 | .Fl MD |
415 | generated files and adds them to the dependency list without raising | | 373 | or |
416 | an error. The dependency filename is taken directly from the | | 374 | .Fl MMD , |
417 | \&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR | | 375 | .Fl MF |
418 | also suppresses preprocessed output, as a missing header file renders | | 376 | overrides the default dependency output file. |
419 | this useless. | | 377 | .Pp |
420 | .Sp | | 378 | .It Fl MG |
| | | 379 | In conjunction with an option such as |
| | | 380 | .Fl M |
| | | 381 | requesting dependency generation, |
| | | 382 | .Fl MG |
| | | 383 | assumes missing header files are generated files and adds them to the dependency list without raising an error. |
| | | 384 | The dependency filename is taken directly from the |
| | | 385 | .Va #include |
| | | 386 | directive without prepending any path. |
| | | 387 | .Fl MG |
| | | 388 | also suppresses preprocessed output, as a missing header file renders this useless. |
| | | 389 | .Pp |
421 | This feature is used in automatic updating of makefiles. | | 390 | This feature is used in automatic updating of makefiles. |
422 | .IP "\fB\-MP\fR" 4 | | 391 | .Pp |
423 | .IX Item "-MP" | | 392 | .It Fl MP |
424 | This option instructs \s-1CPP\s0 to add a phony target for each dependency | | 393 | This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. |
425 | other than the main file, causing each to depend on nothing. These | | 394 | These dummy rules work around errors |
426 | dummy rules work around errors \fBmake\fR gives if you remove header | | 395 | .Sy make |
427 | files without updating the \fIMakefile\fR to match. | | 396 | gives if you remove header files without updating the |
428 | .Sp | | 397 | .Pa Makefile |
| | | 398 | to match. |
| | | 399 | .Pp |
429 | This is typical output: | | 400 | This is typical output: |
430 | .Sp | | 401 | .Pp |
431 | .Vb 1 | | 402 | .Bd -literal -offset indent |
432 | \& test.o: test.c test.h | | 403 | test.o: test.c test.h |
433 | .Ve | | 404 | |
434 | .Sp | | 405 | test.h: |
435 | .Vb 1 | | 406 | .Ed |
436 | \& test.h: | | 407 | .It Fl MT Ar target |
437 | .Ve | | 408 | Change the target of the rule emitted by dependency generation. |
438 | .IP "\fB\-MT\fR \fItarget\fR" 4 | | 409 | By default CPP takes the name of the main input file, including any path, deletes any file suffix such as |
439 | .IX Item "-MT target" | | 410 | .Sy .c , |
440 | Change the target of the rule emitted by dependency generation. By | | 411 | and appends the platform's usual object suffix. |
441 | default \s-1CPP\s0 takes the name of the main input file, including any path, | | 412 | The result is the target. |
442 | deletes any file suffix such as \fB.c\fR, and appends the platform's | | 413 | .Pp |
443 | usual object suffix. The result is the target. | | 414 | An |
444 | .Sp | | 415 | .Fl MT |
445 | An \fB\-MT\fR option will set the target to be exactly the string you | | 416 | option will set the target to be exactly the string you specify. |
446 | specify. If you want multiple targets, you can specify them as a single | | 417 | If you want multiple targets, you can specify them as a single argument to |
447 | argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options. | | 418 | .Fl MT , |
448 | .Sp | | 419 | or use multiple |
449 | For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give | | 420 | .Fl MT |
450 | .Sp | | 421 | options. |
451 | .Vb 1 | | 422 | .Pp |
452 | \& $(objpfx)foo.o: foo.c | | 423 | For example, |
453 | .Ve | | 424 | .Sy -MT '$(objpfx)foo.o' |
454 | .IP "\fB\-MQ\fR \fItarget\fR" 4 | | 425 | might give |
455 | .IX Item "-MQ target" | | 426 | .Pp |
456 | Same as \fB\-MT\fR, but it quotes any characters which are special to | | 427 | .Bd -literal -offset indent |
457 | Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives | | 428 | $(objpfx)foo.o: foo.c |
458 | .Sp | | 429 | .Ed |
459 | .Vb 1 | | 430 | .It Fl MQ Ar target |
460 | \& $$(objpfx)foo.o: foo.c | | 431 | Same as |
461 | .Ve | | 432 | .Fl MT , |
462 | .Sp | | 433 | but it quotes any characters which are special to Make. |
| | | 434 | .Sy -MQ '$(objpfx)foo.o' |
| | | 435 | gives |
| | | 436 | .Pp |
| | | 437 | .Bd -literal -offset indent |
| | | 438 | $$(objpfx)foo.o: foo.c |
| | | 439 | .Ed |
463 | The default target is automatically quoted, as if it were given with | | 440 | The default target is automatically quoted, as if it were given with |
464 | \&\fB\-MQ\fR. | | 441 | .Fl MQ . |
465 | .IP "\fB\-MD\fR" 4 | | 442 | .Pp |
466 | .IX Item "-MD" | | 443 | .It Fl MD |
467 | \&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that | | 444 | .Fl MD |
468 | \&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on | | 445 | is equivalent to |
469 | whether an \fB\-o\fR option is given. If it is, the driver uses its | | 446 | .Fl M Fl MF Ar file , |
470 | argument but with a suffix of \fI.d\fR, otherwise it take the | | 447 | except that |
471 | basename of the input file and applies a \fI.d\fR suffix. | | 448 | .Fl E |
472 | .Sp | | 449 | is not implied. |
473 | If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any | | 450 | The driver determines |
474 | \&\fB\-o\fR switch is understood to specify the dependency output file | | 451 | .Em file |
475 | (but \f(CW@pxref\fR{dashMF,,\-MF}), but if used without \fB\-E\fR, each \fB\-o\fR | | 452 | based on whether an |
| | | 453 | .Fl o |
| | | 454 | option is given. |
| | | 455 | If it is, the driver uses its argument but with a suffix of |
| | | 456 | .Pa .d , |
| | | 457 | otherwise it take the basename of the input file and applies a |
| | | 458 | .Pa .d |
| | | 459 | suffix. |
| | | 460 | .Pp |
| | | 461 | If |
| | | 462 | .Fl MD |
| | | 463 | is used in conjunction with |
| | | 464 | .Fl E , |
| | | 465 | any |
| | | 466 | .Fl o |
| | | 467 | switch is understood to specify the dependency output file (but @pxref{dashMF,,-MF}), but if used without |
| | | 468 | .Fl E , |
| | | 469 | each |
| | | 470 | .Fl o |
476 | is understood to specify a target object file. | | 471 | is understood to specify a target object file. |
477 | .Sp | | 472 | .Pp |
478 | Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate | | 473 | Since |
479 | a dependency output file as a side-effect of the compilation process. | | 474 | .Fl E |
480 | .IP "\fB\-MMD\fR" 4 | | 475 | is not implied, |
481 | .IX Item "-MMD" | | 476 | .Fl MD |
482 | Like \fB\-MD\fR except mention only user header files, not system | | 477 | can be used to generate a dependency output file as a side-effect of the compilation process. |
483 | header files. | | 478 | .Pp |
484 | .IP "\fB\-x c\fR" 4 | | 479 | .It Fl MMD |
485 | .IX Item "-x c" | | 480 | Like |
486 | .PD 0 | | 481 | .Fl MD |
487 | .IP "\fB\-x c++\fR" 4 | | 482 | except mention only user header files, not system header files. |
488 | .IX Item "-x c++" | | 483 | .Pp |
489 | .IP "\fB\-x objective-c\fR" 4 | | 484 | .It Fl x Ar c |
490 | .IX Item "-x objective-c" | | 485 | .It Fl x Ar c++ |
491 | .IP "\fB\-x assembler-with-cpp\fR" 4 | | 486 | .It Fl x Ar objective-c |
492 | .IX Item "-x assembler-with-cpp" | | 487 | .It Fl x Ar assembler-with-cpp |
493 | .PD | | 488 | Specify the source language: C, C++, Objective-C, or assembly. |
494 | Specify the source language: C, \*(C+, Objective\-C, or assembly. This has | | 489 | This has nothing to do with standards conformance or extensions; it merely selects which base syntax to expect. |
495 | nothing to do with standards conformance or extensions; it merely | | 490 | If you give none of these options, cpp will deduce the language from the extension of the source file: |
496 | selects which base syntax to expect. If you give none of these options, | | 491 | .Sy .c , |
497 | cpp will deduce the language from the extension of the source file: | | 492 | .Sy .cc , |
498 | \&\fB.c\fR, \fB.cc\fR, \fB.m\fR, or \fB.S\fR. Some other common | | 493 | .Sy .m , |
499 | extensions for \*(C+ and assembly are also recognized. If cpp does not | | 494 | or |
500 | recognize the extension, it will treat the file as C; this is the most | | 495 | .Sy .S . |
501 | generic mode. | | 496 | Some other common extensions for C++ and assembly are also recognized. |
502 | .Sp | | 497 | If cpp does not recognize the extension, it will treat the file as C; this is the most generic mode. |
503 | \&\fINote:\fR Previous versions of cpp accepted a \fB\-lang\fR option | | 498 | .Pp |
504 | which selected both the language and the standards conformance level. | | 499 | .Em Note: |
505 | This option has been removed, because it conflicts with the \fB\-l\fR | | 500 | Previous versions of cpp accepted a |
| | | 501 | .Fl lang |
| | | 502 | option which selected both the language and the standards conformance level. |
| | | 503 | This option has been removed, because it conflicts with the |
| | | 504 | .Fl l |
506 | option. | | 505 | option. |
507 | .IP "\fB\-std=\fR\fIstandard\fR" 4 | | 506 | .Pp |
508 | .IX Item "-std=standard" | | 507 | .It Fl std= Ns Ar standard |
509 | .PD 0 | | 508 | .It Fl ansi |
510 | .IP "\fB\-ansi\fR" 4 | | 509 | Specify the standard to which the code should conform. |
511 | .IX Item "-ansi" | | 510 | Currently CPP knows about C and C++ standards; others may be added in the future. |
512 | .PD | | 511 | .Pp |
513 | Specify the standard to which the code should conform. Currently \s-1CPP\s0 | | 512 | .Em standard |
514 | knows about C and \*(C+ standards; others may be added in the future. | | | |
515 | .Sp | | | |
516 | \&\fIstandard\fR | | | |
517 | may be one of: | | 513 | may be one of: |
518 | .RS 4 | | 514 | .Pp |
519 | .ie n .IP """iso9899:1990""" 4 | | 515 | .Bl -tag -width xx |
520 | .el .IP "\f(CWiso9899:1990\fR" 4 | | 516 | .It Sy iso9899:1990 Ns |
521 | .IX Item "iso9899:1990" | | 517 | .It Sy c89 Ns |
522 | .PD 0 | | 518 | The ISO C standard from 1990. |
523 | .ie n .IP """c89""" 4 | | 519 | .Sy c89 |
524 | .el .IP "\f(CWc89\fR" 4 | | 520 | is the customary shorthand for this version of the standard. |
525 | .IX Item "c89" | | 521 | .Pp |
526 | .PD | | 522 | The |
527 | The \s-1ISO\s0 C standard from 1990. \fBc89\fR is the customary shorthand for | | 523 | .Fl ansi |
528 | this version of the standard. | | 524 | option is equivalent to |
529 | .Sp | | 525 | .Fl std=c89 . |
530 | The \fB\-ansi\fR option is equivalent to \fB\-std=c89\fR. | | 526 | .Pp |
531 | .ie n .IP """iso9899:199409""" 4 | | 527 | .It Sy iso9899:199409 Ns |
532 | .el .IP "\f(CWiso9899:199409\fR" 4 | | | |
533 | .IX Item "iso9899:199409" | | | |
534 | The 1990 C standard, as amended in 1994. | | 528 | The 1990 C standard, as amended in 1994. |
535 | .ie n .IP """iso9899:1999""" 4 | | 529 | .Pp |
536 | .el .IP "\f(CWiso9899:1999\fR" 4 | | 530 | .It Sy iso9899:1999 Ns |
537 | .IX Item "iso9899:1999" | | 531 | .It Sy c99 Ns |
538 | .PD 0 | | 532 | .It Sy iso9899:199x Ns |
539 | .ie n .IP """c99""" 4 | | 533 | .It Sy c9x Ns |
540 | .el .IP "\f(CWc99\fR" 4 | | 534 | The revised ISO C standard, published in December 1999. |
541 | .IX Item "c99" | | 535 | Before publication, this was known as C9X. |
542 | .ie n .IP """iso9899:199x""" 4 | | 536 | .Pp |
543 | .el .IP "\f(CWiso9899:199x\fR" 4 | | 537 | .It Sy gnu89 Ns |
544 | .IX Item "iso9899:199x" | | 538 | The 1990 C standard plus GNU extensions. |
545 | .ie n .IP """c9x""" 4 | | 539 | This is the default. |
546 | .el .IP "\f(CWc9x\fR" 4 | | 540 | .Pp |
547 | .IX Item "c9x" | | 541 | .It Sy gnu99 Ns |
548 | .PD | | 542 | .It Sy gnu9x Ns |
549 | The revised \s-1ISO\s0 C standard, published in December 1999. Before | | 543 | The 1999 C standard plus GNU extensions. |
550 | publication, this was known as C9X. | | 544 | .Pp |
551 | .ie n .IP """gnu89""" 4 | | 545 | .It Sy c++98 Ns |
552 | .el .IP "\f(CWgnu89\fR" 4 | | 546 | The 1998 ISO C++ standard plus amendments. |
553 | .IX Item "gnu89" | | 547 | .Pp |
554 | The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. | | 548 | .It Sy gnu++98 Ns |
555 | .ie n .IP """gnu99""" 4 | | 549 | The same as |
556 | .el .IP "\f(CWgnu99\fR" 4 | | 550 | .Fl std=c++98 |
557 | .IX Item "gnu99" | | 551 | plus GNU extensions. |
558 | .PD 0 | | 552 | This is the default for C++ code. |
559 | .ie n .IP """gnu9x""" 4 | | 553 | .Pp |
560 | .el .IP "\f(CWgnu9x\fR" 4 | | 554 | .El |
561 | .IX Item "gnu9x" | | 555 | .It Fl I- |
562 | .PD | | 556 | Split the include path. |
563 | The 1999 C standard plus \s-1GNU\s0 extensions. | | 557 | Any directories specified with |
564 | .ie n .IP """c++98""" 4 | | 558 | .Fl I |
565 | .el .IP "\f(CWc++98\fR" 4 | | 559 | options before |
566 | .IX Item "c++98" | | 560 | .Fl I- |
567 | The 1998 \s-1ISO\s0 \*(C+ standard plus amendments. | | 561 | are searched only for headers requested with |
568 | .ie n .IP """gnu++98""" 4 | | 562 | .Va .Sy #include \&"file" ; |
569 | .el .IP "\f(CWgnu++98\fR" 4 | | 563 | they are not searched for |
570 | .IX Item "gnu++98" | | 564 | .Va .Sy #include \*[Lt]file\*[Gt] . |
571 | The same as \fB\-std=c++98\fR plus \s-1GNU\s0 extensions. This is the | | 565 | If additional directories are specified with |
572 | default for \*(C+ code. | | 566 | .Fl I |
573 | .RE | | 567 | options after the |
574 | .RS 4 | | 568 | .Fl I- , |
575 | .RE | | 569 | those directories are searched for all |
576 | .IP "\fB\-I\-\fR" 4 | | 570 | .Sy #include |
577 | .IX Item "-I-" | | 571 | directives. |
578 | Split the include path. Any directories specified with \fB\-I\fR | | 572 | .Pp |
579 | options before \fB\-I\-\fR are searched only for headers requested with | | 573 | In addition, |
580 | \&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for | | 574 | .Fl I- |
581 | \&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are | | 575 | inhibits the use of the directory of the current file directory as the first search directory for |
582 | specified with \fB\-I\fR options after the \fB\-I\-\fR, those | | 576 | .Va .Sy #include \&"file" . |
583 | directories are searched for all \fB#include\fR directives. | | 577 | .Pp |
584 | .Sp | | | |
585 | In addition, \fB\-I\-\fR inhibits the use of the directory of the current | | | |
586 | file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. | | | |
587 | .Sp | | | |
588 | This option has been deprecated. | | 578 | This option has been deprecated. |
589 | .IP "\fB\-nostdinc\fR" 4 | | 579 | .Pp |
590 | .IX Item "-nostdinc" | | 580 | .It Fl nostdinc |
591 | Do not search the standard system directories for header files. | | 581 | Do not search the standard system directories for header files. |
592 | Only the directories you have specified with \fB\-I\fR options | | 582 | Only the directories you have specified with |
593 | (and the directory of the current file, if appropriate) are searched. | | 583 | .Fl I |
594 | .IP "\fB\-nostdinc++\fR" 4 | | 584 | options (and the directory of the current file, if appropriate) are searched. |
595 | .IX Item "-nostdinc++" | | 585 | .Pp |
596 | Do not search for header files in the \*(C+\-specific standard directories, | | 586 | .It Fl nostdinc++ |
597 | but do still search the other standard directories. (This option is | | 587 | Do not search for header files in the C++-specific standard directories, but do still search the other standard directories. |
598 | used when building the \*(C+ library.) | | 588 | (This option is used when building the C++ library.) |
599 | .IP "\fB\-include\fR \fIfile\fR" 4 | | 589 | .Pp |
600 | .IX Item "-include file" | | 590 | .It Fl include Ar file |
601 | Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first | | 591 | Process |
602 | line of the primary source file. However, the first directory searched | | 592 | .Em file |
603 | for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR | | 593 | as if |
604 | the directory containing the main source file. If not found there, it | | 594 | .Va #include \&"file" |
605 | is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search | | 595 | appeared as the first line of the primary source file. |
606 | chain as normal. | | 596 | However, the first directory searched for |
607 | .Sp | | 597 | .Em file |
608 | If multiple \fB\-include\fR options are given, the files are included | | 598 | is the preprocessor's working directory |
609 | in the order they appear on the command line. | | 599 | .Em instead of |
610 | .IP "\fB\-imacros\fR \fIfile\fR" 4 | | 600 | the directory containing the main source file. |
611 | .IX Item "-imacros file" | | 601 | If not found there, it is searched for in the remainder of the |
612 | Exactly like \fB\-include\fR, except that any output produced by | | 602 | .Va #include \&"..." |
613 | scanning \fIfile\fR is thrown away. Macros it defines remain defined. | | 603 | search chain as normal. |
614 | This allows you to acquire all the macros from a header without also | | 604 | .Pp |
615 | processing its declarations. | | 605 | If multiple |
616 | .Sp | | 606 | .Fl include |
617 | All files specified by \fB\-imacros\fR are processed before all files | | 607 | options are given, the files are included in the order they appear on the command line. |
618 | specified by \fB\-include\fR. | | 608 | .Pp |
619 | .IP "\fB\-idirafter\fR \fIdir\fR" 4 | | 609 | .It Fl imacros Ar file |
620 | .IX Item "-idirafter dir" | | 610 | Exactly like |
621 | Search \fIdir\fR for header files, but do it \fIafter\fR all | | 611 | .Fl include , |
622 | directories specified with \fB\-I\fR and the standard system directories | | 612 | except that any output produced by scanning |
623 | have been exhausted. \fIdir\fR is treated as a system include directory. | | 613 | .Em file |
624 | .IP "\fB\-iprefix\fR \fIprefix\fR" 4 | | 614 | is thrown away. |
625 | .IX Item "-iprefix prefix" | | 615 | Macros it defines remain defined. |
626 | Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR | | 616 | This allows you to acquire all the macros from a header without also processing its declarations. |
627 | options. If the prefix represents a directory, you should include the | | 617 | .Pp |
628 | final \fB/\fR. | | 618 | All files specified by |
629 | .IP "\fB\-iwithprefix\fR \fIdir\fR" 4 | | 619 | .Fl imacros |
630 | .IX Item "-iwithprefix dir" | | 620 | are processed before all files specified by |
631 | .PD 0 | | 621 | .Fl include . |
632 | .IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4 | | 622 | .Pp |
633 | .IX Item "-iwithprefixbefore dir" | | 623 | .It Fl idirafter Ar dir |
634 | .PD | | 624 | Search |
635 | Append \fIdir\fR to the prefix specified previously with | | 625 | .Em dir |
636 | \&\fB\-iprefix\fR, and add the resulting directory to the include search | | 626 | for header files, but do it |
637 | path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR | | 627 | .Em after |
638 | would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would. | | 628 | all directories specified with |
639 | .IP "\fB\-isysroot\fR \fIdir\fR" 4 | | 629 | .Fl I |
640 | .IX Item "-isysroot dir" | | 630 | and the standard system directories have been exhausted. |
641 | This option is like the \fB\-\-sysroot\fR option, but applies only to | | 631 | .Em dir |
642 | header files. See the \fB\-\-sysroot\fR option for more information. | | 632 | is treated as a system include directory. |
643 | .IP "\fB\-isystem\fR \fIdir\fR" 4 | | 633 | .Pp |
644 | .IX Item "-isystem dir" | | 634 | .It Fl iprefix Ar prefix |
645 | Search \fIdir\fR for header files, after all directories specified by | | 635 | Specify |
646 | \&\fB\-I\fR but before the standard system directories. Mark it | | 636 | .Em prefix |
647 | as a system directory, so that it gets the same special treatment as | | 637 | as the prefix for subsequent |
648 | is applied to the standard system directories. | | 638 | .Fl iwithprefix |
649 | .IP "\fB\-iquote\fR \fIdir\fR" 4 | | 639 | options. |
650 | .IX Item "-iquote dir" | | 640 | If the prefix represents a directory, you should include the final |
651 | Search \fIdir\fR only for header files requested with | | 641 | .Sy / . |
652 | \&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for | | 642 | .Pp |
653 | \&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR, before all directories specified by | | 643 | .It Fl iwithprefix Ar dir |
654 | \&\fB\-I\fR and before the standard system directories. | | 644 | .It Fl iwithprefixbefore Ar dir |
655 | .IP "\fB\-fdollars\-in\-identifiers\fR" 4 | | 645 | Append |
656 | .IX Item "-fdollars-in-identifiers" | | 646 | .Em dir |
657 | @anchor{fdollars\-in\-identifiers} | | 647 | to the prefix specified previously with |
658 | Accept \fB$\fR in identifiers. | | 648 | .Fl iprefix , |
659 | .IP "\fB\-fextended\-identifiers\fR" 4 | | 649 | and add the resulting directory to the include search path. |
660 | .IX Item "-fextended-identifiers" | | 650 | .Fl iwithprefixbefore |
661 | Accept universal character names in identifiers. This option is | | 651 | puts it in the same place |
662 | experimental; in a future version of \s-1GCC\s0, it will be enabled by | | 652 | .Fl I |
663 | default for C99 and \*(C+. | | 653 | would; |
664 | .IP "\fB\-fpreprocessed\fR" 4 | | 654 | .Fl iwithprefix |
665 | .IX Item "-fpreprocessed" | | 655 | puts it where |
666 | Indicate to the preprocessor that the input file has already been | | 656 | .Fl idirafter |
667 | preprocessed. This suppresses things like macro expansion, trigraph | | 657 | would. |
668 | conversion, escaped newline splicing, and processing of most directives. | | 658 | .Pp |
669 | The preprocessor still recognizes and removes comments, so that you can | | 659 | .It Fl isysroot Ar dir |
670 | pass a file preprocessed with \fB\-C\fR to the compiler without | | 660 | This option is like the |
671 | problems. In this mode the integrated preprocessor is little more than | | 661 | .Fl -sysroot |
672 | a tokenizer for the front ends. | | 662 | option, but applies only to header files. |
673 | .Sp | | 663 | See the |
674 | \&\fB\-fpreprocessed\fR is implicit if the input file has one of the | | 664 | .Fl -sysroot |
675 | extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the | | 665 | option for more information. |
676 | extensions that \s-1GCC\s0 uses for preprocessed files created by | | 666 | .Pp |
677 | \&\fB\-save\-temps\fR. | | 667 | .It Fl isystem Ar dir |
678 | .IP "\fB\-ftabstop=\fR\fIwidth\fR" 4 | | 668 | Search |
679 | .IX Item "-ftabstop=width" | | 669 | .Em dir |
680 | Set the distance between tab stops. This helps the preprocessor report | | 670 | for header files, after all directories specified by |
681 | correct column numbers in warnings or errors, even if tabs appear on the | | 671 | .Fl I |
682 | line. If the value is less than 1 or greater than 100, the option is | | 672 | but before the standard system directories. |
683 | ignored. The default is 8. | | 673 | Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories. |
684 | .IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4 | | 674 | .Pp |
685 | .IX Item "-fexec-charset=charset" | | 675 | .It Fl cxx-isystem Ar dir |
686 | Set the execution character set, used for string and character | | 676 | Search |
687 | constants. The default is \s-1UTF\-8\s0. \fIcharset\fR can be any encoding | | 677 | .Em dir |
688 | supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. | | 678 | for C++ header files, after all directories specified by |
689 | .IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4 | | 679 | .Fl I |
690 | .IX Item "-fwide-exec-charset=charset" | | 680 | but before the standard system directories. |
691 | Set the wide execution character set, used for wide string and | | 681 | Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories. |
692 | character constants. The default is \s-1UTF\-32\s0 or \s-1UTF\-16\s0, whichever | | 682 | .Pp |
693 | corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR. As with | | 683 | .It Fl iquote Ar dir |
694 | \&\fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported | | 684 | Search |
695 | by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have | | 685 | .Em dir |
696 | problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR. | | 686 | only for header files requested with |
697 | .IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4 | | 687 | .Va .Sy #include \&"file" ; |
698 | .IX Item "-finput-charset=charset" | | 688 | they are not searched for |
699 | Set the input character set, used for translation from the character | | 689 | .Va .Sy #include \*[Lt]file\*[Gt] , |
700 | set of the input file to the source character set used by \s-1GCC\s0. If the | | 690 | before all directories specified by |
701 | locale does not specify, or \s-1GCC\s0 cannot get this information from the | | 691 | .Fl I |
702 | locale, the default is \s-1UTF\-8\s0. This can be overridden by either the locale | | 692 | and before the standard system directories. |
703 | or this command line option. Currently the command line option takes | | 693 | .Pp |
704 | precedence if there's a conflict. \fIcharset\fR can be any encoding | | 694 | .It Fl fdollars-in-identifiers |
705 | supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. | | 695 | @anchor{fdollars-in-identifiers} Accept |
706 | .IP "\fB\-fworking\-directory\fR" 4 | | 696 | .Sy $ |
707 | .IX Item "-fworking-directory" | | 697 | in identifiers. |
708 | Enable generation of linemarkers in the preprocessor output that will | | 698 | .Pp |
709 | let the compiler know the current working directory at the time of | | 699 | .It Fl fextended-identifiers |
710 | preprocessing. When this option is enabled, the preprocessor will | | 700 | Accept universal character names in identifiers. |
711 | emit, after the initial linemarker, a second linemarker with the | | 701 | This option is experimental; in a future version of GCC, it will be enabled by default for C99 and C++. |
712 | current working directory followed by two slashes. \s-1GCC\s0 will use this | | 702 | .Pp |
713 | directory, when it's present in the preprocessed input, as the | | 703 | .It Fl fpreprocessed |
714 | directory emitted as the current working directory in some debugging | | 704 | Indicate to the preprocessor that the input file has already been preprocessed. |
715 | information formats. This option is implicitly enabled if debugging | | 705 | This suppresses things like macro expansion, trigraph conversion, escaped newline splicing, and processing of most directives. |
716 | information is enabled, but this can be inhibited with the negated | | 706 | The preprocessor still recognizes and removes comments, so that you can pass a file preprocessed with |
717 | form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is | | 707 | .Fl C |
718 | present in the command line, this option has no effect, since no | | 708 | to the compiler without problems. |
719 | \&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever. | | 709 | In this mode the integrated preprocessor is little more than a tokenizer for the front ends. |
720 | .IP "\fB\-fno\-show\-column\fR" 4 | | 710 | .Pp |
721 | .IX Item "-fno-show-column" | | 711 | .Fl fpreprocessed |
722 | Do not print column numbers in diagnostics. This may be necessary if | | 712 | is implicit if the input file has one of the extensions |
723 | diagnostics are being scanned by a program that does not understand the | | 713 | .Sy .i , |
724 | column numbers, such as \fBdejagnu\fR. | | 714 | .Sy .ii |
725 | .IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4 | | 715 | or |
726 | .IX Item "-A predicate=answer" | | 716 | .Sy .mi . |
727 | Make an assertion with the predicate \fIpredicate\fR and answer | | 717 | These are the extensions that GCC uses for preprocessed files created by |
728 | \&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR | | 718 | .Fl save-temps . |
729 | \&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because | | 719 | .Pp |
730 | it does not use shell special characters. | | 720 | .It Fl ftabstop= Ns Ar width |
731 | .IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4 | | 721 | Set the distance between tab stops. |
732 | .IX Item "-A -predicate=answer" | | 722 | This helps the preprocessor report correct column numbers in warnings or errors, even if tabs appear on the line. |
733 | Cancel an assertion with the predicate \fIpredicate\fR and answer | | 723 | If the value is less than 1 or greater than 100, the option is ignored. |
734 | \&\fIanswer\fR. | | 724 | The default is 8. |
735 | .IP "\fB\-dCHARS\fR" 4 | | 725 | .Pp |
736 | .IX Item "-dCHARS" | | 726 | .It Fl fexec-charset= Ns Ar charset |
737 | \&\fI\s-1CHARS\s0\fR is a sequence of one or more of the following characters, | | 727 | Set the execution character set, used for string and character constants. |
738 | and must not be preceded by a space. Other characters are interpreted | | 728 | The default is UTF-8. |
739 | by the compiler proper, or reserved for future versions of \s-1GCC\s0, and so | | 729 | .Em charset |
740 | are silently ignored. If you specify characters whose behavior | | 730 | can be any encoding supported by the system's |
741 | conflicts, the result is undefined. | | 731 | .Va iconv |
742 | .RS 4 | | 732 | library routine. |
743 | .IP "\fBM\fR" 4 | | 733 | .Pp |
744 | .IX Item "M" | | 734 | .It Fl fwide-exec-charset= Ns Ar charset |
745 | Instead of the normal output, generate a list of \fB#define\fR | | 735 | Set the wide execution character set, used for wide string and character constants. |
746 | directives for all the macros defined during the execution of the | | 736 | The default is UTF-32 or UTF-16, whichever corresponds to the width of |
747 | preprocessor, including predefined macros. This gives you a way of | | 737 | .Va wchar_t . |
748 | finding out what is predefined in your version of the preprocessor. | | 738 | As with |
749 | Assuming you have no file \fIfoo.h\fR, the command | | 739 | .Fl fexec-charset , |
750 | .Sp | | 740 | .Em charset |
751 | .Vb 1 | | 741 | can be any encoding supported by the system's |
752 | \& touch foo.h; cpp -dM foo.h | | 742 | .Va iconv |
753 | .Ve | | 743 | library routine; however, you will have problems with encodings that do not fit exactly in |
754 | .Sp | | 744 | .Va wchar_t . |
| | | 745 | .Pp |
| | | 746 | .It Fl finput-charset= Ns Ar charset |
| | | 747 | Set the input character set, used for translation from the character set of the input file to the source character set used by GCC. |
| | | 748 | If the locale does not specify, or GCC cannot get this information from the locale, the default is UTF-8. |
| | | 749 | This can be overridden by either the locale or this command line option. |
| | | 750 | Currently the command line option takes precedence if there's a conflict. |
| | | 751 | .Em charset |
| | | 752 | can be any encoding supported by the system's |
| | | 753 | .Va iconv |
| | | 754 | library routine. |
| | | 755 | .Pp |
| | | 756 | .It Fl fworking-directory |
| | | 757 | Enable generation of linemarkers in the preprocessor output that will let the compiler know the current working directory at the time of preprocessing. |
| | | 758 | When this option is enabled, the preprocessor will emit, after the initial linemarker, a second linemarker with the current working directory followed by two slashes. |
| | | 759 | GCC will use this directory, when it's present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats. |
| | | 760 | This option is implicitly enabled if debugging information is enabled, but this can be inhibited with the negated form |
| | | 761 | .Fl fno-working-directory . |
| | | 762 | If the |
| | | 763 | .Fl P |
| | | 764 | flag is present in the command line, this option has no effect, since no |
| | | 765 | .Va #line |
| | | 766 | directives are emitted whatsoever. |
| | | 767 | .Pp |
| | | 768 | .It Fl fno-show-column |
| | | 769 | Do not print column numbers in diagnostics. |
| | | 770 | This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as |
| | | 771 | .Sy dejagnu . |
| | | 772 | .Pp |
| | | 773 | .It Fl A Ar predicate Ns = Ns Ar answer |
| | | 774 | Make an assertion with the predicate |
| | | 775 | .Em predicate |
| | | 776 | and answer |
| | | 777 | .Em answer . |
| | | 778 | This form is preferred to the older form |
| | | 779 | .Fl A Ar predicate |
| | | 780 | .Sy ( |
| | | 781 | .Em answer |
| | | 782 | .Sy ) , |
| | | 783 | which is still supported, because it does not use shell special characters. |
| | | 784 | .Pp |
| | | 785 | .It Fl A Fl Ns Ar predicate Ns = Ns Ar answer |
| | | 786 | Cancel an assertion with the predicate |
| | | 787 | .Em predicate |
| | | 788 | and answer |
| | | 789 | .Em answer . |
| | | 790 | .Pp |
| | | 791 | .It Fl dCHARS |
| | | 792 | .Em CHARS |
| | | 793 | is a sequence of one or more of the following characters, and must not be preceded by a space. |
| | | 794 | Other characters are interpreted by the compiler proper, or reserved for future versions of GCC, and so are silently ignored. |
| | | 795 | If you specify characters whose behavior conflicts, the result is undefined. |
| | | 796 | .Pp |
| | | 797 | .Bl -tag -width xx |
| | | 798 | .It Sy M Ns |
| | | 799 | Instead of the normal output, generate a list of |
| | | 800 | .Sy #define |
| | | 801 | directives for all the macros defined during the execution of the preprocessor, including predefined macros. |
| | | 802 | This gives you a way of finding out what is predefined in your version of the preprocessor. |
| | | 803 | Assuming you have no file |
| | | 804 | .Pa foo.h , |
| | | 805 | the command |
| | | 806 | .Pp |
| | | 807 | .Bd -literal -offset indent |
| | | 808 | touch foo.h; cpp -dM foo.h |
| | | 809 | .Ed |
755 | will show all the predefined macros. | | 810 | will show all the predefined macros. |
756 | .IP "\fBD\fR" 4 | | 811 | .Pp |
757 | .IX Item "D" | | 812 | .It Sy D Ns |
758 | Like \fBM\fR except in two respects: it does \fInot\fR include the | | 813 | Like |
759 | predefined macros, and it outputs \fIboth\fR the \fB#define\fR | | 814 | .Sy M |
760 | directives and the result of preprocessing. Both kinds of output go to | | 815 | except in two respects: it does |
761 | the standard output file. | | 816 | .Em not |
762 | .IP "\fBN\fR" 4 | | 817 | include the predefined macros, and it outputs |
763 | .IX Item "N" | | 818 | .Em both |
764 | Like \fBD\fR, but emit only the macro names, not their expansions. | | 819 | the |
765 | .IP "\fBI\fR" 4 | | 820 | .Sy #define |
766 | .IX Item "I" | | 821 | directives and the result of preprocessing. |
767 | Output \fB#include\fR directives in addition to the result of | | 822 | Both kinds of output go to the standard output file. |
768 | preprocessing. | | 823 | .Pp |
769 | .RE | | 824 | .It Sy N Ns |
770 | .RS 4 | | 825 | Like |
771 | .RE | | 826 | .Sy D , |
772 | .IP "\fB\-P\fR" 4 | | 827 | but emit only the macro names, not their expansions. |
773 | .IX Item "-P" | | 828 | .Pp |
| | | 829 | .It Sy I Ns |
| | | 830 | Output |
| | | 831 | .Sy #include |
| | | 832 | directives in addition to the result of preprocessing. |
| | | 833 | .Pp |
| | | 834 | .El |
| | | 835 | .It Fl P |
774 | Inhibit generation of linemarkers in the output from the preprocessor. | | 836 | Inhibit generation of linemarkers in the output from the preprocessor. |
775 | This might be useful when running the preprocessor on something that is | | 837 | This might be useful when running the preprocessor on something that is not C code, and will be sent to a program which might be confused by the linemarkers. |
776 | not C code, and will be sent to a program which might be confused by the | | 838 | .Pp |
777 | linemarkers. | | 839 | .It Fl C |
778 | .IP "\fB\-C\fR" 4 | | 840 | Do not discard comments. |
779 | .IX Item "-C" | | 841 | All comments are passed through to the output file, except for comments in processed directives, which are deleted along with the directive. |
780 | Do not discard comments. All comments are passed through to the output | | 842 | .Pp |
781 | file, except for comments in processed directives, which are deleted | | 843 | You should be prepared for side effects when using |
782 | along with the directive. | | 844 | .Fl C ; |
783 | .Sp | | 845 | it causes the preprocessor to treat comments as tokens in their own right. |
784 | You should be prepared for side effects when using \fB\-C\fR; it | | 846 | For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary source line, since the first token on the line is no longer a |
785 | causes the preprocessor to treat comments as tokens in their own right. | | 847 | .Sy # . |
786 | For example, comments appearing at the start of what would be a | | 848 | .Pp |
787 | directive line have the effect of turning that line into an ordinary | | 849 | .It Fl CC |
788 | source line, since the first token on the line is no longer a \fB#\fR. | | 850 | Do not discard comments, including during macro expansion. |
789 | .IP "\fB\-CC\fR" 4 | | 851 | This is like |
790 | .IX Item "-CC" | | 852 | .Fl C , |
791 | Do not discard comments, including during macro expansion. This is | | 853 | except that comments contained within macros are also passed through to the output file where the macro is expanded. |
792 | like \fB\-C\fR, except that comments contained within macros are | | 854 | .Pp |
793 | also passed through to the output file where the macro is expanded. | | 855 | In addition to the side-effects of the |
794 | .Sp | | 856 | .Fl C |
795 | In addition to the side-effects of the \fB\-C\fR option, the | | 857 | option, the |
796 | \&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro | | 858 | .Fl CC |
797 | to be converted to C\-style comments. This is to prevent later use | | 859 | option causes all C++-style comments inside a macro to be converted to C-style comments. |
798 | of that macro from inadvertently commenting out the remainder of | | 860 | This is to prevent later use of that macro from inadvertently commenting out the remainder of the source line. |
799 | the source line. | | 861 | .Pp |
800 | .Sp | | 862 | The |
801 | The \fB\-CC\fR option is generally used to support lint comments. | | 863 | .Fl CC |
802 | .IP "\fB\-traditional\-cpp\fR" 4 | | 864 | option is generally used to support lint comments. |
803 | .IX Item "-traditional-cpp" | | 865 | .Pp |
804 | Try to imitate the behavior of old-fashioned C preprocessors, as | | 866 | .It Fl traditional-cpp |
805 | opposed to \s-1ISO\s0 C preprocessors. | | 867 | Try to imitate the behavior of old-fashioned C preprocessors, as opposed to ISO C preprocessors. |
806 | .IP "\fB\-trigraphs\fR" 4 | | 868 | .Pp |
807 | .IX Item "-trigraphs" | | 869 | .It Fl trigraphs |
808 | Process trigraph sequences. | | 870 | Process trigraph sequences. |
809 | .IP "\fB\-remap\fR" 4 | | 871 | .Pp |
810 | .IX Item "-remap" | | 872 | .It Fl remap |
811 | Enable special code to work around file systems which only permit very | | 873 | Enable special code to work around file systems which only permit very short file names, such as MS-DOS. |
812 | short file names, such as \s-1MS\-DOS\s0. | | 874 | .Pp |
813 | .IP "\fB\-\-help\fR" 4 | | 875 | .It Fl -help |
814 | .IX Item "--help" | | 876 | .It Fl -target-help |
815 | .PD 0 | | 877 | Print text describing all the command line options instead of preprocessing anything. |
816 | .IP "\fB\-\-target\-help\fR" 4 | | 878 | .Pp |
817 | .IX Item "--target-help" | | 879 | .It Fl v |
818 | .PD | | 880 | Verbose mode. |
819 | Print text describing all the command line options instead of | | 881 | Print out GNU CPP's version number at the beginning of execution, and report the final form of the include path. |
820 | preprocessing anything. | | 882 | .Pp |
821 | .IP "\fB\-v\fR" 4 | | 883 | .It Fl H |
822 | .IX Item "-v" | | 884 | Print the name of each header file used, in addition to other normal activities. |
823 | Verbose mode. Print out \s-1GNU\s0 \s-1CPP\s0's version number at the beginning of | | 885 | Each name is indented to show how deep in the |
824 | execution, and report the final form of the include path. | | 886 | .Sy #include |
825 | .IP "\fB\-H\fR" 4 | | 887 | stack it is. |
826 | .IX Item "-H" | | 888 | Precompiled header files are also printed, even if they are found to be invalid; an invalid precompiled header file is printed with |
827 | Print the name of each header file used, in addition to other normal | | 889 | .Sy ...x |
828 | activities. Each name is indented to show how deep in the | | 890 | and a valid one with |
829 | \&\fB#include\fR stack it is. Precompiled header files are also | | 891 | .Sy ...! . |
830 | printed, even if they are found to be invalid; an invalid precompiled | | 892 | .Pp |
831 | header file is printed with \fB...x\fR and a valid one with \fB...!\fR . | | 893 | .It Fl version |
832 | .IP "\fB\-version\fR" 4 | | 894 | .It Fl -version |
833 | .IX Item "-version" | | 895 | Print out GNU CPP's version number. |
834 | .PD 0 | | 896 | With one dash, proceed to preprocess as normal. |
835 | .IP "\fB\-\-version\fR" 4 | | 897 | With two dashes, exit immediately. |
836 | .IX Item "--version" | | 898 | .Pp |
837 | .PD | | 899 | .El |
838 | Print out \s-1GNU\s0 \s-1CPP\s0's version number. With one dash, proceed to | | 900 | .Sh ENVIRONMENT |
839 | preprocess as normal. With two dashes, exit immediately. | | 901 | This section describes the environment variables that affect how CPP operates. |
840 | .SH "ENVIRONMENT" | | 902 | You can use them to specify directories or prefixes to use when searching for include files, or to control dependency output. |
841 | .IX Header "ENVIRONMENT" | | 903 | .Pp |
842 | This section describes the environment variables that affect how \s-1CPP\s0 | | | |
843 | operates. You can use them to specify directories or prefixes to use | | | |
844 | when searching for include files, or to control dependency output. | | | |
845 | .PP | | | |
846 | Note that you can also specify places to search using options such as | | 904 | Note that you can also specify places to search using options such as |
847 | \&\fB\-I\fR, and control dependency output with options like | | 905 | .Fl I , |
848 | \&\fB\-M\fR. These take precedence over | | 906 | and control dependency output with options like |
849 | environment variables, which in turn take precedence over the | | 907 | .Fl M . |
850 | configuration of \s-1GCC\s0. | | 908 | These take precedence over environment variables, which in turn take precedence over the configuration of GCC. |
851 | .IP "\fB\s-1CPATH\s0\fR" 4 | | 909 | .Pp |
852 | .IX Item "CPATH" | | 910 | .Bl -tag -width xx -compact |
853 | .PD 0 | | 911 | .It Sy CPATH Ns |
854 | .IP "\fBC_INCLUDE_PATH\fR" 4 | | 912 | .It Sy C_INCLUDE_PATH Ns |
855 | .IX Item "C_INCLUDE_PATH" | | 913 | .It Sy CPLUS_INCLUDE_PATH Ns |
856 | .IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4 | | 914 | .It Sy OBJC_INCLUDE_PATH Ns |
857 | .IX Item "CPLUS_INCLUDE_PATH" | | 915 | Each variable's value is a list of directories separated by a special character, much like |
858 | .IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4 | | 916 | .Sy PATH , |
859 | .IX Item "OBJC_INCLUDE_PATH" | | 917 | in which to look for header files. |
860 | .PD | | 918 | The special character, |
861 | Each variable's value is a list of directories separated by a special | | 919 | .Va PATH_SEPARATOR , |
862 | character, much like \fB\s-1PATH\s0\fR, in which to look for header files. | | 920 | is target-dependent and determined at GCC build time. |
863 | The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and | | 921 | For Microsoft Windows-based targets it is a semicolon, and for almost all other targets it is a colon. |
864 | determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a | | 922 | .Pp |
865 | semicolon, and for almost all other targets it is a colon. | | 923 | .Sy CPATH |
866 | .Sp | | 924 | specifies a list of directories to be searched as if specified with |
867 | \&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if | | 925 | .Fl I , |
868 | specified with \fB\-I\fR, but after any paths given with \fB\-I\fR | | 926 | but after any paths given with |
869 | options on the command line. This environment variable is used | | 927 | .Fl I |
870 | regardless of which language is being preprocessed. | | 928 | options on the command line. |
871 | .Sp | | 929 | This environment variable is used regardless of which language is being preprocessed. |
872 | The remaining environment variables apply only when preprocessing the | | 930 | .Pp |
873 | particular language indicated. Each specifies a list of directories | | 931 | The remaining environment variables apply only when preprocessing the particular language indicated. |
874 | to be searched as if specified with \fB\-isystem\fR, but after any | | 932 | Each specifies a list of directories to be searched as if specified with |
875 | paths given with \fB\-isystem\fR options on the command line. | | 933 | .Fl isystem , |
876 | .Sp | | 934 | but after any paths given with |
877 | In all these variables, an empty element instructs the compiler to | | 935 | .Fl isystem |
878 | search its current working directory. Empty elements can appear at the | | 936 | options on the command line. |
879 | beginning or end of a path. For instance, if the value of | | 937 | .Pp |
880 | \&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same | | 938 | In all these variables, an empty element instructs the compiler to search its current working directory. |
881 | effect as \fB\-I.\ \-I/special/include\fR. | | 939 | Empty elements can appear at the beginning or end of a path. |
882 | .IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4 | | 940 | For instance, if the value of |
883 | .IX Item "DEPENDENCIES_OUTPUT" | | 941 | .Sy CPATH |
884 | If this variable is set, its value specifies how to output | | 942 | is |
885 | dependencies for Make based on the non-system header files processed | | 943 | .Va :/special/include , |
886 | by the compiler. System header files are ignored in the dependency | | 944 | that has the same effect as |
887 | output. | | 945 | .Sy -I. -I/special/include . |
888 | .Sp | | 946 | .Pp |
889 | The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in | | 947 | .It Sy DEPENDENCIES_OUTPUT Ns |
890 | which case the Make rules are written to that file, guessing the target | | 948 | If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed by the compiler. |
891 | name from the source file name. Or the value can have the form | | 949 | System header files are ignored in the dependency output. |
892 | \&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to | | 950 | .Pp |
893 | file \fIfile\fR using \fItarget\fR as the target name. | | 951 | The value of |
894 | .Sp | | 952 | .Sy DEPENDENCIES_OUTPUT |
895 | In other words, this environment variable is equivalent to combining | | 953 | can be just a file name, in which case the Make rules are written to that file, guessing the target name from the source file name. |
896 | the options \fB\-MM\fR and \fB\-MF\fR, | | 954 | Or the value can have the form |
897 | with an optional \fB\-MT\fR switch too. | | 955 | .Em file |
898 | .IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4 | | 956 | \~ |
899 | .IX Item "SUNPRO_DEPENDENCIES" | | 957 | .Em target , |
900 | This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above), | | 958 | in which case the rules are written to file |
901 | except that system header files are not ignored, so it implies | | 959 | .Em file |
902 | \&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the | | 960 | using |
903 | main input file is omitted. | | 961 | .Em target |
904 | .SH "SEE ALSO" | | 962 | as the target name. |
905 | .IX Header "SEE ALSO" | | 963 | .Pp |
906 | \&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), | | 964 | In other words, this environment variable is equivalent to combining the options |
907 | \&\fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and | | 965 | .Fl MM |
908 | \&\fIbinutils\fR. | | 966 | and |
909 | .SH "COPYRIGHT" | | 967 | .Fl MF , |
910 | .IX Header "COPYRIGHT" | | 968 | with an optional |
911 | Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, | | 969 | .Fl MT |
912 | 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 | | 970 | switch too. |
913 | Free Software Foundation, Inc. | | 971 | .Pp |
914 | .PP | | 972 | .It Sy SUNPRO_DEPENDENCIES Ns |
915 | Permission is granted to copy, distribute and/or modify this document | | 973 | This variable is the same as |
916 | under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 or | | 974 | .Sy DEPENDENCIES_OUTPUT |
917 | any later version published by the Free Software Foundation. A copy of | | 975 | (see above), except that system header files are not ignored, so it implies |
918 | the license is included in the | | 976 | .Fl M |
919 | man page \fIgfdl\fR\|(7). | | 977 | rather than |
920 | This manual contains no Invariant Sections. The Front-Cover Texts are | | 978 | .Fl MM . |
921 | (a) (see below), and the Back-Cover Texts are (b) (see below). | | 979 | However, the dependence on the main input file is omitted. |
922 | .PP | | 980 | .Pp |
923 | (a) The \s-1FSF\s0's Front-Cover Text is: | | 981 | .It Sy CPP_RESTRICTED Ns |
924 | .PP | | 982 | If this variable is defined, cpp will skip any include file which is not a regular file, and will continue searching for the requested name (this is always done if the found file is a directory). |
925 | .Vb 1 | | 983 | .Pp |
926 | \& A GNU Manual | | 984 | .El |
927 | .Ve | | 985 | .Sh SEE ALSO |
928 | .PP | | 986 | gpl(7), gfdl(7), fsf-funding(7), gcc(1), as(1), ld(1), and the Info entries for |
929 | (b) The \s-1FSF\s0's Back-Cover Text is: | | 987 | .Pa cpp , |
930 | .PP | | 988 | .Pa gcc , |
931 | .Vb 3 | | 989 | and |
932 | \& You have freedom to copy and modify this GNU Manual, like GNU | | 990 | .Pa binutils . |
933 | \& software. Copies published by the Free Software Foundation raise | | 991 | .Sh COPYRIGHT |
934 | \& funds for GNU development. | | 992 | Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. |
935 | .Ve | | 993 | .Pp |
| | | 994 | Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation. |
| | | 995 | A copy of the license is included in the man page gfdl(7). |
| | | 996 | This manual contains no Invariant Sections. |
| | | 997 | The Front-Cover Texts are (a) (see below), and the Back-Cover Texts are (b) (see below). |
| | | 998 | .Pp |
| | | 999 | (a) The FSF's Front-Cover Text is: |
| | | 1000 | .Pp |
| | | 1001 | A GNU Manual |
| | | 1002 | .Pp |
| | | 1003 | (b) The FSF's Back-Cover Text is: |
| | | 1004 | .Pp |
| | | 1005 | You have freedom to copy and modify this GNU Manual, like GNU software. |
| | | 1006 | Copies published by the Free Software Foundation raise funds for GNU development. |