OSDN Git Service

16ec89b7df265cb34214c8e7d60ec7a6cb58369c
[pf3gnuchains/gcc-fork.git] / gcc / doc / invoke.texi
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
5
6 @ignore
7 @c man begin INCLUDE
8 @include gcc-vers.texi
9 @c man end
10
11 @c man begin COPYRIGHT
12 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
13 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
14
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.2 or
17 any later version published by the Free Software Foundation; with the
18 Invariant Sections being ``GNU General Public License'' and ``Funding
19 Free Software'', the Front-Cover texts being (a) (see below), and with
20 the Back-Cover Texts being (b) (see below).  A copy of the license is
21 included in the gfdl(7) man page.
22
23 (a) The FSF's Front-Cover Text is:
24
25      A GNU Manual
26
27 (b) The FSF's Back-Cover Text is:
28
29      You have freedom to copy and modify this GNU Manual, like GNU
30      software.  Copies published by the Free Software Foundation raise
31      funds for GNU development.
32 @c man end
33 @c Set file name and title for the man page.
34 @setfilename gcc
35 @settitle GNU project C and C++ compiler
36 @c man begin SYNOPSIS
37 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
38     [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
39     [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
40     [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
41     [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
42     [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
43     [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
44
45 Only the most useful options are listed here; see below for the
46 remainder.  @samp{g++} accepts mostly the same options as @samp{gcc}.
47 @c man end
48 @c man begin SEEALSO
49 gpl(7), gfdl(7), fsf-funding(7),
50 cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
51 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
52 @file{ld}, @file{binutils} and @file{gdb}.
53 @c man end
54 @c man begin BUGS
55 For instructions on reporting bugs, see
56 @w{@uref{http://gcc.gnu.org/bugs.html}}.
57 @c man end
58 @c man begin AUTHOR
59 See the Info entry for @command{gcc}, or
60 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
61 for contributors to GCC@.
62 @c man end
63 @end ignore
64
65 @node Invoking GCC
66 @chapter GCC Command Options
67 @cindex GCC command options
68 @cindex command options
69 @cindex options, GCC command
70
71 @c man begin DESCRIPTION
72 When you invoke GCC, it normally does preprocessing, compilation,
73 assembly and linking.  The ``overall options'' allow you to stop this
74 process at an intermediate stage.  For example, the @option{-c} option
75 says not to run the linker.  Then the output consists of object files
76 output by the assembler.
77
78 Other options are passed on to one stage of processing.  Some options
79 control the preprocessor and others the compiler itself.  Yet other
80 options control the assembler and linker; most of these are not
81 documented here, since you rarely need to use any of them.
82
83 @cindex C compilation options
84 Most of the command line options that you can use with GCC are useful
85 for C programs; when an option is only useful with another language
86 (usually C++), the explanation says so explicitly.  If the description
87 for a particular option does not mention a source language, you can use
88 that option with all supported languages.
89
90 @cindex C++ compilation options
91 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
92 options for compiling C++ programs.
93
94 @cindex grouping options
95 @cindex options, grouping
96 The @command{gcc} program accepts options and file names as operands.  Many
97 options have multi-letter names; therefore multiple single-letter options
98 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
99 -r}}.
100
101 @cindex order of options
102 @cindex options, order
103 You can mix options and other arguments.  For the most part, the order
104 you use doesn't matter.  Order does matter when you use several options
105 of the same kind; for example, if you specify @option{-L} more than once,
106 the directories are searched in the order specified.
107
108 Many options have long names starting with @samp{-f} or with
109 @samp{-W}---for example, 
110 @option{-fmove-loop-invariants}, @option{-Wformat} and so on.  Most of
111 these have both positive and negative forms; the negative form of
112 @option{-ffoo} would be @option{-fno-foo}.  This manual documents
113 only one of these two forms, whichever one is not the default.
114
115 @c man end
116
117 @xref{Option Index}, for an index to GCC's options.
118
119 @menu
120 * Option Summary::      Brief list of all options, without explanations.
121 * Overall Options::     Controlling the kind of output:
122                         an executable, object files, assembler files,
123                         or preprocessed source.
124 * Invoking G++::        Compiling C++ programs.
125 * C Dialect Options::   Controlling the variant of C language compiled.
126 * C++ Dialect Options:: Variations on C++.
127 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
128                         and Objective-C++.
129 * Language Independent Options:: Controlling how diagnostics should be
130                         formatted.
131 * Warning Options::     How picky should the compiler be?
132 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
133 * Optimize Options::    How much optimization?
134 * Preprocessor Options:: Controlling header files and macro definitions.
135                          Also, getting dependency information for Make.
136 * Assembler Options::   Passing options to the assembler.
137 * Link Options::        Specifying libraries and so on.
138 * Directory Options::   Where to find header files and libraries.
139                         Where to find the compiler executable files.
140 * Spec Files::          How to pass switches to sub-processes.
141 * Target Options::      Running a cross-compiler, or an old version of GCC.
142 * Submodel Options::    Specifying minor hardware or convention variations,
143                         such as 68010 vs 68020.
144 * Code Gen Options::    Specifying conventions for function calls, data layout
145                         and register usage.
146 * Environment Variables:: Env vars that affect GCC.
147 * Precompiled Headers:: Compiling a header once, and using it many times.
148 * Running Protoize::    Automatically adding or removing function prototypes.
149 @end menu
150
151 @c man begin OPTIONS
152
153 @node Option Summary
154 @section Option Summary
155
156 Here is a summary of all the options, grouped by type.  Explanations are
157 in the following sections.
158
159 @table @emph
160 @item Overall Options
161 @xref{Overall Options,,Options Controlling the Kind of Output}.
162 @gccoptlist{-c  -S  -E  -o @var{file}  -combine -pipe  -pass-exit-codes  @gol
163 -x @var{language}  -v  -###  --help  --target-help  --version @@@var{file}}
164
165 @item C Language Options
166 @xref{C Dialect Options,,Options Controlling C Dialect}.
167 @gccoptlist{-ansi  -std=@var{standard}  -aux-info @var{filename} @gol
168 -fno-asm  -fno-builtin  -fno-builtin-@var{function} @gol
169 -fhosted  -ffreestanding  -fms-extensions @gol
170 -trigraphs  -no-integrated-cpp  -traditional  -traditional-cpp @gol
171 -fallow-single-precision  -fcond-mismatch @gol
172 -fsigned-bitfields  -fsigned-char @gol
173 -funsigned-bitfields  -funsigned-char}
174
175 @item C++ Language Options
176 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
177 @gccoptlist{-fabi-version=@var{n}  -fno-access-control  -fcheck-new @gol
178 -fconserve-space  -ffriend-injection @gol
179 -fno-elide-constructors @gol
180 -fno-enforce-eh-specs @gol
181 -ffor-scope  -fno-for-scope  -fno-gnu-keywords @gol
182 -fno-implicit-templates @gol
183 -fno-implicit-inline-templates @gol
184 -fno-implement-inlines  -fms-extensions @gol
185 -fno-nonansi-builtins  -fno-operator-names @gol
186 -fno-optional-diags  -fpermissive @gol
187 -frepo  -fno-rtti  -fstats  -ftemplate-depth-@var{n} @gol
188 -fno-threadsafe-statics -fuse-cxa-atexit  -fno-weak  -nostdinc++ @gol
189 -fno-default-inline  -fvisibility-inlines-hidden @gol
190 -Wabi  -Wctor-dtor-privacy @gol
191 -Wnon-virtual-dtor  -Wreorder @gol
192 -Weffc++  -Wno-deprecated  -Wstrict-null-sentinel @gol
193 -Wno-non-template-friend  -Wold-style-cast @gol
194 -Woverloaded-virtual  -Wno-pmf-conversions @gol
195 -Wsign-promo}
196
197 @item Objective-C and Objective-C++ Language Options
198 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
199 Objective-C and Objective-C++ Dialects}.
200 @gccoptlist{
201 -fconstant-string-class=@var{class-name} @gol
202 -fgnu-runtime  -fnext-runtime @gol
203 -fno-nil-receivers @gol
204 -fobjc-call-cxx-cdtors @gol
205 -fobjc-direct-dispatch @gol
206 -fobjc-exceptions @gol
207 -fobjc-gc @gol
208 -freplace-objc-classes @gol
209 -fzero-link @gol
210 -gen-decls @gol
211 -Wassign-intercept @gol
212 -Wno-protocol  -Wselector @gol
213 -Wstrict-selector-match @gol
214 -Wundeclared-selector}
215
216 @item Language Independent Options
217 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
218 @gccoptlist{-fmessage-length=@var{n}  @gol
219 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}} @gol
220 -fdiagnostics-show-options
221
222 @item Warning Options
223 @xref{Warning Options,,Options to Request or Suppress Warnings}.
224 @gccoptlist{-fsyntax-only  -pedantic  -pedantic-errors @gol
225 -w  -Wextra  -Wall  -Waggregate-return -Walways-true -Wno-attributes @gol
226 -Wc++-compat -Wcast-align  -Wcast-qual  -Wchar-subscripts  -Wcomment @gol
227 -Wconversion  -Wno-deprecated-declarations @gol
228 -Wdisabled-optimization  -Wno-div-by-zero  -Wno-endif-labels @gol
229 -Werror  -Werror-* -Werror-implicit-function-declaration @gol
230 -Wfatal-errors  -Wfloat-equal  -Wformat  -Wformat=2 @gol
231 -Wno-format-extra-args -Wformat-nonliteral @gol
232 -Wformat-security  -Wformat-y2k @gol
233 -Wimplicit  -Wimplicit-function-declaration  -Wimplicit-int @gol
234 -Wimport  -Wno-import  -Winit-self  -Winline @gol
235 -Wno-int-to-pointer-cast @gol
236 -Wno-invalid-offsetof  -Winvalid-pch @gol
237 -Wlarger-than-@var{len}  -Wunsafe-loop-optimizations  -Wlong-long @gol
238 -Wmain  -Wmissing-braces  -Wmissing-field-initializers @gol
239 -Wmissing-format-attribute  -Wmissing-include-dirs @gol
240 -Wmissing-noreturn @gol
241 -Wno-multichar  -Wnonnull  -Woverlength-strings  -Wpacked  -Wpadded @gol
242 -Wparentheses  -Wpointer-arith  -Wno-pointer-to-int-cast @gol
243 -Wredundant-decls @gol
244 -Wreturn-type  -Wsequence-point  -Wshadow @gol
245 -Wsign-compare  -Wstack-protector @gol
246 -Wstrict-aliasing -Wstrict-aliasing=2 @gol
247 -Wstring-literal-comparison @gol
248 -Wswitch  -Wswitch-default  -Wswitch-enum @gol
249 -Wsystem-headers  -Wtrigraphs  -Wundef  -Wuninitialized @gol
250 -Wunknown-pragmas  -Wno-pragmas -Wunreachable-code @gol
251 -Wunused  -Wunused-function  -Wunused-label  -Wunused-parameter @gol
252 -Wunused-value  -Wunused-variable  -Wvariadic-macros @gol
253 -Wvolatile-register-var  -Wwrite-strings}
254
255 @item C-only Warning Options
256 @gccoptlist{-Wbad-function-cast  -Wmissing-declarations @gol
257 -Wmissing-prototypes  -Wnested-externs  -Wold-style-definition @gol
258 -Wstrict-prototypes  -Wtraditional @gol
259 -Wdeclaration-after-statement -Wpointer-sign}
260
261 @item Debugging Options
262 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
263 @gccoptlist{-d@var{letters}  -dumpspecs  -dumpmachine  -dumpversion @gol
264 -fdump-unnumbered  -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
265 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
266 -fdump-ipa-all -fdump-ipa-cgraph @gol
267 -fdump-tree-all @gol
268 -fdump-tree-original@r{[}-@var{n}@r{]}  @gol
269 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
270 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
271 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
272 -fdump-tree-ch @gol
273 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
274 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
275 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
276 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
277 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
278 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
279 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
280 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
281 -fdump-tree-nrv -fdump-tree-vect @gol
282 -fdump-tree-sink @gol
283 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
284 -fdump-tree-salias @gol
285 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
286 -fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
287 -ftree-vectorizer-verbose=@var{n} @gol
288 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
289 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
290 -feliminate-unused-debug-symbols -fmem-report -fprofile-arcs @gol
291 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
292 -ftest-coverage  -ftime-report -fvar-tracking @gol
293 -g  -g@var{level}  -gcoff -gdwarf-2 @gol
294 -ggdb  -gstabs  -gstabs+  -gvms  -gxcoff  -gxcoff+ @gol
295 -p  -pg  -print-file-name=@var{library}  -print-libgcc-file-name @gol
296 -print-multi-directory  -print-multi-lib @gol
297 -print-prog-name=@var{program}  -print-search-dirs  -Q @gol
298 -save-temps  -time}
299
300 @item Optimization Options
301 @xref{Optimize Options,,Options that Control Optimization}.
302 @gccoptlist{-falign-functions=@var{n}  -falign-jumps=@var{n} @gol
303 -falign-labels=@var{n}  -falign-loops=@var{n}  @gol
304 -fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
305 -fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
306 -fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
307 -fcaller-saves  -fcprop-registers  -fcse-follow-jumps @gol
308 -fcse-skip-blocks  -fcx-limited-range  -fdata-sections @gol
309 -fdelayed-branch  -fdelete-null-pointer-checks -fearly-inlining @gol
310 -fexpensive-optimizations  -ffast-math  -ffloat-store @gol
311 -fforce-addr  -ffunction-sections @gol
312 -fgcse  -fgcse-lm  -fgcse-sm  -fgcse-las  -fgcse-after-reload @gol
313 -fcrossjumping  -fif-conversion  -fif-conversion2 @gol
314 -finline-functions  -finline-functions-called-once @gol
315 -finline-limit=@var{n}  -fkeep-inline-functions @gol
316 -fkeep-static-consts  -fmerge-constants  -fmerge-all-constants @gol
317 -fmodulo-sched -fno-branch-count-reg @gol
318 -fno-default-inline  -fno-defer-pop -fmove-loop-invariants @gol
319 -fno-function-cse  -fno-guess-branch-probability @gol
320 -fno-inline  -fno-math-errno  -fno-peephole  -fno-peephole2 @gol
321 -funsafe-math-optimizations  -funsafe-loop-optimizations  -ffinite-math-only @gol
322 -fno-toplevel-reorder -fno-trapping-math  -fno-zero-initialized-in-bss @gol
323 -fomit-frame-pointer  -foptimize-register-move @gol
324 -foptimize-sibling-calls  -fprefetch-loop-arrays @gol
325 -fprofile-generate -fprofile-use @gol
326 -fregmove  -frename-registers @gol
327 -freorder-blocks  -freorder-blocks-and-partition -freorder-functions @gol
328 -frerun-cse-after-loop @gol
329 -frounding-math -frtl-abstract-sequences @gol
330 -fschedule-insns  -fschedule-insns2 @gol
331 -fno-sched-interblock  -fno-sched-spec  -fsched-spec-load @gol
332 -fsched-spec-load-dangerous  @gol
333 -fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
334 -fsched2-use-superblocks @gol
335 -fsched2-use-traces -freschedule-modulo-scheduled-loops @gol
336 -fsection-anchors  -fsignaling-nans  -fsingle-precision-constant @gol
337 -fstack-protector  -fstack-protector-all @gol
338 -fstrict-aliasing  -ftracer  -fthread-jumps @gol
339 -funroll-all-loops  -funroll-loops  -fpeel-loops @gol
340 -fsplit-ivs-in-unroller -funswitch-loops @gol
341 -fvariable-expansion-in-unroller @gol
342 -ftree-pre  -ftree-ccp  -ftree-dce -ftree-loop-optimize @gol
343 -ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
344 -ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
345 -ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
346 -ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
347 -ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
348 --param @var{name}=@var{value}
349 -O  -O0  -O1  -O2  -O3  -Os}
350
351 @item Preprocessor Options
352 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
353 @gccoptlist{-A@var{question}=@var{answer} @gol
354 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
355 -C  -dD  -dI  -dM  -dN @gol
356 -D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H @gol
357 -idirafter @var{dir} @gol
358 -include @var{file}  -imacros @var{file} @gol
359 -iprefix @var{file}  -iwithprefix @var{dir} @gol
360 -iwithprefixbefore @var{dir}  -isystem @var{dir} @gol
361 -imultilib @var{dir} -isysroot @var{dir} @gol
362 -M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  @gol
363 -P  -fworking-directory  -remap @gol
364 -trigraphs  -undef  -U@var{macro}  -Wp,@var{option} @gol
365 -Xpreprocessor @var{option}}
366
367 @item Assembler Option
368 @xref{Assembler Options,,Passing Options to the Assembler}.
369 @gccoptlist{-Wa,@var{option}  -Xassembler @var{option}}
370
371 @item Linker Options
372 @xref{Link Options,,Options for Linking}.
373 @gccoptlist{@var{object-file-name}  -l@var{library} @gol
374 -nostartfiles  -nodefaultlibs  -nostdlib -pie -rdynamic @gol
375 -s  -static  -static-libgcc  -shared  -shared-libgcc  -symbolic @gol
376 -Wl,@var{option}  -Xlinker @var{option} @gol
377 -u @var{symbol}}
378
379 @item Directory Options
380 @xref{Directory Options,,Options for Directory Search}.
381 @gccoptlist{-B@var{prefix}  -I@var{dir}  -iquote@var{dir}  -L@var{dir}
382 -specs=@var{file}  -I- --sysroot=@var{dir}}
383
384 @item Target Options
385 @c I wrote this xref this way to avoid overfull hbox. -- rms
386 @xref{Target Options}.
387 @gccoptlist{-V @var{version}  -b @var{machine}}
388
389 @item Machine Dependent Options
390 @xref{Submodel Options,,Hardware Models and Configurations}.
391 @c This list is ordered alphanumerically by subsection name.
392 @c Try and put the significant identifier (CPU or system) first,
393 @c so users have a clue at guessing where the ones they want will be.
394
395 @emph{ARC Options}
396 @gccoptlist{-EB  -EL @gol
397 -mmangle-cpu  -mcpu=@var{cpu}  -mtext=@var{text-section} @gol
398 -mdata=@var{data-section}  -mrodata=@var{readonly-data-section}}
399
400 @emph{ARM Options}
401 @gccoptlist{-mapcs-frame  -mno-apcs-frame @gol
402 -mabi=@var{name} @gol
403 -mapcs-stack-check  -mno-apcs-stack-check @gol
404 -mapcs-float  -mno-apcs-float @gol
405 -mapcs-reentrant  -mno-apcs-reentrant @gol
406 -msched-prolog  -mno-sched-prolog @gol
407 -mlittle-endian  -mbig-endian  -mwords-little-endian @gol
408 -mfloat-abi=@var{name}  -msoft-float  -mhard-float  -mfpe @gol
409 -mthumb-interwork  -mno-thumb-interwork @gol
410 -mcpu=@var{name}  -march=@var{name}  -mfpu=@var{name}  @gol
411 -mstructure-size-boundary=@var{n} @gol
412 -mabort-on-noreturn @gol
413 -mlong-calls  -mno-long-calls @gol
414 -msingle-pic-base  -mno-single-pic-base @gol
415 -mpic-register=@var{reg} @gol
416 -mnop-fun-dllimport @gol
417 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
418 -mpoke-function-name @gol
419 -mthumb  -marm @gol
420 -mtpcs-frame  -mtpcs-leaf-frame @gol
421 -mcaller-super-interworking  -mcallee-super-interworking @gol
422 -mtp=@var{name}}
423
424 @emph{AVR Options}
425 @gccoptlist{-mmcu=@var{mcu}  -msize  -minit-stack=@var{n}  -mno-interrupts @gol
426 -mcall-prologues  -mno-tablejump  -mtiny-stack  -mint8}
427
428 @emph{Blackfin Options}
429 @gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
430 -mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
431 -mlow-64k -mno-low64k -mid-shared-library @gol
432 -mno-id-shared-library -mshared-library-id=@var{n} @gol
433 -mlong-calls  -mno-long-calls}
434
435 @emph{CRIS Options}
436 @gccoptlist{-mcpu=@var{cpu}  -march=@var{cpu}  -mtune=@var{cpu} @gol
437 -mmax-stack-frame=@var{n}  -melinux-stacksize=@var{n} @gol
438 -metrax4  -metrax100  -mpdebug  -mcc-init  -mno-side-effects @gol
439 -mstack-align  -mdata-align  -mconst-align @gol
440 -m32-bit  -m16-bit  -m8-bit  -mno-prologue-epilogue  -mno-gotplt @gol
441 -melf  -maout  -melinux  -mlinux  -sim  -sim2 @gol
442 -mmul-bug-workaround  -mno-mul-bug-workaround}
443
444 @emph{CRX Options}
445 @gccoptlist{-mmac -mpush-args}
446
447 @emph{Darwin Options}
448 @gccoptlist{-all_load  -allowable_client  -arch  -arch_errors_fatal @gol
449 -arch_only  -bind_at_load  -bundle  -bundle_loader @gol
450 -client_name  -compatibility_version  -current_version @gol
451 -dead_strip @gol
452 -dependency-file  -dylib_file  -dylinker_install_name @gol
453 -dynamic  -dynamiclib  -exported_symbols_list @gol
454 -filelist  -flat_namespace  -force_cpusubtype_ALL @gol
455 -force_flat_namespace  -headerpad_max_install_names @gol
456 -image_base  -init  -install_name  -keep_private_externs @gol
457 -multi_module  -multiply_defined  -multiply_defined_unused @gol
458 -noall_load   -no_dead_strip_inits_and_terms @gol
459 -nofixprebinding -nomultidefs  -noprebind  -noseglinkedit @gol
460 -pagezero_size  -prebind  -prebind_all_twolevel_modules @gol
461 -private_bundle  -read_only_relocs  -sectalign @gol
462 -sectobjectsymbols  -whyload  -seg1addr @gol
463 -sectcreate  -sectobjectsymbols  -sectorder @gol
464 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
465 -seg_addr_table  -seg_addr_table_filename  -seglinkedit @gol
466 -segprot  -segs_read_only_addr  -segs_read_write_addr @gol
467 -single_module  -static  -sub_library  -sub_umbrella @gol
468 -twolevel_namespace  -umbrella  -undefined @gol
469 -unexported_symbols_list  -weak_reference_mismatches @gol
470 -whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
471 -mone-byte-bool}
472
473 @emph{DEC Alpha Options}
474 @gccoptlist{-mno-fp-regs  -msoft-float  -malpha-as  -mgas @gol
475 -mieee  -mieee-with-inexact  -mieee-conformant @gol
476 -mfp-trap-mode=@var{mode}  -mfp-rounding-mode=@var{mode} @gol
477 -mtrap-precision=@var{mode}  -mbuild-constants @gol
478 -mcpu=@var{cpu-type}  -mtune=@var{cpu-type} @gol
479 -mbwx  -mmax  -mfix  -mcix @gol
480 -mfloat-vax  -mfloat-ieee @gol
481 -mexplicit-relocs  -msmall-data  -mlarge-data @gol
482 -msmall-text  -mlarge-text @gol
483 -mmemory-latency=@var{time}}
484
485 @emph{DEC Alpha/VMS Options}
486 @gccoptlist{-mvms-return-codes}
487
488 @emph{FRV Options}
489 @gccoptlist{-mgpr-32  -mgpr-64  -mfpr-32  -mfpr-64 @gol
490 -mhard-float  -msoft-float @gol
491 -malloc-cc  -mfixed-cc  -mdword  -mno-dword @gol
492 -mdouble  -mno-double @gol
493 -mmedia  -mno-media  -mmuladd  -mno-muladd @gol
494 -mfdpic  -minline-plt -mgprel-ro  -multilib-library-pic @gol
495 -mlinked-fp  -mlong-calls  -malign-labels @gol
496 -mlibrary-pic  -macc-4  -macc-8 @gol
497 -mpack  -mno-pack  -mno-eflags  -mcond-move  -mno-cond-move @gol
498 -moptimize-membar -mno-optimize-membar @gol
499 -mscc  -mno-scc  -mcond-exec  -mno-cond-exec @gol
500 -mvliw-branch  -mno-vliw-branch @gol
501 -mmulti-cond-exec  -mno-multi-cond-exec  -mnested-cond-exec @gol
502 -mno-nested-cond-exec  -mtomcat-stats @gol
503 -mTLS -mtls @gol
504 -mcpu=@var{cpu}}
505
506 @emph{GNU/Linux Options}
507 @gccoptlist{-muclibc}
508
509 @emph{H8/300 Options}
510 @gccoptlist{-mrelax  -mh  -ms  -mn  -mint32  -malign-300}
511
512 @emph{HPPA Options}
513 @gccoptlist{-march=@var{architecture-type} @gol
514 -mbig-switch  -mdisable-fpregs  -mdisable-indexing @gol
515 -mfast-indirect-calls  -mgas  -mgnu-ld   -mhp-ld @gol
516 -mfixed-range=@var{register-range} @gol
517 -mjump-in-delay -mlinker-opt -mlong-calls @gol
518 -mlong-load-store  -mno-big-switch  -mno-disable-fpregs @gol
519 -mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas @gol
520 -mno-jump-in-delay  -mno-long-load-store @gol
521 -mno-portable-runtime  -mno-soft-float @gol
522 -mno-space-regs  -msoft-float  -mpa-risc-1-0 @gol
523 -mpa-risc-1-1  -mpa-risc-2-0  -mportable-runtime @gol
524 -mschedule=@var{cpu-type}  -mspace-regs  -msio  -mwsio @gol
525 -munix=@var{unix-std}  -nolibdld  -static  -threads}
526
527 @emph{i386 and x86-64 Options}
528 @gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
529 -mfpmath=@var{unit} @gol
530 -masm=@var{dialect}  -mno-fancy-math-387 @gol
531 -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib @gol
532 -mno-wide-multiply  -mrtd  -malign-double @gol
533 -mpreferred-stack-boundary=@var{num} @gol
534 -mmmx  -msse  -msse2 -msse3 -m3dnow -msselibm @gol
535 -mthreads  -mno-align-stringops  -minline-all-stringops @gol
536 -mpush-args  -maccumulate-outgoing-args  -m128bit-long-double @gol
537 -m96bit-long-double  -mregparm=@var{num}  -msseregparm @gol
538 -momit-leaf-frame-pointer  -mno-red-zone -mno-tls-direct-seg-refs @gol
539 -mcmodel=@var{code-model} @gol
540 -m32  -m64 -mlarge-data-threshold=@var{num}}
541
542 @emph{IA-64 Options}
543 @gccoptlist{-mbig-endian  -mlittle-endian  -mgnu-as  -mgnu-ld  -mno-pic @gol
544 -mvolatile-asm-stop  -mregister-names  -mno-sdata @gol
545 -mconstant-gp  -mauto-pic  -minline-float-divide-min-latency @gol
546 -minline-float-divide-max-throughput @gol
547 -minline-int-divide-min-latency @gol
548 -minline-int-divide-max-throughput  @gol
549 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
550 -mno-dwarf2-asm -mearly-stop-bits @gol
551 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
552 -mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
553 -mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
554 -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
555 -msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
556 -mno-sched-prefer-non-data-spec-insns @gol
557 -mno-sched-prefer-non-control-spec-insns @gol
558 -mno-sched-count-spec-in-critical-path}
559
560 @emph{M32R/D Options}
561 @gccoptlist{-m32r2 -m32rx -m32r @gol
562 -mdebug @gol
563 -malign-loops -mno-align-loops @gol
564 -missue-rate=@var{number} @gol
565 -mbranch-cost=@var{number} @gol
566 -mmodel=@var{code-size-model-type} @gol
567 -msdata=@var{sdata-type} @gol
568 -mno-flush-func -mflush-func=@var{name} @gol
569 -mno-flush-trap -mflush-trap=@var{number} @gol
570 -G @var{num}}
571
572 @emph{M32C Options}
573 @gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
574
575 @emph{M680x0 Options}
576 @gccoptlist{-m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040 @gol
577 -m68060  -mcpu32  -m5200  -mcfv4e -m68881  -mbitfield  @gol
578 -mc68000  -mc68020   @gol
579 -mnobitfield  -mrtd  -mshort  -msoft-float  -mpcrel @gol
580 -malign-int  -mstrict-align  -msep-data  -mno-sep-data @gol
581 -mshared-library-id=n  -mid-shared-library  -mno-id-shared-library}
582
583 @emph{M68hc1x Options}
584 @gccoptlist{-m6811  -m6812  -m68hc11  -m68hc12   -m68hcs12 @gol
585 -mauto-incdec  -minmax  -mlong-calls  -mshort @gol
586 -msoft-reg-count=@var{count}}
587
588 @emph{MCore Options}
589 @gccoptlist{-mhardlit  -mno-hardlit  -mdiv  -mno-div  -mrelax-immediates @gol
590 -mno-relax-immediates  -mwide-bitfields  -mno-wide-bitfields @gol
591 -m4byte-functions  -mno-4byte-functions  -mcallgraph-data @gol
592 -mno-callgraph-data  -mslow-bytes  -mno-slow-bytes  -mno-lsim @gol
593 -mlittle-endian  -mbig-endian  -m210  -m340  -mstack-increment}
594
595 @emph{MIPS Options}
596 @gccoptlist{-EL  -EB  -march=@var{arch}  -mtune=@var{arch} @gol
597 -mips1  -mips2  -mips3  -mips4  -mips32  -mips32r2  -mips64 @gol
598 -mips16  -mno-mips16  -mabi=@var{abi}  -mabicalls  -mno-abicalls @gol
599 -mshared  -mno-shared  -mxgot  -mno-xgot  -mgp32  -mgp64  @gol
600 -mfp32  -mfp64  -mhard-float  -msoft-float  @gol
601 -msingle-float  -mdouble-float  -mdsp  -mpaired-single  -mips3d @gol
602 -mlong64  -mlong32  -msym32  -mno-sym32 @gol
603 -G@var{num}  -membedded-data  -mno-embedded-data @gol
604 -muninit-const-in-rodata  -mno-uninit-const-in-rodata @gol
605 -msplit-addresses  -mno-split-addresses  @gol
606 -mexplicit-relocs  -mno-explicit-relocs  @gol
607 -mcheck-zero-division  -mno-check-zero-division @gol
608 -mdivide-traps  -mdivide-breaks @gol
609 -mmemcpy  -mno-memcpy  -mlong-calls  -mno-long-calls @gol
610 -mmad  -mno-mad  -mfused-madd  -mno-fused-madd  -nocpp @gol
611 -mfix-r4000  -mno-fix-r4000  -mfix-r4400  -mno-fix-r4400 @gol
612 -mfix-vr4120  -mno-fix-vr4120  -mfix-vr4130 @gol
613 -mfix-sb1  -mno-fix-sb1 @gol
614 -mflush-func=@var{func}  -mno-flush-func @gol
615 -mbranch-likely  -mno-branch-likely @gol
616 -mfp-exceptions -mno-fp-exceptions @gol
617 -mvr4130-align -mno-vr4130-align}
618
619 @emph{MMIX Options}
620 @gccoptlist{-mlibfuncs  -mno-libfuncs  -mepsilon  -mno-epsilon  -mabi=gnu @gol
621 -mabi=mmixware  -mzero-extend  -mknuthdiv  -mtoplevel-symbols @gol
622 -melf  -mbranch-predict  -mno-branch-predict  -mbase-addresses @gol
623 -mno-base-addresses  -msingle-exit  -mno-single-exit}
624
625 @emph{MN10300 Options}
626 @gccoptlist{-mmult-bug  -mno-mult-bug @gol
627 -mam33  -mno-am33 @gol
628 -mam33-2  -mno-am33-2 @gol
629 -mreturn-pointer-on-d0 @gol
630 -mno-crt0  -mrelax}
631
632 @emph{MT Options}
633 @gccoptlist{-mno-crt0 -mbacc -msim @gol
634 -march=@var{cpu-type} }
635
636 @emph{PDP-11 Options}
637 @gccoptlist{-mfpu  -msoft-float  -mac0  -mno-ac0  -m40  -m45  -m10 @gol
638 -mbcopy  -mbcopy-builtin  -mint32  -mno-int16 @gol
639 -mint16  -mno-int32  -mfloat32  -mno-float64 @gol
640 -mfloat64  -mno-float32  -mabshi  -mno-abshi @gol
641 -mbranch-expensive  -mbranch-cheap @gol
642 -msplit  -mno-split  -munix-asm  -mdec-asm}
643
644 @emph{PowerPC Options}
645 See RS/6000 and PowerPC Options.
646
647 @emph{RS/6000 and PowerPC Options}
648 @gccoptlist{-mcpu=@var{cpu-type} @gol
649 -mtune=@var{cpu-type} @gol
650 -mpower  -mno-power  -mpower2  -mno-power2 @gol
651 -mpowerpc  -mpowerpc64  -mno-powerpc @gol
652 -maltivec  -mno-altivec @gol
653 -mpowerpc-gpopt  -mno-powerpc-gpopt @gol
654 -mpowerpc-gfxopt  -mno-powerpc-gfxopt @gol
655 -mmfcrf  -mno-mfcrf  -mpopcntb  -mno-popcntb  -mfprnd  -mno-fprnd @gol
656 -mnew-mnemonics  -mold-mnemonics @gol
657 -mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc @gol
658 -m64  -m32  -mxl-compat  -mno-xl-compat  -mpe @gol
659 -malign-power  -malign-natural @gol
660 -msoft-float  -mhard-float  -mmultiple  -mno-multiple @gol
661 -mstring  -mno-string  -mupdate  -mno-update @gol
662 -mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align @gol
663 -mstrict-align  -mno-strict-align  -mrelocatable @gol
664 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
665 -mtoc  -mno-toc  -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
666 -mdynamic-no-pic  -maltivec  -mswdiv @gol
667 -mprioritize-restricted-insns=@var{priority} @gol
668 -msched-costly-dep=@var{dependence_type} @gol
669 -minsert-sched-nops=@var{scheme} @gol
670 -mcall-sysv  -mcall-netbsd @gol
671 -maix-struct-return  -msvr4-struct-return @gol
672 -mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
673 -misel -mno-isel @gol
674 -misel=yes  -misel=no @gol
675 -mspe -mno-spe @gol
676 -mspe=yes  -mspe=no @gol
677 -mvrsave -mno-vrsave @gol
678 -mmulhw -mno-mulhw @gol
679 -mdlmzb -mno-dlmzb @gol
680 -mfloat-gprs=yes  -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
681 -mprototype  -mno-prototype @gol
682 -msim  -mmvme  -mads  -myellowknife  -memb  -msdata @gol
683 -msdata=@var{opt}  -mvxworks  -mwindiss  -G @var{num}  -pthread}
684
685 @emph{S/390 and zSeries Options}
686 @gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
687 -mhard-float  -msoft-float -mlong-double-64 -mlong-double-128 @gol
688 -mbackchain  -mno-backchain -mpacked-stack  -mno-packed-stack @gol
689 -msmall-exec  -mno-small-exec  -mmvcle -mno-mvcle @gol
690 -m64  -m31  -mdebug  -mno-debug  -mesa  -mzarch @gol
691 -mtpf-trace -mno-tpf-trace  -mfused-madd  -mno-fused-madd @gol
692 -mwarn-framesize  -mwarn-dynamicstack  -mstack-size -mstack-guard}
693
694 @emph{SH Options}
695 @gccoptlist{-m1  -m2  -m2e  -m3  -m3e @gol
696 -m4-nofpu  -m4-single-only  -m4-single  -m4 @gol
697 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
698 -m5-64media  -m5-64media-nofpu @gol
699 -m5-32media  -m5-32media-nofpu @gol
700 -m5-compact  -m5-compact-nofpu @gol
701 -mb  -ml  -mdalign  -mrelax @gol
702 -mbigtable  -mfmovd  -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
703 -mieee  -misize  -mpadstruct  -mspace @gol
704 -mprefergot  -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
705 -mdivsi3_libfunc=@var{name}  @gol
706 -madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
707  -minvalid-symbols}
708
709 @emph{SPARC Options}
710 @gccoptlist{-mcpu=@var{cpu-type} @gol
711 -mtune=@var{cpu-type} @gol
712 -mcmodel=@var{code-model} @gol
713 -m32  -m64  -mapp-regs  -mno-app-regs @gol
714 -mfaster-structs  -mno-faster-structs @gol
715 -mfpu  -mno-fpu  -mhard-float  -msoft-float @gol
716 -mhard-quad-float  -msoft-quad-float @gol
717 -mimpure-text  -mno-impure-text  -mlittle-endian @gol
718 -mstack-bias  -mno-stack-bias @gol
719 -munaligned-doubles  -mno-unaligned-doubles @gol
720 -mv8plus  -mno-v8plus  -mvis  -mno-vis
721 -threads -pthreads -pthread}
722
723 @emph{System V Options}
724 @gccoptlist{-Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}}
725
726 @emph{TMS320C3x/C4x Options}
727 @gccoptlist{-mcpu=@var{cpu}  -mbig  -msmall  -mregparm  -mmemparm @gol
728 -mfast-fix  -mmpyi  -mbk  -mti  -mdp-isr-reload @gol
729 -mrpts=@var{count}  -mrptb  -mdb  -mloop-unsigned @gol
730 -mparallel-insns  -mparallel-mpy  -mpreserve-float}
731
732 @emph{V850 Options}
733 @gccoptlist{-mlong-calls  -mno-long-calls  -mep  -mno-ep @gol
734 -mprolog-function  -mno-prolog-function  -mspace @gol
735 -mtda=@var{n}  -msda=@var{n}  -mzda=@var{n} @gol
736 -mapp-regs  -mno-app-regs @gol
737 -mdisable-callt  -mno-disable-callt @gol
738 -mv850e1 @gol
739 -mv850e @gol
740 -mv850  -mbig-switch}
741
742 @emph{VAX Options}
743 @gccoptlist{-mg  -mgnu  -munix}
744
745 @emph{x86-64 Options}
746 See i386 and x86-64 Options.
747
748 @emph{Xstormy16 Options}
749 @gccoptlist{-msim}
750
751 @emph{Xtensa Options}
752 @gccoptlist{-mconst16 -mno-const16 @gol
753 -mfused-madd  -mno-fused-madd @gol
754 -mtext-section-literals  -mno-text-section-literals @gol
755 -mtarget-align  -mno-target-align @gol
756 -mlongcalls  -mno-longcalls}
757
758 @emph{zSeries Options}
759 See S/390 and zSeries Options.
760
761 @item Code Generation Options
762 @xref{Code Gen Options,,Options for Code Generation Conventions}.
763 @gccoptlist{-fcall-saved-@var{reg}  -fcall-used-@var{reg} @gol
764 -ffixed-@var{reg}  -fexceptions @gol
765 -fnon-call-exceptions  -funwind-tables @gol
766 -fasynchronous-unwind-tables @gol
767 -finhibit-size-directive  -finstrument-functions @gol
768 -fno-common  -fno-ident @gol
769 -fpcc-struct-return  -fpic  -fPIC -fpie -fPIE @gol
770 -fno-jump-tables @gol
771 -freg-struct-return  -fshort-enums @gol
772 -fshort-double  -fshort-wchar @gol
773 -fverbose-asm  -fpack-struct[=@var{n}]  -fstack-check @gol
774 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
775 -fargument-alias  -fargument-noalias @gol
776 -fargument-noalias-global  -fargument-noalias-anything
777 -fleading-underscore  -ftls-model=@var{model} @gol
778 -ftrapv  -fwrapv  -fbounds-check @gol
779 -fvisibility  -fopenmp}
780 @end table
781
782 @menu
783 * Overall Options::     Controlling the kind of output:
784                         an executable, object files, assembler files,
785                         or preprocessed source.
786 * C Dialect Options::   Controlling the variant of C language compiled.
787 * C++ Dialect Options:: Variations on C++.
788 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
789                         and Objective-C++.
790 * Language Independent Options:: Controlling how diagnostics should be
791                         formatted.
792 * Warning Options::     How picky should the compiler be?
793 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
794 * Optimize Options::    How much optimization?
795 * Preprocessor Options:: Controlling header files and macro definitions.
796                          Also, getting dependency information for Make.
797 * Assembler Options::   Passing options to the assembler.
798 * Link Options::        Specifying libraries and so on.
799 * Directory Options::   Where to find header files and libraries.
800                         Where to find the compiler executable files.
801 * Spec Files::          How to pass switches to sub-processes.
802 * Target Options::      Running a cross-compiler, or an old version of GCC.
803 @end menu
804
805 @node Overall Options
806 @section Options Controlling the Kind of Output
807
808 Compilation can involve up to four stages: preprocessing, compilation
809 proper, assembly and linking, always in that order.  GCC is capable of
810 preprocessing and compiling several files either into several
811 assembler input files, or into one assembler input file; then each
812 assembler input file produces an object file, and linking combines all
813 the object files (those newly compiled, and those specified as input)
814 into an executable file.
815
816 @cindex file name suffix
817 For any given input file, the file name suffix determines what kind of
818 compilation is done:
819
820 @table @gcctabopt
821 @item @var{file}.c
822 C source code which must be preprocessed.
823
824 @item @var{file}.i
825 C source code which should not be preprocessed.
826
827 @item @var{file}.ii
828 C++ source code which should not be preprocessed.
829
830 @item @var{file}.m
831 Objective-C source code.  Note that you must link with the @file{libobjc}
832 library to make an Objective-C program work.
833
834 @item @var{file}.mi
835 Objective-C source code which should not be preprocessed.
836
837 @item @var{file}.mm
838 @itemx @var{file}.M
839 Objective-C++ source code.  Note that you must link with the @file{libobjc}
840 library to make an Objective-C++ program work.  Note that @samp{.M} refers
841 to a literal capital M@.
842
843 @item @var{file}.mii
844 Objective-C++ source code which should not be preprocessed.
845
846 @item @var{file}.h
847 C, C++, Objective-C or Objective-C++ header file to be turned into a
848 precompiled header.
849
850 @item @var{file}.cc
851 @itemx @var{file}.cp
852 @itemx @var{file}.cxx
853 @itemx @var{file}.cpp
854 @itemx @var{file}.CPP
855 @itemx @var{file}.c++
856 @itemx @var{file}.C
857 C++ source code which must be preprocessed.  Note that in @samp{.cxx},
858 the last two letters must both be literally @samp{x}.  Likewise,
859 @samp{.C} refers to a literal capital C@.
860
861 @item @var{file}.mm
862 @itemx @var{file}.M
863 Objective-C++ source code which must be preprocessed.
864
865 @item @var{file}.mii
866 Objective-C++ source code which should not be preprocessed.
867
868 @item @var{file}.hh
869 @itemx @var{file}.H
870 C++ header file to be turned into a precompiled header.
871
872 @item @var{file}.f
873 @itemx @var{file}.for
874 @itemx @var{file}.FOR
875 Fixed form Fortran source code which should not be preprocessed.
876
877 @item @var{file}.F
878 @itemx @var{file}.fpp
879 @itemx @var{file}.FPP
880 Fixed form Fortran source code which must be preprocessed (with the traditional
881 preprocessor).
882
883 @item @var{file}.f90
884 @itemx @var{file}.f95
885 Free form Fortran source code which should not be preprocessed.
886
887 @item @var{file}.F90
888 @itemx @var{file}.F95
889 Free form Fortran source code which must be preprocessed (with the
890 traditional preprocessor).
891
892 @c FIXME: Descriptions of Java file types.
893 @c @var{file}.java
894 @c @var{file}.class
895 @c @var{file}.zip
896 @c @var{file}.jar
897
898 @item @var{file}.ads
899 Ada source code file which contains a library unit declaration (a
900 declaration of a package, subprogram, or generic, or a generic
901 instantiation), or a library unit renaming declaration (a package,
902 generic, or subprogram renaming declaration).  Such files are also
903 called @dfn{specs}.
904
905 @itemx @var{file}.adb
906 Ada source code file containing a library unit body (a subprogram or
907 package body).  Such files are also called @dfn{bodies}.
908
909 @c GCC also knows about some suffixes for languages not yet included:
910 @c Pascal:
911 @c @var{file}.p
912 @c @var{file}.pas
913 @c Ratfor:
914 @c @var{file}.r
915
916 @item @var{file}.s
917 Assembler code.
918
919 @item @var{file}.S
920 Assembler code which must be preprocessed.
921
922 @item @var{other}
923 An object file to be fed straight into linking.
924 Any file name with no recognized suffix is treated this way.
925 @end table
926
927 @opindex x
928 You can specify the input language explicitly with the @option{-x} option:
929
930 @table @gcctabopt
931 @item -x @var{language}
932 Specify explicitly the @var{language} for the following input files
933 (rather than letting the compiler choose a default based on the file
934 name suffix).  This option applies to all following input files until
935 the next @option{-x} option.  Possible values for @var{language} are:
936 @smallexample
937 c  c-header  c-cpp-output
938 c++  c++-header  c++-cpp-output
939 objective-c  objective-c-header  objective-c-cpp-output
940 objective-c++ objective-c++-header objective-c++-cpp-output
941 assembler  assembler-with-cpp
942 ada
943 f77  f77-cpp-input
944 f95  f95-cpp-input
945 java
946 treelang
947 @end smallexample
948
949 @item -x none
950 Turn off any specification of a language, so that subsequent files are
951 handled according to their file name suffixes (as they are if @option{-x}
952 has not been used at all).
953
954 @item -pass-exit-codes
955 @opindex pass-exit-codes
956 Normally the @command{gcc} program will exit with the code of 1 if any
957 phase of the compiler returns a non-success return code.  If you specify
958 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
959 numerically highest error produced by any phase that returned an error
960 indication.  The C, C++, and Fortran frontends return 4, if an internal
961 compiler error is encountered.
962 @end table
963
964 If you only want some of the stages of compilation, you can use
965 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
966 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
967 @command{gcc} is to stop.  Note that some combinations (for example,
968 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
969
970 @table @gcctabopt
971 @item -c
972 @opindex c
973 Compile or assemble the source files, but do not link.  The linking
974 stage simply is not done.  The ultimate output is in the form of an
975 object file for each source file.
976
977 By default, the object file name for a source file is made by replacing
978 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
979
980 Unrecognized input files, not requiring compilation or assembly, are
981 ignored.
982
983 @item -S
984 @opindex S
985 Stop after the stage of compilation proper; do not assemble.  The output
986 is in the form of an assembler code file for each non-assembler input
987 file specified.
988
989 By default, the assembler file name for a source file is made by
990 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
991
992 Input files that don't require compilation are ignored.
993
994 @item -E
995 @opindex E
996 Stop after the preprocessing stage; do not run the compiler proper.  The
997 output is in the form of preprocessed source code, which is sent to the
998 standard output.
999
1000 Input files which don't require preprocessing are ignored.
1001
1002 @cindex output file option
1003 @item -o @var{file}
1004 @opindex o
1005 Place output in file @var{file}.  This applies regardless to whatever
1006 sort of output is being produced, whether it be an executable file,
1007 an object file, an assembler file or preprocessed C code.
1008
1009 If @option{-o} is not specified, the default is to put an executable
1010 file in @file{a.out}, the object file for
1011 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1012 assembler file in @file{@var{source}.s}, a precompiled header file in
1013 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1014 standard output.
1015
1016 @item -v
1017 @opindex v
1018 Print (on standard error output) the commands executed to run the stages
1019 of compilation.  Also print the version number of the compiler driver
1020 program and of the preprocessor and the compiler proper.
1021
1022 @item -###
1023 @opindex ###
1024 Like @option{-v} except the commands are not executed and all command
1025 arguments are quoted.  This is useful for shell scripts to capture the
1026 driver-generated command lines.
1027
1028 @item -pipe
1029 @opindex pipe
1030 Use pipes rather than temporary files for communication between the
1031 various stages of compilation.  This fails to work on some systems where
1032 the assembler is unable to read from a pipe; but the GNU assembler has
1033 no trouble.
1034
1035 @item -combine
1036 @opindex combine
1037 If you are compiling multiple source files, this option tells the driver
1038 to pass all the source files to the compiler at once (for those
1039 languages for which the compiler can handle this).  This will allow
1040 intermodule analysis (IMA) to be performed by the compiler.  Currently the only
1041 language for which this is supported is C@.  If you pass source files for
1042 multiple languages to the driver, using this option, the driver will invoke
1043 the compiler(s) that support IMA once each, passing each compiler all the
1044 source files appropriate for it.  For those languages that do not support
1045 IMA this option will be ignored, and the compiler will be invoked once for
1046 each source file in that language.  If you use this option in conjunction
1047 with @option{-save-temps}, the compiler will generate multiple
1048 pre-processed files
1049 (one for each source file), but only one (combined) @file{.o} or
1050 @file{.s} file.
1051
1052 @item --help
1053 @opindex help
1054 Print (on the standard output) a description of the command line options
1055 understood by @command{gcc}.  If the @option{-v} option is also specified
1056 then @option{--help} will also be passed on to the various processes
1057 invoked by @command{gcc}, so that they can display the command line options
1058 they accept.  If the @option{-Wextra} option is also specified then command
1059 line options which have no documentation associated with them will also
1060 be displayed.
1061
1062 @item --target-help
1063 @opindex target-help
1064 Print (on the standard output) a description of target specific command
1065 line options for each tool.
1066
1067 @item --version
1068 @opindex version
1069 Display the version number and copyrights of the invoked GCC@.
1070
1071 @include @value{srcdir}/../libiberty/at-file.texi
1072 @end table
1073
1074 @node Invoking G++
1075 @section Compiling C++ Programs
1076
1077 @cindex suffixes for C++ source
1078 @cindex C++ source file suffixes
1079 C++ source files conventionally use one of the suffixes @samp{.C},
1080 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1081 @samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1082 preprocessed C++ files use the suffix @samp{.ii}.  GCC recognizes
1083 files with these names and compiles them as C++ programs even if you
1084 call the compiler the same way as for compiling C programs (usually
1085 with the name @command{gcc}).
1086
1087 @findex g++
1088 @findex c++
1089 However, C++ programs often require class libraries as well as a
1090 compiler that understands the C++ language---and under some
1091 circumstances, you might want to compile programs or header files from
1092 standard input, or otherwise without a suffix that flags them as C++
1093 programs.  You might also like to precompile a C header file with a
1094 @samp{.h} extension to be used in C++ compilations.  @command{g++} is a
1095 program that calls GCC with the default language set to C++, and
1096 automatically specifies linking against the C++ library.  On many
1097 systems, @command{g++} is also installed with the name @command{c++}.
1098
1099 @cindex invoking @command{g++}
1100 When you compile C++ programs, you may specify many of the same
1101 command-line options that you use for compiling programs in any
1102 language; or command-line options meaningful for C and related
1103 languages; or options that are meaningful only for C++ programs.
1104 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1105 explanations of options for languages related to C@.
1106 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1107 explanations of options that are meaningful only for C++ programs.
1108
1109 @node C Dialect Options
1110 @section Options Controlling C Dialect
1111 @cindex dialect options
1112 @cindex language dialect options
1113 @cindex options, dialect
1114
1115 The following options control the dialect of C (or languages derived
1116 from C, such as C++, Objective-C and Objective-C++) that the compiler
1117 accepts:
1118
1119 @table @gcctabopt
1120 @cindex ANSI support
1121 @cindex ISO support
1122 @item -ansi
1123 @opindex ansi
1124 In C mode, support all ISO C90 programs.  In C++ mode,
1125 remove GNU extensions that conflict with ISO C++.
1126
1127 This turns off certain features of GCC that are incompatible with ISO
1128 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1129 such as the @code{asm} and @code{typeof} keywords, and
1130 predefined macros such as @code{unix} and @code{vax} that identify the
1131 type of system you are using.  It also enables the undesirable and
1132 rarely used ISO trigraph feature.  For the C compiler,
1133 it disables recognition of C++ style @samp{//} comments as well as
1134 the @code{inline} keyword.
1135
1136 The alternate keywords @code{__asm__}, @code{__extension__},
1137 @code{__inline__} and @code{__typeof__} continue to work despite
1138 @option{-ansi}.  You would not want to use them in an ISO C program, of
1139 course, but it is useful to put them in header files that might be included
1140 in compilations done with @option{-ansi}.  Alternate predefined macros
1141 such as @code{__unix__} and @code{__vax__} are also available, with or
1142 without @option{-ansi}.
1143
1144 The @option{-ansi} option does not cause non-ISO programs to be
1145 rejected gratuitously.  For that, @option{-pedantic} is required in
1146 addition to @option{-ansi}.  @xref{Warning Options}.
1147
1148 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1149 option is used.  Some header files may notice this macro and refrain
1150 from declaring certain functions or defining certain macros that the
1151 ISO standard doesn't call for; this is to avoid interfering with any
1152 programs that might use these names for other things.
1153
1154 Functions which would normally be built in but do not have semantics
1155 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1156 functions with @option{-ansi} is used.  @xref{Other Builtins,,Other
1157 built-in functions provided by GCC}, for details of the functions
1158 affected.
1159
1160 @item -std=
1161 @opindex std
1162 Determine the language standard.  This option is currently only
1163 supported when compiling C or C++.  A value for this option must be
1164 provided; possible values are
1165
1166 @table @samp
1167 @item c89
1168 @itemx iso9899:1990
1169 ISO C90 (same as @option{-ansi}).
1170
1171 @item iso9899:199409
1172 ISO C90 as modified in amendment 1.
1173
1174 @item c99
1175 @itemx c9x
1176 @itemx iso9899:1999
1177 @itemx iso9899:199x
1178 ISO C99.  Note that this standard is not yet fully supported; see
1179 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information.  The
1180 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1181
1182 @item gnu89
1183 Default, ISO C90 plus GNU extensions (including some C99 features).
1184
1185 @item gnu99
1186 @itemx gnu9x
1187 ISO C99 plus GNU extensions.  When ISO C99 is fully implemented in GCC,
1188 this will become the default.  The name @samp{gnu9x} is deprecated.
1189
1190 @item c++98
1191 The 1998 ISO C++ standard plus amendments.
1192
1193 @item gnu++98
1194 The same as @option{-std=c++98} plus GNU extensions.  This is the
1195 default for C++ code.
1196 @end table
1197
1198 Even when this option is not specified, you can still use some of the
1199 features of newer standards in so far as they do not conflict with
1200 previous C standards.  For example, you may use @code{__restrict__} even
1201 when @option{-std=c99} is not specified.
1202
1203 The @option{-std} options specifying some version of ISO C have the same
1204 effects as @option{-ansi}, except that features that were not in ISO C90
1205 but are in the specified version (for example, @samp{//} comments and
1206 the @code{inline} keyword in ISO C99) are not disabled.
1207
1208 @xref{Standards,,Language Standards Supported by GCC}, for details of
1209 these standard versions.
1210
1211 @item -aux-info @var{filename}
1212 @opindex aux-info
1213 Output to the given filename prototyped declarations for all functions
1214 declared and/or defined in a translation unit, including those in header
1215 files.  This option is silently ignored in any language other than C@.
1216
1217 Besides declarations, the file indicates, in comments, the origin of
1218 each declaration (source file and line), whether the declaration was
1219 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1220 @samp{O} for old, respectively, in the first character after the line
1221 number and the colon), and whether it came from a declaration or a
1222 definition (@samp{C} or @samp{F}, respectively, in the following
1223 character).  In the case of function definitions, a K&R-style list of
1224 arguments followed by their declarations is also provided, inside
1225 comments, after the declaration.
1226
1227 @item -fno-asm
1228 @opindex fno-asm
1229 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1230 keyword, so that code can use these words as identifiers.  You can use
1231 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1232 instead.  @option{-ansi} implies @option{-fno-asm}.
1233
1234 In C++, this switch only affects the @code{typeof} keyword, since
1235 @code{asm} and @code{inline} are standard keywords.  You may want to
1236 use the @option{-fno-gnu-keywords} flag instead, which has the same
1237 effect.  In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1238 switch only affects the @code{asm} and @code{typeof} keywords, since
1239 @code{inline} is a standard keyword in ISO C99.
1240
1241 @item -fno-builtin
1242 @itemx -fno-builtin-@var{function}
1243 @opindex fno-builtin
1244 @cindex built-in functions
1245 Don't recognize built-in functions that do not begin with
1246 @samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
1247 functions provided by GCC}, for details of the functions affected,
1248 including those which are not built-in functions when @option{-ansi} or
1249 @option{-std} options for strict ISO C conformance are used because they
1250 do not have an ISO standard meaning.
1251
1252 GCC normally generates special code to handle certain built-in functions
1253 more efficiently; for instance, calls to @code{alloca} may become single
1254 instructions that adjust the stack directly, and calls to @code{memcpy}
1255 may become inline copy loops.  The resulting code is often both smaller
1256 and faster, but since the function calls no longer appear as such, you
1257 cannot set a breakpoint on those calls, nor can you change the behavior
1258 of the functions by linking with a different library.  In addition,
1259 when a function is recognized as a built-in function, GCC may use
1260 information about that function to warn about problems with calls to
1261 that function, or to generate more efficient code, even if the
1262 resulting code still contains calls to that function.  For example,
1263 warnings are given with @option{-Wformat} for bad calls to
1264 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1265 known not to modify global memory.
1266
1267 With the @option{-fno-builtin-@var{function}} option
1268 only the built-in function @var{function} is
1269 disabled.  @var{function} must not begin with @samp{__builtin_}.  If a
1270 function is named this is not built-in in this version of GCC, this
1271 option is ignored.  There is no corresponding
1272 @option{-fbuiltin-@var{function}} option; if you wish to enable
1273 built-in functions selectively when using @option{-fno-builtin} or
1274 @option{-ffreestanding}, you may define macros such as:
1275
1276 @smallexample
1277 #define abs(n)          __builtin_abs ((n))
1278 #define strcpy(d, s)    __builtin_strcpy ((d), (s))
1279 @end smallexample
1280
1281 @item -fhosted
1282 @opindex fhosted
1283 @cindex hosted environment
1284
1285 Assert that compilation takes place in a hosted environment.  This implies
1286 @option{-fbuiltin}.  A hosted environment is one in which the
1287 entire standard library is available, and in which @code{main} has a return
1288 type of @code{int}.  Examples are nearly everything except a kernel.
1289 This is equivalent to @option{-fno-freestanding}.
1290
1291 @item -ffreestanding
1292 @opindex ffreestanding
1293 @cindex hosted environment
1294
1295 Assert that compilation takes place in a freestanding environment.  This
1296 implies @option{-fno-builtin}.  A freestanding environment
1297 is one in which the standard library may not exist, and program startup may
1298 not necessarily be at @code{main}.  The most obvious example is an OS kernel.
1299 This is equivalent to @option{-fno-hosted}.
1300
1301 @xref{Standards,,Language Standards Supported by GCC}, for details of
1302 freestanding and hosted environments.
1303
1304 @item -fms-extensions
1305 @opindex fms-extensions
1306 Accept some non-standard constructs used in Microsoft header files.
1307
1308 Some cases of unnamed fields in structures and unions are only
1309 accepted with this option.  @xref{Unnamed Fields,,Unnamed struct/union
1310 fields within structs/unions}, for details.
1311
1312 @item -trigraphs
1313 @opindex trigraphs
1314 Support ISO C trigraphs.  The @option{-ansi} option (and @option{-std}
1315 options for strict ISO C conformance) implies @option{-trigraphs}.
1316
1317 @item -no-integrated-cpp
1318 @opindex no-integrated-cpp
1319 Performs a compilation in two passes: preprocessing and compiling.  This
1320 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1321 @option{-B} option.  The user supplied compilation step can then add in
1322 an additional preprocessing step after normal preprocessing but before
1323 compiling.  The default is to use the integrated cpp (internal cpp)
1324
1325 The semantics of this option will change if "cc1", "cc1plus", and
1326 "cc1obj" are merged.
1327
1328 @cindex traditional C language
1329 @cindex C language, traditional
1330 @item -traditional
1331 @itemx -traditional-cpp
1332 @opindex traditional-cpp
1333 @opindex traditional
1334 Formerly, these options caused GCC to attempt to emulate a pre-standard
1335 C compiler.  They are now only supported with the @option{-E} switch.
1336 The preprocessor continues to support a pre-standard mode.  See the GNU
1337 CPP manual for details.
1338
1339 @item -fcond-mismatch
1340 @opindex fcond-mismatch
1341 Allow conditional expressions with mismatched types in the second and
1342 third arguments.  The value of such an expression is void.  This option
1343 is not supported for C++.
1344
1345 @item -funsigned-char
1346 @opindex funsigned-char
1347 Let the type @code{char} be unsigned, like @code{unsigned char}.
1348
1349 Each kind of machine has a default for what @code{char} should
1350 be.  It is either like @code{unsigned char} by default or like
1351 @code{signed char} by default.
1352
1353 Ideally, a portable program should always use @code{signed char} or
1354 @code{unsigned char} when it depends on the signedness of an object.
1355 But many programs have been written to use plain @code{char} and
1356 expect it to be signed, or expect it to be unsigned, depending on the
1357 machines they were written for.  This option, and its inverse, let you
1358 make such a program work with the opposite default.
1359
1360 The type @code{char} is always a distinct type from each of
1361 @code{signed char} or @code{unsigned char}, even though its behavior
1362 is always just like one of those two.
1363
1364 @item -fsigned-char
1365 @opindex fsigned-char
1366 Let the type @code{char} be signed, like @code{signed char}.
1367
1368 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1369 the negative form of @option{-funsigned-char}.  Likewise, the option
1370 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1371
1372 @item -fsigned-bitfields
1373 @itemx -funsigned-bitfields
1374 @itemx -fno-signed-bitfields
1375 @itemx -fno-unsigned-bitfields
1376 @opindex fsigned-bitfields
1377 @opindex funsigned-bitfields
1378 @opindex fno-signed-bitfields
1379 @opindex fno-unsigned-bitfields
1380 These options control whether a bit-field is signed or unsigned, when the
1381 declaration does not use either @code{signed} or @code{unsigned}.  By
1382 default, such a bit-field is signed, because this is consistent: the
1383 basic integer types such as @code{int} are signed types.
1384 @end table
1385
1386 @node C++ Dialect Options
1387 @section Options Controlling C++ Dialect
1388
1389 @cindex compiler options, C++
1390 @cindex C++ options, command line
1391 @cindex options, C++
1392 This section describes the command-line options that are only meaningful
1393 for C++ programs; but you can also use most of the GNU compiler options
1394 regardless of what language your program is in.  For example, you
1395 might compile a file @code{firstClass.C} like this:
1396
1397 @smallexample
1398 g++ -g -frepo -O -c firstClass.C
1399 @end smallexample
1400
1401 @noindent
1402 In this example, only @option{-frepo} is an option meant
1403 only for C++ programs; you can use the other options with any
1404 language supported by GCC@.
1405
1406 Here is a list of options that are @emph{only} for compiling C++ programs:
1407
1408 @table @gcctabopt
1409
1410 @item -fabi-version=@var{n}
1411 @opindex fabi-version
1412 Use version @var{n} of the C++ ABI@.  Version 2 is the version of the
1413 C++ ABI that first appeared in G++ 3.4.  Version 1 is the version of
1414 the C++ ABI that first appeared in G++ 3.2.  Version 0 will always be
1415 the version that conforms most closely to the C++ ABI specification.
1416 Therefore, the ABI obtained using version 0 will change as ABI bugs
1417 are fixed.
1418
1419 The default is version 2.
1420
1421 @item -fno-access-control
1422 @opindex fno-access-control
1423 Turn off all access checking.  This switch is mainly useful for working
1424 around bugs in the access control code.
1425
1426 @item -fcheck-new
1427 @opindex fcheck-new
1428 Check that the pointer returned by @code{operator new} is non-null
1429 before attempting to modify the storage allocated.  This check is
1430 normally unnecessary because the C++ standard specifies that
1431 @code{operator new} will only return @code{0} if it is declared
1432 @samp{throw()}, in which case the compiler will always check the
1433 return value even without this option.  In all other cases, when
1434 @code{operator new} has a non-empty exception specification, memory
1435 exhaustion is signalled by throwing @code{std::bad_alloc}.  See also
1436 @samp{new (nothrow)}.
1437
1438 @item -fconserve-space
1439 @opindex fconserve-space
1440 Put uninitialized or runtime-initialized global variables into the
1441 common segment, as C does.  This saves space in the executable at the
1442 cost of not diagnosing duplicate definitions.  If you compile with this
1443 flag and your program mysteriously crashes after @code{main()} has
1444 completed, you may have an object that is being destroyed twice because
1445 two definitions were merged.
1446
1447 This option is no longer useful on most targets, now that support has
1448 been added for putting variables into BSS without making them common.
1449
1450 @item -ffriend-injection
1451 @opindex ffriend-injection
1452 Inject friend functions into the enclosing namespace, so that they are
1453 visible outside the scope of the class in which they are declared.
1454 Friend functions were documented to work this way in the old Annotated
1455 C++ Reference Manual, and versions of G++ before 4.1 always worked
1456 that way.  However, in ISO C++ a friend function which is not declared
1457 in an enclosing scope can only be found using argument dependent
1458 lookup.  This option causes friends to be injected as they were in
1459 earlier releases.
1460
1461 This option is for compatibility, and may be removed in a future
1462 release of G++.
1463
1464 @item -fno-elide-constructors
1465 @opindex fno-elide-constructors
1466 The C++ standard allows an implementation to omit creating a temporary
1467 which is only used to initialize another object of the same type.
1468 Specifying this option disables that optimization, and forces G++ to
1469 call the copy constructor in all cases.
1470
1471 @item -fno-enforce-eh-specs
1472 @opindex fno-enforce-eh-specs
1473 Don't generate code to check for violation of exception specifications
1474 at runtime.  This option violates the C++ standard, but may be useful
1475 for reducing code size in production builds, much like defining
1476 @samp{NDEBUG}.  This does not give user code permission to throw
1477 exceptions in violation of the exception specifications; the compiler
1478 will still optimize based on the specifications, so throwing an
1479 unexpected exception will result in undefined behavior.
1480
1481 @item -ffor-scope
1482 @itemx -fno-for-scope
1483 @opindex ffor-scope
1484 @opindex fno-for-scope
1485 If @option{-ffor-scope} is specified, the scope of variables declared in
1486 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1487 as specified by the C++ standard.
1488 If @option{-fno-for-scope} is specified, the scope of variables declared in
1489 a @i{for-init-statement} extends to the end of the enclosing scope,
1490 as was the case in old versions of G++, and other (traditional)
1491 implementations of C++.
1492
1493 The default if neither flag is given to follow the standard,
1494 but to allow and give a warning for old-style code that would
1495 otherwise be invalid, or have different behavior.
1496
1497 @item -fno-gnu-keywords
1498 @opindex fno-gnu-keywords
1499 Do not recognize @code{typeof} as a keyword, so that code can use this
1500 word as an identifier.  You can use the keyword @code{__typeof__} instead.
1501 @option{-ansi} implies @option{-fno-gnu-keywords}.
1502
1503 @item -fno-implicit-templates
1504 @opindex fno-implicit-templates
1505 Never emit code for non-inline templates which are instantiated
1506 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1507 @xref{Template Instantiation}, for more information.
1508
1509 @item -fno-implicit-inline-templates
1510 @opindex fno-implicit-inline-templates
1511 Don't emit code for implicit instantiations of inline templates, either.
1512 The default is to handle inlines differently so that compiles with and
1513 without optimization will need the same set of explicit instantiations.
1514
1515 @item -fno-implement-inlines
1516 @opindex fno-implement-inlines
1517 To save space, do not emit out-of-line copies of inline functions
1518 controlled by @samp{#pragma implementation}.  This will cause linker
1519 errors if these functions are not inlined everywhere they are called.
1520
1521 @item -fms-extensions
1522 @opindex fms-extensions
1523 Disable pedantic warnings about constructs used in MFC, such as implicit
1524 int and getting a pointer to member function via non-standard syntax.
1525
1526 @item -fno-nonansi-builtins
1527 @opindex fno-nonansi-builtins
1528 Disable built-in declarations of functions that are not mandated by
1529 ANSI/ISO C@.  These include @code{ffs}, @code{alloca}, @code{_exit},
1530 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1531
1532 @item -fno-operator-names
1533 @opindex fno-operator-names
1534 Do not treat the operator name keywords @code{and}, @code{bitand},
1535 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1536 synonyms as keywords.
1537
1538 @item -fno-optional-diags
1539 @opindex fno-optional-diags
1540 Disable diagnostics that the standard says a compiler does not need to
1541 issue.  Currently, the only such diagnostic issued by G++ is the one for
1542 a name having multiple meanings within a class.
1543
1544 @item -fpermissive
1545 @opindex fpermissive
1546 Downgrade some diagnostics about nonconformant code from errors to
1547 warnings.  Thus, using @option{-fpermissive} will allow some
1548 nonconforming code to compile.
1549
1550 @item -frepo
1551 @opindex frepo
1552 Enable automatic template instantiation at link time.  This option also
1553 implies @option{-fno-implicit-templates}.  @xref{Template
1554 Instantiation}, for more information.
1555
1556 @item -fno-rtti
1557 @opindex fno-rtti
1558 Disable generation of information about every class with virtual
1559 functions for use by the C++ runtime type identification features
1560 (@samp{dynamic_cast} and @samp{typeid}).  If you don't use those parts
1561 of the language, you can save some space by using this flag.  Note that
1562 exception handling uses the same information, but it will generate it as
1563 needed.
1564
1565 @item -fstats
1566 @opindex fstats
1567 Emit statistics about front-end processing at the end of the compilation.
1568 This information is generally only useful to the G++ development team.
1569
1570 @item -ftemplate-depth-@var{n}
1571 @opindex ftemplate-depth
1572 Set the maximum instantiation depth for template classes to @var{n}.
1573 A limit on the template instantiation depth is needed to detect
1574 endless recursions during template class instantiation.  ANSI/ISO C++
1575 conforming programs must not rely on a maximum depth greater than 17.
1576
1577 @item -fno-threadsafe-statics
1578 @opindex fno-threadsafe-statics
1579 Do not emit the extra code to use the routines specified in the C++
1580 ABI for thread-safe initialization of local statics.  You can use this
1581 option to reduce code size slightly in code that doesn't need to be
1582 thread-safe.
1583
1584 @item -fuse-cxa-atexit
1585 @opindex fuse-cxa-atexit
1586 Register destructors for objects with static storage duration with the
1587 @code{__cxa_atexit} function rather than the @code{atexit} function.
1588 This option is required for fully standards-compliant handling of static
1589 destructors, but will only work if your C library supports
1590 @code{__cxa_atexit}.
1591
1592 @item -fno-use-cxa-get-exception-ptr
1593 @opindex fno-use-cxa-get-exception-ptr
1594 Don't use the @code{__cxa_get_exception_ptr} runtime routine.  This
1595 will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1596 if the runtime routine is not available.
1597
1598 @item -fvisibility-inlines-hidden
1599 @opindex fvisibility-inlines-hidden
1600 Causes all inlined methods to be marked with
1601 @code{__attribute__ ((visibility ("hidden")))} so that they do not
1602 appear in the export table of a DSO and do not require a PLT indirection
1603 when used within the DSO@.  Enabling this option can have a dramatic effect
1604 on load and link times of a DSO as it massively reduces the size of the
1605 dynamic export table when the library makes heavy use of templates.  While
1606 it can cause bloating through duplication of code within each DSO where
1607 it is used, often the wastage is less than the considerable space occupied
1608 by a long symbol name in the export table which is typical when using
1609 templates and namespaces.  For even more savings, combine with the
1610 @option{-fvisibility=hidden} switch.
1611
1612 @item -fno-weak
1613 @opindex fno-weak
1614 Do not use weak symbol support, even if it is provided by the linker.
1615 By default, G++ will use weak symbols if they are available.  This
1616 option exists only for testing, and should not be used by end-users;
1617 it will result in inferior code and has no benefits.  This option may
1618 be removed in a future release of G++.
1619
1620 @item -nostdinc++
1621 @opindex nostdinc++
1622 Do not search for header files in the standard directories specific to
1623 C++, but do still search the other standard directories.  (This option
1624 is used when building the C++ library.)
1625 @end table
1626
1627 In addition, these optimization, warning, and code generation options
1628 have meanings only for C++ programs:
1629
1630 @table @gcctabopt
1631 @item -fno-default-inline
1632 @opindex fno-default-inline
1633 Do not assume @samp{inline} for functions defined inside a class scope.
1634 @xref{Optimize Options,,Options That Control Optimization}.  Note that these
1635 functions will have linkage like inline functions; they just won't be
1636 inlined by default.
1637
1638 @item -Wabi @r{(C++ only)}
1639 @opindex Wabi
1640 Warn when G++ generates code that is probably not compatible with the
1641 vendor-neutral C++ ABI@.  Although an effort has been made to warn about
1642 all such cases, there are probably some cases that are not warned about,
1643 even though G++ is generating incompatible code.  There may also be
1644 cases where warnings are emitted even though the code that is generated
1645 will be compatible.
1646
1647 You should rewrite your code to avoid these warnings if you are
1648 concerned about the fact that code generated by G++ may not be binary
1649 compatible with code generated by other compilers.
1650
1651 The known incompatibilities at this point include:
1652
1653 @itemize @bullet
1654
1655 @item
1656 Incorrect handling of tail-padding for bit-fields.  G++ may attempt to
1657 pack data into the same byte as a base class.  For example:
1658
1659 @smallexample
1660 struct A @{ virtual void f(); int f1 : 1; @};
1661 struct B : public A @{ int f2 : 1; @};
1662 @end smallexample
1663
1664 @noindent
1665 In this case, G++ will place @code{B::f2} into the same byte
1666 as@code{A::f1}; other compilers will not.  You can avoid this problem
1667 by explicitly padding @code{A} so that its size is a multiple of the
1668 byte size on your platform; that will cause G++ and other compilers to
1669 layout @code{B} identically.
1670
1671 @item
1672 Incorrect handling of tail-padding for virtual bases.  G++ does not use
1673 tail padding when laying out virtual bases.  For example:
1674
1675 @smallexample
1676 struct A @{ virtual void f(); char c1; @};
1677 struct B @{ B(); char c2; @};
1678 struct C : public A, public virtual B @{@};
1679 @end smallexample
1680
1681 @noindent
1682 In this case, G++ will not place @code{B} into the tail-padding for
1683 @code{A}; other compilers will.  You can avoid this problem by
1684 explicitly padding @code{A} so that its size is a multiple of its
1685 alignment (ignoring virtual base classes); that will cause G++ and other
1686 compilers to layout @code{C} identically.
1687
1688 @item
1689 Incorrect handling of bit-fields with declared widths greater than that
1690 of their underlying types, when the bit-fields appear in a union.  For
1691 example:
1692
1693 @smallexample
1694 union U @{ int i : 4096; @};
1695 @end smallexample
1696
1697 @noindent
1698 Assuming that an @code{int} does not have 4096 bits, G++ will make the
1699 union too small by the number of bits in an @code{int}.
1700
1701 @item
1702 Empty classes can be placed at incorrect offsets.  For example:
1703
1704 @smallexample
1705 struct A @{@};
1706
1707 struct B @{
1708   A a;
1709   virtual void f ();
1710 @};
1711
1712 struct C : public B, public A @{@};
1713 @end smallexample
1714
1715 @noindent
1716 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1717 it should be placed at offset zero.  G++ mistakenly believes that the
1718 @code{A} data member of @code{B} is already at offset zero.
1719
1720 @item
1721 Names of template functions whose types involve @code{typename} or
1722 template template parameters can be mangled incorrectly.
1723
1724 @smallexample
1725 template <typename Q>
1726 void f(typename Q::X) @{@}
1727
1728 template <template <typename> class Q>
1729 void f(typename Q<int>::X) @{@}
1730 @end smallexample
1731
1732 @noindent
1733 Instantiations of these templates may be mangled incorrectly.
1734
1735 @end itemize
1736
1737 @item -Wctor-dtor-privacy @r{(C++ only)}
1738 @opindex Wctor-dtor-privacy
1739 Warn when a class seems unusable because all the constructors or
1740 destructors in that class are private, and it has neither friends nor
1741 public static member functions.
1742
1743 @item -Wnon-virtual-dtor @r{(C++ only)}
1744 @opindex Wnon-virtual-dtor
1745 Warn when a class appears to be polymorphic, thereby requiring a virtual
1746 destructor, yet it declares a non-virtual one.  This warning is also
1747 enabled if -Weffc++ is specified.
1748
1749 @item -Wreorder @r{(C++ only)}
1750 @opindex Wreorder
1751 @cindex reordering, warning
1752 @cindex warning for reordering of member initializers
1753 Warn when the order of member initializers given in the code does not
1754 match the order in which they must be executed.  For instance:
1755
1756 @smallexample
1757 struct A @{
1758   int i;
1759   int j;
1760   A(): j (0), i (1) @{ @}
1761 @};
1762 @end smallexample
1763
1764 The compiler will rearrange the member initializers for @samp{i}
1765 and @samp{j} to match the declaration order of the members, emitting
1766 a warning to that effect.  This warning is enabled by @option{-Wall}.
1767 @end table
1768
1769 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1770
1771 @table @gcctabopt
1772 @item -Weffc++ @r{(C++ only)}
1773 @opindex Weffc++
1774 Warn about violations of the following style guidelines from Scott Meyers'
1775 @cite{Effective C++} book:
1776
1777 @itemize @bullet
1778 @item
1779 Item 11:  Define a copy constructor and an assignment operator for classes
1780 with dynamically allocated memory.
1781
1782 @item
1783 Item 12:  Prefer initialization to assignment in constructors.
1784
1785 @item
1786 Item 14:  Make destructors virtual in base classes.
1787
1788 @item
1789 Item 15:  Have @code{operator=} return a reference to @code{*this}.
1790
1791 @item
1792 Item 23:  Don't try to return a reference when you must return an object.
1793
1794 @end itemize
1795
1796 Also warn about violations of the following style guidelines from
1797 Scott Meyers' @cite{More Effective C++} book:
1798
1799 @itemize @bullet
1800 @item
1801 Item 6:  Distinguish between prefix and postfix forms of increment and
1802 decrement operators.
1803
1804 @item
1805 Item 7:  Never overload @code{&&}, @code{||}, or @code{,}.
1806
1807 @end itemize
1808
1809 When selecting this option, be aware that the standard library
1810 headers do not obey all of these guidelines; use @samp{grep -v}
1811 to filter out those warnings.
1812
1813 @item -Wno-deprecated @r{(C++ only)}
1814 @opindex Wno-deprecated
1815 Do not warn about usage of deprecated features.  @xref{Deprecated Features}.
1816
1817 @item -Wstrict-null-sentinel @r{(C++ only)}
1818 @opindex Wstrict-null-sentinel
1819 Warn also about the use of an uncasted @code{NULL} as sentinel.  When
1820 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1821 to @code{__null}.  Although it is a null pointer constant not a null pointer,
1822 it is guaranteed to of the same size as a pointer.  But this use is
1823 not portable across different compilers.
1824
1825 @item -Wno-non-template-friend @r{(C++ only)}
1826 @opindex Wno-non-template-friend
1827 Disable warnings when non-templatized friend functions are declared
1828 within a template.  Since the advent of explicit template specification
1829 support in G++, if the name of the friend is an unqualified-id (i.e.,
1830 @samp{friend foo(int)}), the C++ language specification demands that the
1831 friend declare or define an ordinary, nontemplate function.  (Section
1832 14.5.3).  Before G++ implemented explicit specification, unqualified-ids
1833 could be interpreted as a particular specialization of a templatized
1834 function.  Because this non-conforming behavior is no longer the default
1835 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1836 check existing code for potential trouble spots and is on by default.
1837 This new compiler behavior can be turned off with
1838 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1839 but disables the helpful warning.
1840
1841 @item -Wold-style-cast @r{(C++ only)}
1842 @opindex Wold-style-cast
1843 Warn if an old-style (C-style) cast to a non-void type is used within
1844 a C++ program.  The new-style casts (@samp{dynamic_cast},
1845 @samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1846 less vulnerable to unintended effects and much easier to search for.
1847
1848 @item -Woverloaded-virtual @r{(C++ only)}
1849 @opindex Woverloaded-virtual
1850 @cindex overloaded virtual fn, warning
1851 @cindex warning for overloaded virtual fn
1852 Warn when a function declaration hides virtual functions from a
1853 base class.  For example, in:
1854
1855 @smallexample
1856 struct A @{
1857   virtual void f();
1858 @};
1859
1860 struct B: public A @{
1861   void f(int);
1862 @};
1863 @end smallexample
1864
1865 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1866 like:
1867
1868 @smallexample
1869 B* b;
1870 b->f();
1871 @end smallexample
1872
1873 will fail to compile.
1874
1875 @item -Wno-pmf-conversions @r{(C++ only)}
1876 @opindex Wno-pmf-conversions
1877 Disable the diagnostic for converting a bound pointer to member function
1878 to a plain pointer.
1879
1880 @item -Wsign-promo @r{(C++ only)}
1881 @opindex Wsign-promo
1882 Warn when overload resolution chooses a promotion from unsigned or
1883 enumerated type to a signed type, over a conversion to an unsigned type of
1884 the same size.  Previous versions of G++ would try to preserve
1885 unsignedness, but the standard mandates the current behavior.
1886
1887 @smallexample
1888 struct A @{
1889   operator int ();
1890   A& operator = (int);
1891 @};
1892
1893 main ()
1894 @{
1895   A a,b;
1896   a = b;
1897 @}
1898 @end smallexample
1899
1900 In this example, G++ will synthesize a default @samp{A& operator =
1901 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1902 @end table
1903
1904 @node Objective-C and Objective-C++ Dialect Options
1905 @section Options Controlling Objective-C and Objective-C++ Dialects
1906
1907 @cindex compiler options, Objective-C and Objective-C++
1908 @cindex Objective-C and Objective-C++ options, command line
1909 @cindex options, Objective-C and Objective-C++
1910 (NOTE: This manual does not describe the Objective-C and Objective-C++
1911 languages themselves.  See @xref{Standards,,Language Standards
1912 Supported by GCC}, for references.)
1913
1914 This section describes the command-line options that are only meaningful
1915 for Objective-C and Objective-C++ programs, but you can also use most of
1916 the language-independent GNU compiler options.
1917 For example, you might compile a file @code{some_class.m} like this:
1918
1919 @smallexample
1920 gcc -g -fgnu-runtime -O -c some_class.m
1921 @end smallexample
1922
1923 @noindent
1924 In this example, @option{-fgnu-runtime} is an option meant only for
1925 Objective-C and Objective-C++ programs; you can use the other options with
1926 any language supported by GCC@.
1927
1928 Note that since Objective-C is an extension of the C language, Objective-C
1929 compilations may also use options specific to the C front-end (e.g.,
1930 @option{-Wtraditional}).  Similarly, Objective-C++ compilations may use
1931 C++-specific options (e.g., @option{-Wabi}).
1932
1933 Here is a list of options that are @emph{only} for compiling Objective-C
1934 and Objective-C++ programs:
1935
1936 @table @gcctabopt
1937 @item -fconstant-string-class=@var{class-name}
1938 @opindex fconstant-string-class
1939 Use @var{class-name} as the name of the class to instantiate for each
1940 literal string specified with the syntax @code{@@"@dots{}"}.  The default
1941 class name is @code{NXConstantString} if the GNU runtime is being used, and
1942 @code{NSConstantString} if the NeXT runtime is being used (see below).  The
1943 @option{-fconstant-cfstrings} option, if also present, will override the
1944 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
1945 to be laid out as constant CoreFoundation strings.
1946
1947 @item -fgnu-runtime
1948 @opindex fgnu-runtime
1949 Generate object code compatible with the standard GNU Objective-C
1950 runtime.  This is the default for most types of systems.
1951
1952 @item -fnext-runtime
1953 @opindex fnext-runtime
1954 Generate output compatible with the NeXT runtime.  This is the default
1955 for NeXT-based systems, including Darwin and Mac OS X@.  The macro
1956 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
1957 used.
1958
1959 @item -fno-nil-receivers
1960 @opindex fno-nil-receivers
1961 Assume that all Objective-C message dispatches (e.g.,
1962 @code{[receiver message:arg]}) in this translation unit ensure that the receiver
1963 is not @code{nil}.  This allows for more efficient entry points in the runtime
1964 to be used.  Currently, this option is only available in conjunction with
1965 the NeXT runtime on Mac OS X 10.3 and later.
1966
1967 @item -fobjc-call-cxx-cdtors
1968 @opindex fobjc-call-cxx-cdtors
1969 For each Objective-C class, check if any of its instance variables is a
1970 C++ object with a non-trivial default constructor.  If so, synthesize a
1971 special @code{- (id) .cxx_construct} instance method that will run
1972 non-trivial default constructors on any such instance variables, in order,
1973 and then return @code{self}.  Similarly, check if any instance variable
1974 is a C++ object with a non-trivial destructor, and if so, synthesize a
1975 special @code{- (void) .cxx_destruct} method that will run
1976 all such default destructors, in reverse order.
1977
1978 The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
1979 thusly generated will only operate on instance variables declared in the
1980 current Objective-C class, and not those inherited from superclasses.  It
1981 is the responsibility of the Objective-C runtime to invoke all such methods
1982 in an object's inheritance hierarchy.  The @code{- (id) .cxx_construct} methods
1983 will be invoked by the runtime immediately after a new object
1984 instance is allocated; the @code{- (void) .cxx_destruct} methods will
1985 be invoked immediately before the runtime deallocates an object instance.
1986
1987 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
1988 support for invoking the @code{- (id) .cxx_construct} and
1989 @code{- (void) .cxx_destruct} methods.
1990
1991 @item -fobjc-direct-dispatch
1992 @opindex fobjc-direct-dispatch
1993 Allow fast jumps to the message dispatcher.  On Darwin this is
1994 accomplished via the comm page.
1995
1996 @item -fobjc-exceptions
1997 @opindex fobjc-exceptions
1998 Enable syntactic support for structured exception handling in Objective-C,
1999 similar to what is offered by C++ and Java.  This option is
2000 unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2001 earlier.
2002
2003 @smallexample
2004   @@try @{
2005     @dots{}
2006        @@throw expr;
2007     @dots{}
2008   @}
2009   @@catch (AnObjCClass *exc) @{
2010     @dots{}
2011       @@throw expr;
2012     @dots{}
2013       @@throw;
2014     @dots{}
2015   @}
2016   @@catch (AnotherClass *exc) @{
2017     @dots{}
2018   @}
2019   @@catch (id allOthers) @{
2020     @dots{}
2021   @}
2022   @@finally @{
2023     @dots{}
2024       @@throw expr;
2025     @dots{}
2026   @}
2027 @end smallexample
2028
2029 The @code{@@throw} statement may appear anywhere in an Objective-C or
2030 Objective-C++ program; when used inside of a @code{@@catch} block, the
2031 @code{@@throw} may appear without an argument (as shown above), in which case
2032 the object caught by the @code{@@catch} will be rethrown.
2033
2034 Note that only (pointers to) Objective-C objects may be thrown and
2035 caught using this scheme.  When an object is thrown, it will be caught
2036 by the nearest @code{@@catch} clause capable of handling objects of that type,
2037 analogously to how @code{catch} blocks work in C++ and Java.  A
2038 @code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2039 any and all Objective-C exceptions not caught by previous @code{@@catch}
2040 clauses (if any).
2041
2042 The @code{@@finally} clause, if present, will be executed upon exit from the
2043 immediately preceding @code{@@try @dots{} @@catch} section.  This will happen
2044 regardless of whether any exceptions are thrown, caught or rethrown
2045 inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2046 of the @code{finally} clause in Java.
2047
2048 There are several caveats to using the new exception mechanism:
2049
2050 @itemize @bullet
2051 @item
2052 Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2053 idioms provided by the @code{NSException} class, the new
2054 exceptions can only be used on Mac OS X 10.3 (Panther) and later
2055 systems, due to additional functionality needed in the (NeXT) Objective-C
2056 runtime.
2057
2058 @item
2059 As mentioned above, the new exceptions do not support handling
2060 types other than Objective-C objects.   Furthermore, when used from
2061 Objective-C++, the Objective-C exception model does not interoperate with C++
2062 exceptions at this time.  This means you cannot @code{@@throw} an exception
2063 from Objective-C and @code{catch} it in C++, or vice versa
2064 (i.e., @code{throw @dots{} @@catch}).
2065 @end itemize
2066
2067 The @option{-fobjc-exceptions} switch also enables the use of synchronization
2068 blocks for thread-safe execution:
2069
2070 @smallexample
2071   @@synchronized (ObjCClass *guard) @{
2072     @dots{}
2073   @}
2074 @end smallexample
2075
2076 Upon entering the @code{@@synchronized} block, a thread of execution shall
2077 first check whether a lock has been placed on the corresponding @code{guard}
2078 object by another thread.  If it has, the current thread shall wait until
2079 the other thread relinquishes its lock.  Once @code{guard} becomes available,
2080 the current thread will place its own lock on it, execute the code contained in
2081 the @code{@@synchronized} block, and finally relinquish the lock (thereby
2082 making @code{guard} available to other threads).
2083
2084 Unlike Java, Objective-C does not allow for entire methods to be marked
2085 @code{@@synchronized}.  Note that throwing exceptions out of
2086 @code{@@synchronized} blocks is allowed, and will cause the guarding object
2087 to be unlocked properly.
2088
2089 @item -fobjc-gc
2090 @opindex fobjc-gc
2091 Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2092
2093 @item -freplace-objc-classes
2094 @opindex freplace-objc-classes
2095 Emit a special marker instructing @command{ld(1)} not to statically link in
2096 the resulting object file, and allow @command{dyld(1)} to load it in at
2097 run time instead.  This is used in conjunction with the Fix-and-Continue
2098 debugging mode, where the object file in question may be recompiled and
2099 dynamically reloaded in the course of program execution, without the need
2100 to restart the program itself.  Currently, Fix-and-Continue functionality
2101 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2102 and later.
2103
2104 @item -fzero-link
2105 @opindex fzero-link
2106 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2107 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2108 compile time) with static class references that get initialized at load time,
2109 which improves run-time performance.  Specifying the @option{-fzero-link} flag
2110 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2111 to be retained.  This is useful in Zero-Link debugging mode, since it allows
2112 for individual class implementations to be modified during program execution.
2113
2114 @item -gen-decls
2115 @opindex gen-decls
2116 Dump interface declarations for all classes seen in the source file to a
2117 file named @file{@var{sourcename}.decl}.
2118
2119 @item -Wassign-intercept
2120 @opindex Wassign-intercept
2121 Warn whenever an Objective-C assignment is being intercepted by the
2122 garbage collector.
2123
2124 @item -Wno-protocol
2125 @opindex Wno-protocol
2126 If a class is declared to implement a protocol, a warning is issued for
2127 every method in the protocol that is not implemented by the class.  The
2128 default behavior is to issue a warning for every method not explicitly
2129 implemented in the class, even if a method implementation is inherited
2130 from the superclass.  If you use the @option{-Wno-protocol} option, then
2131 methods inherited from the superclass are considered to be implemented,
2132 and no warning is issued for them.
2133
2134 @item -Wselector
2135 @opindex Wselector
2136 Warn if multiple methods of different types for the same selector are
2137 found during compilation.  The check is performed on the list of methods
2138 in the final stage of compilation.  Additionally, a check is performed
2139 for each selector appearing in a @code{@@selector(@dots{})}
2140 expression, and a corresponding method for that selector has been found
2141 during compilation.  Because these checks scan the method table only at
2142 the end of compilation, these warnings are not produced if the final
2143 stage of compilation is not reached, for example because an error is
2144 found during compilation, or because the @option{-fsyntax-only} option is
2145 being used.
2146
2147 @item -Wstrict-selector-match
2148 @opindex Wstrict-selector-match
2149 Warn if multiple methods with differing argument and/or return types are
2150 found for a given selector when attempting to send a message using this
2151 selector to a receiver of type @code{id} or @code{Class}.  When this flag
2152 is off (which is the default behavior), the compiler will omit such warnings
2153 if any differences found are confined to types which share the same size
2154 and alignment.
2155
2156 @item -Wundeclared-selector
2157 @opindex Wundeclared-selector
2158 Warn if a @code{@@selector(@dots{})} expression referring to an
2159 undeclared selector is found.  A selector is considered undeclared if no
2160 method with that name has been declared before the
2161 @code{@@selector(@dots{})} expression, either explicitly in an
2162 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
2163 an @code{@@implementation} section.  This option always performs its
2164 checks as soon as a @code{@@selector(@dots{})} expression is found,
2165 while @option{-Wselector} only performs its checks in the final stage of
2166 compilation.  This also enforces the coding style convention
2167 that methods and selectors must be declared before being used.
2168
2169 @item -print-objc-runtime-info
2170 @opindex print-objc-runtime-info
2171 Generate C header describing the largest structure that is passed by
2172 value, if any.
2173
2174 @end table
2175
2176 @node Language Independent Options
2177 @section Options to Control Diagnostic Messages Formatting
2178 @cindex options to control diagnostics formatting
2179 @cindex diagnostic messages
2180 @cindex message formatting
2181
2182 Traditionally, diagnostic messages have been formatted irrespective of
2183 the output device's aspect (e.g.@: its width, @dots{}).  The options described
2184 below can be used to control the diagnostic messages formatting
2185 algorithm, e.g.@: how many characters per line, how often source location
2186 information should be reported.  Right now, only the C++ front end can
2187 honor these options.  However it is expected, in the near future, that
2188 the remaining front ends would be able to digest them correctly.
2189
2190 @table @gcctabopt
2191 @item -fmessage-length=@var{n}
2192 @opindex fmessage-length
2193 Try to format error messages so that they fit on lines of about @var{n}
2194 characters.  The default is 72 characters for @command{g++} and 0 for the rest of
2195 the front ends supported by GCC@.  If @var{n} is zero, then no
2196 line-wrapping will be done; each error message will appear on a single
2197 line.
2198
2199 @opindex fdiagnostics-show-location
2200 @item -fdiagnostics-show-location=once
2201 Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
2202 reporter to emit @emph{once} source location information; that is, in
2203 case the message is too long to fit on a single physical line and has to
2204 be wrapped, the source location won't be emitted (as prefix) again,
2205 over and over, in subsequent continuation lines.  This is the default
2206 behavior.
2207
2208 @item -fdiagnostics-show-location=every-line
2209 Only meaningful in line-wrapping mode.  Instructs the diagnostic
2210 messages reporter to emit the same source location information (as
2211 prefix) for physical lines that result from the process of breaking
2212 a message which is too long to fit on a single line.
2213
2214 @item -fdiagnostics-show-options
2215 @opindex fdiagnostics-show-options
2216 This option instructs the diagnostic machinery to add text to each
2217 diagnostic emitted, which indicates which command line option directly
2218 controls that diagnostic, when such an option is known to the
2219 diagnostic machinery.
2220
2221 @end table
2222
2223 @node Warning Options
2224 @section Options to Request or Suppress Warnings
2225 @cindex options to control warnings
2226 @cindex warning messages
2227 @cindex messages, warning
2228 @cindex suppressing warnings
2229
2230 Warnings are diagnostic messages that report constructions which
2231 are not inherently erroneous but which are risky or suggest there
2232 may have been an error.
2233
2234 You can request many specific warnings with options beginning @samp{-W},
2235 for example @option{-Wimplicit} to request warnings on implicit
2236 declarations.  Each of these specific warning options also has a
2237 negative form beginning @samp{-Wno-} to turn off warnings;
2238 for example, @option{-Wno-implicit}.  This manual lists only one of the
2239 two forms, whichever is not the default.
2240
2241 The following options control the amount and kinds of warnings produced
2242 by GCC; for further, language-specific options also refer to
2243 @ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect
2244 Options}.
2245
2246 @table @gcctabopt
2247 @cindex syntax checking
2248 @item -fsyntax-only
2249 @opindex fsyntax-only
2250 Check the code for syntax errors, but don't do anything beyond that.
2251
2252 @item -pedantic
2253 @opindex pedantic
2254 Issue all the warnings demanded by strict ISO C and ISO C++;
2255 reject all programs that use forbidden extensions, and some other
2256 programs that do not follow ISO C and ISO C++.  For ISO C, follows the
2257 version of the ISO C standard specified by any @option{-std} option used.
2258
2259 Valid ISO C and ISO C++ programs should compile properly with or without
2260 this option (though a rare few will require @option{-ansi} or a
2261 @option{-std} option specifying the required version of ISO C)@.  However,
2262 without this option, certain GNU extensions and traditional C and C++
2263 features are supported as well.  With this option, they are rejected.
2264
2265 @option{-pedantic} does not cause warning messages for use of the
2266 alternate keywords whose names begin and end with @samp{__}.  Pedantic
2267 warnings are also disabled in the expression that follows
2268 @code{__extension__}.  However, only system header files should use
2269 these escape routes; application programs should avoid them.
2270 @xref{Alternate Keywords}.
2271
2272 Some users try to use @option{-pedantic} to check programs for strict ISO
2273 C conformance.  They soon find that it does not do quite what they want:
2274 it finds some non-ISO practices, but not all---only those for which
2275 ISO C @emph{requires} a diagnostic, and some others for which
2276 diagnostics have been added.
2277
2278 A feature to report any failure to conform to ISO C might be useful in
2279 some instances, but would require considerable additional work and would
2280 be quite different from @option{-pedantic}.  We don't have plans to
2281 support such a feature in the near future.
2282
2283 Where the standard specified with @option{-std} represents a GNU
2284 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2285 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2286 extended dialect is based.  Warnings from @option{-pedantic} are given
2287 where they are required by the base standard.  (It would not make sense
2288 for such warnings to be given only for features not in the specified GNU
2289 C dialect, since by definition the GNU dialects of C include all
2290 features the compiler supports with the given option, and there would be
2291 nothing to warn about.)
2292
2293 @item -pedantic-errors
2294 @opindex pedantic-errors
2295 Like @option{-pedantic}, except that errors are produced rather than
2296 warnings.
2297
2298 @item -w
2299 @opindex w
2300 Inhibit all warning messages.
2301
2302 @item -Wno-import
2303 @opindex Wno-import
2304 Inhibit warning messages about the use of @samp{#import}.
2305
2306 @item -Wchar-subscripts
2307 @opindex Wchar-subscripts
2308 Warn if an array subscript has type @code{char}.  This is a common cause
2309 of error, as programmers often forget that this type is signed on some
2310 machines.
2311 This warning is enabled by @option{-Wall}.
2312
2313 @item -Wcomment
2314 @opindex Wcomment
2315 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2316 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2317 This warning is enabled by @option{-Wall}.
2318
2319 @item -Wfatal-errors
2320 @opindex Wfatal-errors
2321 This option causes the compiler to abort compilation on the first error
2322 occurred rather than trying to keep going and printing further error
2323 messages.
2324
2325 @item -Wformat
2326 @opindex Wformat
2327 @opindex ffreestanding
2328 @opindex fno-builtin
2329 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2330 the arguments supplied have types appropriate to the format string
2331 specified, and that the conversions specified in the format string make
2332 sense.  This includes standard functions, and others specified by format
2333 attributes (@pxref{Function Attributes}), in the @code{printf},
2334 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2335 not in the C standard) families (or other target-specific families).
2336 Which functions are checked without format attributes having been
2337 specified depends on the standard version selected, and such checks of
2338 functions without the attribute specified are disabled by
2339 @option{-ffreestanding} or @option{-fno-builtin}.
2340
2341 The formats are checked against the format features supported by GNU
2342 libc version 2.2.  These include all ISO C90 and C99 features, as well
2343 as features from the Single Unix Specification and some BSD and GNU
2344 extensions.  Other library implementations may not support all these
2345 features; GCC does not support warning about features that go beyond a
2346 particular library's limitations.  However, if @option{-pedantic} is used
2347 with @option{-Wformat}, warnings will be given about format features not
2348 in the selected standard version (but not for @code{strfmon} formats,
2349 since those are not in any version of the C standard).  @xref{C Dialect
2350 Options,,Options Controlling C Dialect}.
2351
2352 Since @option{-Wformat} also checks for null format arguments for
2353 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2354
2355 @option{-Wformat} is included in @option{-Wall}.  For more control over some
2356 aspects of format checking, the options @option{-Wformat-y2k},
2357 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2358 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2359 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
2360
2361 @item -Wformat-y2k
2362 @opindex Wformat-y2k
2363 If @option{-Wformat} is specified, also warn about @code{strftime}
2364 formats which may yield only a two-digit year.
2365
2366 @item -Wno-format-extra-args
2367 @opindex Wno-format-extra-args
2368 If @option{-Wformat} is specified, do not warn about excess arguments to a
2369 @code{printf} or @code{scanf} format function.  The C standard specifies
2370 that such arguments are ignored.
2371
2372 Where the unused arguments lie between used arguments that are
2373 specified with @samp{$} operand number specifications, normally
2374 warnings are still given, since the implementation could not know what
2375 type to pass to @code{va_arg} to skip the unused arguments.  However,
2376 in the case of @code{scanf} formats, this option will suppress the
2377 warning if the unused arguments are all pointers, since the Single
2378 Unix Specification says that such unused arguments are allowed.
2379
2380 @item -Wno-format-zero-length
2381 @opindex Wno-format-zero-length
2382 If @option{-Wformat} is specified, do not warn about zero-length formats.
2383 The C standard specifies that zero-length formats are allowed.
2384
2385 @item -Wformat-nonliteral
2386 @opindex Wformat-nonliteral
2387 If @option{-Wformat} is specified, also warn if the format string is not a
2388 string literal and so cannot be checked, unless the format function
2389 takes its format arguments as a @code{va_list}.
2390
2391 @item -Wformat-security
2392 @opindex Wformat-security
2393 If @option{-Wformat} is specified, also warn about uses of format
2394 functions that represent possible security problems.  At present, this
2395 warns about calls to @code{printf} and @code{scanf} functions where the
2396 format string is not a string literal and there are no format arguments,
2397 as in @code{printf (foo);}.  This may be a security hole if the format
2398 string came from untrusted input and contains @samp{%n}.  (This is
2399 currently a subset of what @option{-Wformat-nonliteral} warns about, but
2400 in future warnings may be added to @option{-Wformat-security} that are not
2401 included in @option{-Wformat-nonliteral}.)
2402
2403 @item -Wformat=2
2404 @opindex Wformat=2
2405 Enable @option{-Wformat} plus format checks not included in
2406 @option{-Wformat}.  Currently equivalent to @samp{-Wformat
2407 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2408
2409 @item -Wnonnull
2410 @opindex Wnonnull
2411 Warn about passing a null pointer for arguments marked as
2412 requiring a non-null value by the @code{nonnull} function attribute.
2413
2414 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}.  It
2415 can be disabled with the @option{-Wno-nonnull} option.
2416
2417 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2418 @opindex Winit-self
2419 Warn about uninitialized variables which are initialized with themselves.
2420 Note this option can only be used with the @option{-Wuninitialized} option,
2421 which in turn only works with @option{-O1} and above.
2422
2423 For example, GCC will warn about @code{i} being uninitialized in the
2424 following snippet only when @option{-Winit-self} has been specified:
2425 @smallexample
2426 @group
2427 int f()
2428 @{
2429   int i = i;
2430   return i;
2431 @}
2432 @end group
2433 @end smallexample
2434
2435 @item -Wimplicit-int
2436 @opindex Wimplicit-int
2437 Warn when a declaration does not specify a type.
2438 This warning is enabled by @option{-Wall}.
2439
2440 @item -Wimplicit-function-declaration
2441 @itemx -Werror-implicit-function-declaration
2442 @opindex Wimplicit-function-declaration
2443 @opindex Werror-implicit-function-declaration
2444 Give a warning (or error) whenever a function is used before being
2445 declared.  The form @option{-Wno-error-implicit-function-declaration}
2446 is not supported.
2447 This warning is enabled by @option{-Wall} (as a warning, not an error).
2448
2449 @item -Wimplicit
2450 @opindex Wimplicit
2451 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2452 This warning is enabled by @option{-Wall}.
2453
2454 @item -Wmain
2455 @opindex Wmain
2456 Warn if the type of @samp{main} is suspicious.  @samp{main} should be a
2457 function with external linkage, returning int, taking either zero
2458 arguments, two, or three arguments of appropriate types.
2459 This warning is enabled by @option{-Wall}.
2460
2461 @item -Wmissing-braces
2462 @opindex Wmissing-braces
2463 Warn if an aggregate or union initializer is not fully bracketed.  In
2464 the following example, the initializer for @samp{a} is not fully
2465 bracketed, but that for @samp{b} is fully bracketed.
2466
2467 @smallexample
2468 int a[2][2] = @{ 0, 1, 2, 3 @};
2469 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2470 @end smallexample
2471
2472 This warning is enabled by @option{-Wall}.
2473
2474 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2475 @opindex Wmissing-include-dirs
2476 Warn if a user-supplied include directory does not exist.
2477
2478 @item -Wparentheses
2479 @opindex Wparentheses
2480 Warn if parentheses are omitted in certain contexts, such
2481 as when there is an assignment in a context where a truth value
2482 is expected, or when operators are nested whose precedence people
2483 often get confused about.  Only the warning for an assignment used as
2484 a truth value is supported when compiling C++; the other warnings are
2485 only supported when compiling C@.
2486
2487 Also warn if a comparison like @samp{x<=y<=z} appears; this is
2488 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2489 interpretation from that of ordinary mathematical notation.
2490
2491 Also warn about constructions where there may be confusion to which
2492 @code{if} statement an @code{else} branch belongs.  Here is an example of
2493 such a case:
2494
2495 @smallexample
2496 @group
2497 @{
2498   if (a)
2499     if (b)
2500       foo ();
2501   else
2502     bar ();
2503 @}
2504 @end group
2505 @end smallexample
2506
2507 In C, every @code{else} branch belongs to the innermost possible @code{if}
2508 statement, which in this example is @code{if (b)}.  This is often not
2509 what the programmer expected, as illustrated in the above example by
2510 indentation the programmer chose.  When there is the potential for this
2511 confusion, GCC will issue a warning when this flag is specified.
2512 To eliminate the warning, add explicit braces around the innermost
2513 @code{if} statement so there is no way the @code{else} could belong to
2514 the enclosing @code{if}.  The resulting code would look like this:
2515
2516 @smallexample
2517 @group
2518 @{
2519   if (a)
2520     @{
2521       if (b)
2522         foo ();
2523       else
2524         bar ();
2525     @}
2526 @}
2527 @end group
2528 @end smallexample
2529
2530 This warning is enabled by @option{-Wall}.
2531
2532 @item -Wsequence-point
2533 @opindex Wsequence-point
2534 Warn about code that may have undefined semantics because of violations
2535 of sequence point rules in the C and C++ standards.
2536
2537 The C and C++ standards defines the order in which expressions in a C/C++
2538 program are evaluated in terms of @dfn{sequence points}, which represent
2539 a partial ordering between the execution of parts of the program: those
2540 executed before the sequence point, and those executed after it.  These
2541 occur after the evaluation of a full expression (one which is not part
2542 of a larger expression), after the evaluation of the first operand of a
2543 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2544 function is called (but after the evaluation of its arguments and the
2545 expression denoting the called function), and in certain other places.
2546 Other than as expressed by the sequence point rules, the order of
2547 evaluation of subexpressions of an expression is not specified.  All
2548 these rules describe only a partial order rather than a total order,
2549 since, for example, if two functions are called within one expression
2550 with no sequence point between them, the order in which the functions
2551 are called is not specified.  However, the standards committee have
2552 ruled that function calls do not overlap.
2553
2554 It is not specified when between sequence points modifications to the
2555 values of objects take effect.  Programs whose behavior depends on this
2556 have undefined behavior; the C and C++ standards specify that ``Between
2557 the previous and next sequence point an object shall have its stored
2558 value modified at most once by the evaluation of an expression.  
2559 Furthermore, the prior value shall be read only to determine the value
2560 to be stored.''.  If a program breaks these rules, the results on any
2561 particular implementation are entirely unpredictable.
2562
2563 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2564 = b[n++]} and @code{a[i++] = i;}.  Some more complicated cases are not
2565 diagnosed by this option, and it may give an occasional false positive
2566 result, but in general it has been found fairly effective at detecting
2567 this sort of problem in programs.
2568
2569 The standard is worded confusingly, therefore there is some debate
2570 over the precise meaning of the sequence point rules in subtle cases.
2571 Links to discussions of the problem, including proposed formal
2572 definitions, may be found on the GCC readings page, at
2573 @w{@uref{http://gcc.gnu.org/readings.html}}.
2574
2575 This warning is enabled by @option{-Wall} for C and C++.
2576
2577 @item -Wreturn-type
2578 @opindex Wreturn-type
2579 Warn whenever a function is defined with a return-type that defaults to
2580 @code{int}.  Also warn about any @code{return} statement with no
2581 return-value in a function whose return-type is not @code{void}.
2582
2583 For C, also warn if the return type of a function has a type qualifier
2584 such as @code{const}.  Such a type qualifier has no effect, since the
2585 value returned by a function is not an lvalue.  ISO C prohibits
2586 qualified @code{void} return types on function definitions, so such
2587 return types always receive a warning even without this option.
2588
2589 For C++, a function without return type always produces a diagnostic
2590 message, even when @option{-Wno-return-type} is specified.  The only
2591 exceptions are @samp{main} and functions defined in system headers.
2592
2593 This warning is enabled by @option{-Wall}.
2594
2595 @item -Wswitch
2596 @opindex Wswitch
2597 Warn whenever a @code{switch} statement has an index of enumerated type
2598 and lacks a @code{case} for one or more of the named codes of that
2599 enumeration.  (The presence of a @code{default} label prevents this
2600 warning.)  @code{case} labels outside the enumeration range also
2601 provoke warnings when this option is used.
2602 This warning is enabled by @option{-Wall}.
2603
2604 @item -Wswitch-default
2605 @opindex Wswitch-switch
2606 Warn whenever a @code{switch} statement does not have a @code{default}
2607 case.
2608
2609 @item -Wswitch-enum
2610 @opindex Wswitch-enum
2611 Warn whenever a @code{switch} statement has an index of enumerated type
2612 and lacks a @code{case} for one or more of the named codes of that
2613 enumeration.  @code{case} labels outside the enumeration range also
2614 provoke warnings when this option is used.
2615
2616 @item -Wtrigraphs
2617 @opindex Wtrigraphs
2618 Warn if any trigraphs are encountered that might change the meaning of
2619 the program (trigraphs within comments are not warned about).
2620 This warning is enabled by @option{-Wall}.
2621
2622 @item -Wunused-function
2623 @opindex Wunused-function
2624 Warn whenever a static function is declared but not defined or a
2625 non-inline static function is unused.
2626 This warning is enabled by @option{-Wall}.
2627
2628 @item -Wunused-label
2629 @opindex Wunused-label
2630 Warn whenever a label is declared but not used.
2631 This warning is enabled by @option{-Wall}.
2632
2633 To suppress this warning use the @samp{unused} attribute
2634 (@pxref{Variable Attributes}).
2635
2636 @item -Wunused-parameter
2637 @opindex Wunused-parameter
2638 Warn whenever a function parameter is unused aside from its declaration.
2639
2640 To suppress this warning use the @samp{unused} attribute
2641 (@pxref{Variable Attributes}).
2642
2643 @item -Wunused-variable
2644 @opindex Wunused-variable
2645 Warn whenever a local variable or non-constant static variable is unused
2646 aside from its declaration
2647 This warning is enabled by @option{-Wall}.
2648
2649 To suppress this warning use the @samp{unused} attribute
2650 (@pxref{Variable Attributes}).
2651
2652 @item -Wunused-value
2653 @opindex Wunused-value
2654 Warn whenever a statement computes a result that is explicitly not used.
2655 This warning is enabled by @option{-Wall}.
2656
2657 To suppress this warning cast the expression to @samp{void}.
2658
2659 @item -Wunused
2660 @opindex Wunused
2661 All the above @option{-Wunused} options combined.
2662
2663 In order to get a warning about an unused function parameter, you must
2664 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2665 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2666
2667 @item -Wuninitialized
2668 @opindex Wuninitialized
2669 Warn if an automatic variable is used without first being initialized or
2670 if a variable may be clobbered by a @code{setjmp} call.
2671
2672 These warnings are possible only in optimizing compilation,
2673 because they require data flow information that is computed only
2674 when optimizing.  If you don't specify @option{-O}, you simply won't
2675 get these warnings.
2676
2677 If you want to warn about code which uses the uninitialized value of the
2678 variable in its own initializer, use the @option{-Winit-self} option.
2679
2680 These warnings occur for individual uninitialized or clobbered
2681 elements of structure, union or array variables as well as for
2682 variables which are uninitialized or clobbered as a whole.  They do
2683 not occur for variables or elements declared @code{volatile}.  Because
2684 these warnings depend on optimization, the exact variables or elements
2685 for which there are warnings will depend on the precise optimization
2686 options and version of GCC used.
2687
2688 Note that there may be no warning about a variable that is used only
2689 to compute a value that itself is never used, because such
2690 computations may be deleted by data flow analysis before the warnings
2691 are printed.
2692
2693 These warnings are made optional because GCC is not smart
2694 enough to see all the reasons why the code might be correct
2695 despite appearing to have an error.  Here is one example of how
2696 this can happen:
2697
2698 @smallexample
2699 @group
2700 @{
2701   int x;
2702   switch (y)
2703     @{
2704     case 1: x = 1;
2705       break;
2706     case 2: x = 4;
2707       break;
2708     case 3: x = 5;
2709     @}
2710   foo (x);
2711 @}
2712 @end group
2713 @end smallexample
2714
2715 @noindent
2716 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2717 always initialized, but GCC doesn't know this.  Here is
2718 another common case:
2719
2720 @smallexample
2721 @{
2722   int save_y;
2723   if (change_y) save_y = y, y = new_y;
2724   @dots{}
2725   if (change_y) y = save_y;
2726 @}
2727 @end smallexample
2728
2729 @noindent
2730 This has no bug because @code{save_y} is used only if it is set.
2731
2732 @cindex @code{longjmp} warnings
2733 This option also warns when a non-volatile automatic variable might be
2734 changed by a call to @code{longjmp}.  These warnings as well are possible
2735 only in optimizing compilation.
2736
2737 The compiler sees only the calls to @code{setjmp}.  It cannot know
2738 where @code{longjmp} will be called; in fact, a signal handler could
2739 call it at any point in the code.  As a result, you may get a warning
2740 even when there is in fact no problem because @code{longjmp} cannot
2741 in fact be called at the place which would cause a problem.
2742
2743 Some spurious warnings can be avoided if you declare all the functions
2744 you use that never return as @code{noreturn}.  @xref{Function
2745 Attributes}.
2746
2747 This warning is enabled by @option{-Wall}.
2748
2749 @item -Wunknown-pragmas
2750 @opindex Wunknown-pragmas
2751 @cindex warning for unknown pragmas
2752 @cindex unknown pragmas, warning
2753 @cindex pragmas, warning of unknown
2754 Warn when a #pragma directive is encountered which is not understood by
2755 GCC@.  If this command line option is used, warnings will even be issued
2756 for unknown pragmas in system header files.  This is not the case if
2757 the warnings were only enabled by the @option{-Wall} command line option.
2758
2759 @item -Wno-pragmas
2760 @opindex Wno-pragmas
2761 @opindex Wpragmas
2762 Do not warn about misuses of pragmas, such as incorrect parameters,
2763 invalid syntax, or conflicts between pragmas.  See also
2764 @samp{-Wunknown-pragmas}.
2765
2766 @item -Wstrict-aliasing
2767 @opindex Wstrict-aliasing
2768 This option is only active when @option{-fstrict-aliasing} is active.
2769 It warns about code which might break the strict aliasing rules that the
2770 compiler is using for optimization.  The warning does not catch all
2771 cases, but does attempt to catch the more common pitfalls.  It is
2772 included in @option{-Wall}.
2773
2774 @item -Wstrict-aliasing=2
2775 @opindex Wstrict-aliasing=2
2776 This option is only active when @option{-fstrict-aliasing} is active.
2777 It warns about code which might break the strict aliasing rules that the
2778 compiler is using for optimization.  This warning catches more cases than
2779 @option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2780 cases that are safe.
2781
2782 @item -Wall
2783 @opindex Wall
2784 All of the above @samp{-W} options combined.  This enables all the
2785 warnings about constructions that some users consider questionable, and
2786 that are easy to avoid (or modify to prevent the warning), even in
2787 conjunction with macros.  This also enables some language-specific
2788 warnings described in @ref{C++ Dialect Options} and
2789 @ref{Objective-C and Objective-C++ Dialect Options}.
2790 @end table
2791
2792 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2793 Some of them warn about constructions that users generally do not
2794 consider questionable, but which occasionally you might wish to check
2795 for; others warn about constructions that are necessary or hard to avoid
2796 in some cases, and there is no simple way to modify the code to suppress
2797 the warning.
2798
2799 @table @gcctabopt
2800 @item -Wextra
2801 @opindex W
2802 @opindex Wextra
2803 (This option used to be called @option{-W}.  The older name is still
2804 supported, but the newer name is more descriptive.)  Print extra warning
2805 messages for these events:
2806
2807 @itemize @bullet
2808 @item
2809 A function can return either with or without a value.  (Falling
2810 off the end of the function body is considered returning without
2811 a value.)  For example, this function would evoke such a
2812 warning:
2813
2814 @smallexample
2815 @group
2816 foo (a)
2817 @{
2818   if (a > 0)
2819     return a;
2820 @}
2821 @end group
2822 @end smallexample
2823
2824 @item
2825 An expression-statement or the left-hand side of a comma expression
2826 contains no side effects.
2827 To suppress the warning, cast the unused expression to void.
2828 For example, an expression such as @samp{x[i,j]} will cause a warning,
2829 but @samp{x[(void)i,j]} will not.
2830
2831 @item
2832 An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2833
2834 @item
2835 Storage-class specifiers like @code{static} are not the first things in
2836 a declaration.  According to the C Standard, this usage is obsolescent.
2837
2838 @item
2839 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2840 arguments.
2841
2842 @item
2843 A comparison between signed and unsigned values could produce an
2844 incorrect result when the signed value is converted to unsigned.
2845 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2846
2847 @item
2848 An aggregate has an initializer which does not initialize all members.
2849 This warning can be independently controlled by
2850 @option{-Wmissing-field-initializers}.
2851
2852 @item
2853 A function parameter is declared without a type specifier in K&R-style
2854 functions:
2855
2856 @smallexample
2857 void foo(bar) @{ @}
2858 @end smallexample
2859
2860 @item
2861 An empty body occurs in an @samp{if} or @samp{else} statement.
2862
2863 @item
2864 A pointer is compared against integer zero with @samp{<}, @samp{<=},
2865 @samp{>}, or @samp{>=}.
2866
2867 @item
2868 A variable might be changed by @samp{longjmp} or @samp{vfork}.
2869
2870 @item
2871 Any of several floating-point events that often indicate errors, such as
2872 overflow, underflow, loss of precision, etc.
2873
2874 @item @r{(C++ only)}
2875 An enumerator and a non-enumerator both appear in a conditional expression.
2876
2877 @item @r{(C++ only)}
2878 A non-static reference or non-static @samp{const} member appears in a
2879 class without constructors.
2880
2881 @item @r{(C++ only)}
2882 Ambiguous virtual bases.
2883
2884 @item @r{(C++ only)}
2885 Subscripting an array which has been declared @samp{register}.
2886
2887 @item @r{(C++ only)}
2888 Taking the address of a variable which has been declared @samp{register}.
2889
2890 @item @r{(C++ only)}
2891 A base class is not initialized in a derived class' copy constructor.
2892 @end itemize
2893
2894 @item -Wno-div-by-zero
2895 @opindex Wno-div-by-zero
2896 @opindex Wdiv-by-zero
2897 Do not warn about compile-time integer division by zero.  Floating point
2898 division by zero is not warned about, as it can be a legitimate way of
2899 obtaining infinities and NaNs.
2900
2901 @item -Wsystem-headers
2902 @opindex Wsystem-headers
2903 @cindex warnings from system headers
2904 @cindex system headers, warnings from
2905 Print warning messages for constructs found in system header files.
2906 Warnings from system headers are normally suppressed, on the assumption
2907 that they usually do not indicate real problems and would only make the
2908 compiler output harder to read.  Using this command line option tells
2909 GCC to emit warnings from system headers as if they occurred in user
2910 code.  However, note that using @option{-Wall} in conjunction with this
2911 option will @emph{not} warn about unknown pragmas in system
2912 headers---for that, @option{-Wunknown-pragmas} must also be used.
2913
2914 @item -Wfloat-equal
2915 @opindex Wfloat-equal
2916 Warn if floating point values are used in equality comparisons.
2917
2918 The idea behind this is that sometimes it is convenient (for the
2919 programmer) to consider floating-point values as approximations to
2920 infinitely precise real numbers.  If you are doing this, then you need
2921 to compute (by analyzing the code, or in some other way) the maximum or
2922 likely maximum error that the computation introduces, and allow for it
2923 when performing comparisons (and when producing output, but that's a
2924 different problem).  In particular, instead of testing for equality, you
2925 would check to see whether the two values have ranges that overlap; and
2926 this is done with the relational operators, so equality comparisons are
2927 probably mistaken.
2928
2929 @item -Wtraditional @r{(C only)}
2930 @opindex Wtraditional
2931 Warn about certain constructs that behave differently in traditional and
2932 ISO C@.  Also warn about ISO C constructs that have no traditional C
2933 equivalent, and/or problematic constructs which should be avoided.
2934
2935 @itemize @bullet
2936 @item
2937 Macro parameters that appear within string literals in the macro body.
2938 In traditional C macro replacement takes place within string literals,
2939 but does not in ISO C@.
2940
2941 @item
2942 In traditional C, some preprocessor directives did not exist.
2943 Traditional preprocessors would only consider a line to be a directive
2944 if the @samp{#} appeared in column 1 on the line.  Therefore
2945 @option{-Wtraditional} warns about directives that traditional C
2946 understands but would ignore because the @samp{#} does not appear as the
2947 first character on the line.  It also suggests you hide directives like
2948 @samp{#pragma} not understood by traditional C by indenting them.  Some
2949 traditional implementations would not recognize @samp{#elif}, so it
2950 suggests avoiding it altogether.
2951
2952 @item
2953 A function-like macro that appears without arguments.
2954
2955 @item
2956 The unary plus operator.
2957
2958 @item
2959 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2960 constant suffixes.  (Traditional C does support the @samp{L} suffix on integer
2961 constants.)  Note, these suffixes appear in macros defined in the system
2962 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2963 Use of these macros in user code might normally lead to spurious
2964 warnings, however GCC's integrated preprocessor has enough context to
2965 avoid warning in these cases.
2966
2967 @item
2968 A function declared external in one block and then used after the end of
2969 the block.
2970
2971 @item
2972 A @code{switch} statement has an operand of type @code{long}.
2973
2974 @item
2975 A non-@code{static} function declaration follows a @code{static} one.
2976 This construct is not accepted by some traditional C compilers.
2977
2978 @item
2979 The ISO type of an integer constant has a different width or
2980 signedness from its traditional type.  This warning is only issued if
2981 the base of the constant is ten.  I.e.@: hexadecimal or octal values, which
2982 typically represent bit patterns, are not warned about.
2983
2984 @item
2985 Usage of ISO string concatenation is detected.
2986
2987 @item
2988 Initialization of automatic aggregates.
2989
2990 @item
2991 Identifier conflicts with labels.  Traditional C lacks a separate
2992 namespace for labels.
2993
2994 @item
2995 Initialization of unions.  If the initializer is zero, the warning is
2996 omitted.  This is done under the assumption that the zero initializer in
2997 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2998 initializer warnings and relies on default initialization to zero in the
2999 traditional C case.
3000
3001 @item
3002 Conversions by prototypes between fixed/floating point values and vice
3003 versa.  The absence of these prototypes when compiling with traditional
3004 C would cause serious problems.  This is a subset of the possible
3005 conversion warnings, for the full set use @option{-Wconversion}.
3006
3007 @item
3008 Use of ISO C style function definitions.  This warning intentionally is
3009 @emph{not} issued for prototype declarations or variadic functions
3010 because these ISO C features will appear in your code when using
3011 libiberty's traditional C compatibility macros, @code{PARAMS} and
3012 @code{VPARAMS}.  This warning is also bypassed for nested functions
3013 because that feature is already a GCC extension and thus not relevant to
3014 traditional C compatibility.
3015 @end itemize
3016
3017 @item -Wdeclaration-after-statement @r{(C only)}
3018 @opindex Wdeclaration-after-statement
3019 Warn when a declaration is found after a statement in a block.  This
3020 construct, known from C++, was introduced with ISO C99 and is by default
3021 allowed in GCC@.  It is not supported by ISO C90 and was not supported by
3022 GCC versions before GCC 3.0.  @xref{Mixed Declarations}.
3023
3024 @item -Wundef
3025 @opindex Wundef
3026 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3027
3028 @item -Wno-endif-labels
3029 @opindex Wno-endif-labels
3030 @opindex Wendif-labels
3031 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3032
3033 @item -Wshadow
3034 @opindex Wshadow
3035 Warn whenever a local variable shadows another local variable, parameter or
3036 global variable or whenever a built-in function is shadowed.
3037
3038 @item -Wlarger-than-@var{len}
3039 @opindex Wlarger-than
3040 Warn whenever an object of larger than @var{len} bytes is defined.
3041
3042 @item -Wunsafe-loop-optimizations
3043 @opindex Wunsafe-loop-optimizations
3044 Warn if the loop cannot be optimized because the compiler could not
3045 assume anything on the bounds of the loop indices.  With
3046 @option{-funsafe-loop-optimizations} warn if the compiler made
3047 such assumptions.
3048
3049 @item -Wpointer-arith
3050 @opindex Wpointer-arith
3051 Warn about anything that depends on the ``size of'' a function type or
3052 of @code{void}.  GNU C assigns these types a size of 1, for
3053 convenience in calculations with @code{void *} pointers and pointers
3054 to functions.
3055
3056 @item -Wbad-function-cast @r{(C only)}
3057 @opindex Wbad-function-cast
3058 Warn whenever a function call is cast to a non-matching type.
3059 For example, warn if @code{int malloc()} is cast to @code{anything *}.
3060
3061 @item -Wc++-compat
3062 Warn about ISO C constructs that are outside of the common subset of
3063 ISO C and ISO C++, e.g.@: request for implicit conversion from
3064 @code{void *} to a pointer to non-@code{void} type.
3065
3066 @item -Wcast-qual
3067 @opindex Wcast-qual
3068 Warn whenever a pointer is cast so as to remove a type qualifier from
3069 the target type.  For example, warn if a @code{const char *} is cast
3070 to an ordinary @code{char *}.
3071
3072 @item -Wcast-align
3073 @opindex Wcast-align
3074 Warn whenever a pointer is cast such that the required alignment of the
3075 target is increased.  For example, warn if a @code{char *} is cast to
3076 an @code{int *} on machines where integers can only be accessed at
3077 two- or four-byte boundaries.
3078
3079 @item -Wwrite-strings
3080 @opindex Wwrite-strings
3081 When compiling C, give string constants the type @code{const
3082 char[@var{length}]} so that
3083 copying the address of one into a non-@code{const} @code{char *}
3084 pointer will get a warning; when compiling C++, warn about the
3085 deprecated conversion from string literals to @code{char *}.  This
3086 warning, by default, is enabled for C++ programs.
3087 These warnings will help you find at
3088 compile time code that can try to write into a string constant, but
3089 only if you have been very careful about using @code{const} in
3090 declarations and prototypes.  Otherwise, it will just be a nuisance;
3091 this is why we did not make @option{-Wall} request these warnings.
3092
3093 @item -Wconversion
3094 @opindex Wconversion
3095 Warn if a prototype causes a type conversion that is different from what
3096 would happen to the same argument in the absence of a prototype.  This
3097 includes conversions of fixed point to floating and vice versa, and
3098 conversions changing the width or signedness of a fixed point argument
3099 except when the same as the default promotion.
3100
3101 Also, warn if a negative integer constant expression is implicitly
3102 converted to an unsigned type.  For example, warn about the assignment
3103 @code{x = -1} if @code{x} is unsigned.  But do not warn about explicit
3104 casts like @code{(unsigned) -1}.
3105
3106 @item -Wsign-compare
3107 @opindex Wsign-compare
3108 @cindex warning for comparison of signed and unsigned values
3109 @cindex comparison of signed and unsigned values, warning
3110 @cindex signed and unsigned values, comparison warning
3111 Warn when a comparison between signed and unsigned values could produce
3112 an incorrect result when the signed value is converted to unsigned.
3113 This warning is also enabled by @option{-Wextra}; to get the other warnings
3114 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3115
3116 @item -Waggregate-return
3117 @opindex Waggregate-return
3118 Warn if any functions that return structures or unions are defined or
3119 called.  (In languages where you can return an array, this also elicits
3120 a warning.)
3121
3122 @item -Walways-true
3123 @opindex Walways-true
3124 Warn about comparisons which are always true such as testing if
3125 unsigned values are greater than or equal to zero.  This warning is
3126 enabled by @option{-Wall}.
3127
3128 @item -Wno-attributes
3129 @opindex Wno-attributes
3130 @opindex Wattributes
3131 Do not warn if an unexpected @code{__attribute__} is used, such as
3132 unrecognized attributes, function attributes applied to variables,
3133 etc.  This will not stop errors for incorrect use of supported
3134 attributes.
3135
3136 @item -Wstrict-prototypes @r{(C only)}
3137 @opindex Wstrict-prototypes
3138 Warn if a function is declared or defined without specifying the
3139 argument types.  (An old-style function definition is permitted without
3140 a warning if preceded by a declaration which specifies the argument
3141 types.)
3142
3143 @item -Wold-style-definition @r{(C only)}
3144 @opindex Wold-style-definition
3145 Warn if an old-style function definition is used.  A warning is given
3146 even if there is a previous prototype.
3147
3148 @item -Wmissing-prototypes @r{(C only)}
3149 @opindex Wmissing-prototypes
3150 Warn if a global function is defined without a previous prototype
3151 declaration.  This warning is issued even if the definition itself
3152 provides a prototype.  The aim is to detect global functions that fail
3153 to be declared in header files.
3154
3155 @item -Wmissing-declarations @r{(C only)}
3156 @opindex Wmissing-declarations
3157 Warn if a global function is defined without a previous declaration.
3158 Do so even if the definition itself provides a prototype.
3159 Use this option to detect global functions that are not declared in
3160 header files.
3161
3162 @item -Wmissing-field-initializers
3163 @opindex Wmissing-field-initializers
3164 @opindex W
3165 @opindex Wextra
3166 Warn if a structure's initializer has some fields missing.  For
3167 example, the following code would cause such a warning, because
3168 @code{x.h} is implicitly zero:
3169
3170 @smallexample
3171 struct s @{ int f, g, h; @};
3172 struct s x = @{ 3, 4 @};
3173 @end smallexample
3174
3175 This option does not warn about designated initializers, so the following
3176 modification would not trigger a warning:
3177
3178 @smallexample
3179 struct s @{ int f, g, h; @};
3180 struct s x = @{ .f = 3, .g = 4 @};
3181 @end smallexample
3182
3183 This warning is included in @option{-Wextra}.  To get other @option{-Wextra}
3184 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3185
3186 @item -Wmissing-noreturn
3187 @opindex Wmissing-noreturn
3188 Warn about functions which might be candidates for attribute @code{noreturn}.
3189 Note these are only possible candidates, not absolute ones.  Care should
3190 be taken to manually verify functions actually do not ever return before
3191 adding the @code{noreturn} attribute, otherwise subtle code generation
3192 bugs could be introduced.  You will not get a warning for @code{main} in
3193 hosted C environments.
3194
3195 @item -Wmissing-format-attribute
3196 @opindex Wmissing-format-attribute
3197 @opindex Wformat
3198 Warn about function pointers which might be candidates for @code{format}
3199 attributes.  Note these are only possible candidates, not absolute ones.
3200 GCC will guess that function pointers with @code{format} attributes that
3201 are used in assignment, initialization, parameter passing or return
3202 statements should have a corresponding @code{format} attribute in the
3203 resulting type.  I.e.@: the left-hand side of the assignment or
3204 initialization, the type of the parameter variable, or the return type
3205 of the containing function respectively should also have a @code{format}
3206 attribute to avoid the warning.
3207
3208 GCC will also warn about function definitions which might be
3209 candidates for @code{format} attributes.  Again, these are only
3210 possible candidates.  GCC will guess that @code{format} attributes
3211 might be appropriate for any function that calls a function like
3212 @code{vprintf} or @code{vscanf}, but this might not always be the
3213 case, and some functions for which @code{format} attributes are
3214 appropriate may not be detected.
3215
3216 @item -Wno-multichar
3217 @opindex Wno-multichar
3218 @opindex Wmultichar
3219 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3220 Usually they indicate a typo in the user's code, as they have
3221 implementation-defined values, and should not be used in portable code.
3222
3223 @item -Wnormalized=<none|id|nfc|nfkc>
3224 @opindex Wnormalized
3225 @cindex NFC
3226 @cindex NFKC
3227 @cindex character set, input normalization
3228 In ISO C and ISO C++, two identifiers are different if they are
3229 different sequences of characters.  However, sometimes when characters
3230 outside the basic ASCII character set are used, you can have two
3231 different character sequences that look the same.  To avoid confusion,
3232 the ISO 10646 standard sets out some @dfn{normalization rules} which
3233 when applied ensure that two sequences that look the same are turned into
3234 the same sequence.  GCC can warn you if you are using identifiers which
3235 have not been normalized; this option controls that warning.
3236
3237 There are four levels of warning that GCC supports.  The default is
3238 @option{-Wnormalized=nfc}, which warns about any identifier which is
3239 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}.  NFC is the
3240 recommended form for most uses.
3241
3242 Unfortunately, there are some characters which ISO C and ISO C++ allow
3243 in identifiers that when turned into NFC aren't allowable as
3244 identifiers.  That is, there's no way to use these symbols in portable
3245 ISO C or C++ and have all your identifiers in NFC.
3246 @option{-Wnormalized=id} suppresses the warning for these characters.
3247 It is hoped that future versions of the standards involved will correct
3248 this, which is why this option is not the default.
3249
3250 You can switch the warning off for all characters by writing
3251 @option{-Wnormalized=none}.  You would only want to do this if you
3252 were using some other normalization scheme (like ``D''), because
3253 otherwise you can easily create bugs that are literally impossible to see.
3254
3255 Some characters in ISO 10646 have distinct meanings but look identical
3256 in some fonts or display methodologies, especially once formatting has
3257 been applied.  For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3258 LETTER N'', will display just like a regular @code{n} which has been
3259 placed in a superscript.  ISO 10646 defines the @dfn{NFKC}
3260 normalisation scheme to convert all these into a standard form as
3261 well, and GCC will warn if your code is not in NFKC if you use
3262 @option{-Wnormalized=nfkc}.  This warning is comparable to warning
3263 about every identifier that contains the letter O because it might be
3264 confused with the digit 0, and so is not the default, but may be
3265 useful as a local coding convention if the programming environment is
3266 unable to be fixed to display these characters distinctly.
3267
3268 @item -Wno-deprecated-declarations
3269 @opindex Wno-deprecated-declarations
3270 Do not warn about uses of functions, variables, and types marked as
3271 deprecated by using the @code{deprecated} attribute.
3272 (@pxref{Function Attributes}, @pxref{Variable Attributes},
3273 @pxref{Type Attributes}.)
3274
3275 @item -Wpacked
3276 @opindex Wpacked
3277 Warn if a structure is given the packed attribute, but the packed
3278 attribute has no effect on the layout or size of the structure.
3279 Such structures may be mis-aligned for little benefit.  For
3280 instance, in this code, the variable @code{f.x} in @code{struct bar}
3281 will be misaligned even though @code{struct bar} does not itself
3282 have the packed attribute:
3283
3284 @smallexample
3285 @group
3286 struct foo @{
3287   int x;
3288   char a, b, c, d;
3289 @} __attribute__((packed));
3290 struct bar @{
3291   char z;
3292   struct foo f;
3293 @};
3294 @end group
3295 @end smallexample
3296
3297 @item -Wpadded
3298 @opindex Wpadded
3299 Warn if padding is included in a structure, either to align an element
3300 of the structure or to align the whole structure.  Sometimes when this
3301 happens it is possible to rearrange the fields of the structure to
3302 reduce the padding and so make the structure smaller.
3303
3304 @item -Wredundant-decls
3305 @opindex Wredundant-decls
3306 Warn if anything is declared more than once in the same scope, even in
3307 cases where multiple declaration is valid and changes nothing.
3308
3309 @item -Wnested-externs @r{(C only)}
3310 @opindex Wnested-externs
3311 Warn if an @code{extern} declaration is encountered within a function.
3312
3313 @item -Wunreachable-code
3314 @opindex Wunreachable-code
3315 Warn if the compiler detects that code will never be executed.
3316
3317 This option is intended to warn when the compiler detects that at
3318 least a whole line of source code will never be executed, because
3319 some condition is never satisfied or because it is after a
3320 procedure that never returns.
3321
3322 It is possible for this option to produce a warning even though there
3323 are circumstances under which part of the affected line can be executed,
3324 so care should be taken when removing apparently-unreachable code.
3325
3326 For instance, when a function is inlined, a warning may mean that the
3327 line is unreachable in only one inlined copy of the function.
3328
3329 This option is not made part of @option{-Wall} because in a debugging
3330 version of a program there is often substantial code which checks
3331 correct functioning of the program and is, hopefully, unreachable
3332 because the program does work.  Another common use of unreachable
3333 code is to provide behavior which is selectable at compile-time.
3334
3335 @item -Winline
3336 @opindex Winline
3337 Warn if a function can not be inlined and it was declared as inline.
3338 Even with this option, the compiler will not warn about failures to
3339 inline functions declared in system headers.
3340
3341 The compiler uses a variety of heuristics to determine whether or not
3342 to inline a function.  For example, the compiler takes into account
3343 the size of the function being inlined and the amount of inlining
3344 that has already been done in the current function.  Therefore,
3345 seemingly insignificant changes in the source program can cause the
3346 warnings produced by @option{-Winline} to appear or disappear.
3347
3348 @item -Wno-invalid-offsetof @r{(C++ only)}
3349 @opindex Wno-invalid-offsetof
3350 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3351 type.  According to the 1998 ISO C++ standard, applying @samp{offsetof}
3352 to a non-POD type is undefined.  In existing C++ implementations,
3353 however, @samp{offsetof} typically gives meaningful results even when
3354 applied to certain kinds of non-POD types. (Such as a simple
3355 @samp{struct} that fails to be a POD type only by virtue of having a
3356 constructor.)  This flag is for users who are aware that they are
3357 writing nonportable code and who have deliberately chosen to ignore the
3358 warning about it.
3359
3360 The restrictions on @samp{offsetof} may be relaxed in a future version
3361 of the C++ standard.
3362
3363 @item -Wno-int-to-pointer-cast @r{(C only)}
3364 @opindex Wno-int-to-pointer-cast
3365 Suppress warnings from casts to pointer type of an integer of a
3366 different size.
3367
3368 @item -Wno-pointer-to-int-cast @r{(C only)}
3369 @opindex Wno-pointer-to-int-cast
3370 Suppress warnings from casts from a pointer to an integer type of a
3371 different size.
3372
3373 @item -Winvalid-pch
3374 @opindex Winvalid-pch
3375 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3376 the search path but can't be used.
3377
3378 @item -Wlong-long
3379 @opindex Wlong-long
3380 @opindex Wno-long-long
3381 Warn if @samp{long long} type is used.  This is default.  To inhibit
3382 the warning messages, use @option{-Wno-long-long}.  Flags
3383 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3384 only when @option{-pedantic} flag is used.
3385
3386 @item -Wvariadic-macros
3387 @opindex Wvariadic-macros
3388 @opindex Wno-variadic-macros
3389 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3390 alternate syntax when in pedantic ISO C99 mode.  This is default.
3391 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3392
3393 @item -Wvolatile-register-var
3394 @opindex Wvolatile-register-var
3395 @opindex Wno-volatile-register-var
3396 Warn if a register variable is declared volatile.  The volatile
3397 modifier does not inhibit all optimizations that may eliminate reads
3398 and/or writes to register variables.
3399
3400 @item -Wdisabled-optimization
3401 @opindex Wdisabled-optimization
3402 Warn if a requested optimization pass is disabled.  This warning does
3403 not generally indicate that there is anything wrong with your code; it
3404 merely indicates that GCC's optimizers were unable to handle the code
3405 effectively.  Often, the problem is that your code is too big or too
3406 complex; GCC will refuse to optimize programs when the optimization
3407 itself is likely to take inordinate amounts of time.
3408
3409 @item -Wpointer-sign
3410 @opindex Wpointer-sign
3411 @opindex Wno-pointer-sign
3412 Warn for pointer argument passing or assignment with different signedness.
3413 This option is only supported for C and Objective-C@.  It is implied by
3414 @option{-Wall} and by @option{-pedantic}, which can be disabled with
3415 @option{-Wno-pointer-sign}.
3416
3417 @item -Werror
3418 @opindex Werror
3419 Make all warnings into errors.
3420
3421 @item -Werror=
3422 @opindex Werror=
3423 Make the specified warning into an errors.  The specifier for a
3424 warning is appended, for example @option{-Werror=switch} turns the
3425 warnings controlled by @option{-Wswitch} into errors.  This switch
3426 takes a negative form, to be used to negate @option{-Werror} for
3427 specific warnings, for example @option{-Wno-error=switch} makes
3428 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
3429 is in effect.  You can use the @option{-fdiagnostics-show-option}
3430 option to have each controllable warning amended with the option which
3431 controls it, to determine what to use with this option.
3432
3433 Note that specifying @option{-Werror=}@var{foo} automatically implies
3434 @option{-W}@var{foo}.  However, @option{-Wno-error=}@var{foo} does not
3435 imply anything.
3436
3437 @item -Wstack-protector
3438 @opindex Wstack-protector
3439 This option is only active when @option{-fstack-protector} is active.  It
3440 warns about functions that will not be protected against stack smashing.
3441
3442 @item -Wstring-literal-comparison
3443 @opindex Wstring-literal-comparison
3444 Warn about suspicious comparisons to string literal constants.  In C,
3445 direct comparisons against the memory address of a string literal, such
3446 as @code{if (x == "abc")}, typically indicate a programmer error, and
3447 even when intentional, result in unspecified behavior and are not portable.
3448 Usually these warnings alert that the programmer intended to use
3449 @code{strcmp}.  This warning is enabled by @option{-Wall}.
3450
3451 @item -Woverlength-strings
3452 @opindex Woverlength-strings
3453 Warn about string constants which are longer than the ``minimum
3454 maximum'' length specified in the C standard.  Modern compilers
3455 generally allow string constants which are much longer than the
3456 standard's minimum limit, but very portable programs should avoid
3457 using longer strings.
3458
3459 The limit applies @emph{after} string constant concatenation, and does
3460 not count the trailing NUL@.  In C89, the limit was 509 characters; in
3461 C99, it was raised to 4095.  C++98 does not specify a normative
3462 minimum maximum, so we do not diagnose overlength strings in C++@.
3463
3464 This option is implied by @option{-pedantic}, and can be disabled with
3465 @option{-Wno-overlength-strings}.
3466 @end table
3467
3468 @node Debugging Options
3469 @section Options for Debugging Your Program or GCC
3470 @cindex options, debugging
3471 @cindex debugging information options
3472
3473 GCC has various special options that are used for debugging
3474 either your program or GCC:
3475
3476 @table @gcctabopt
3477 @item -g
3478 @opindex g
3479 Produce debugging information in the operating system's native format
3480 (stabs, COFF, XCOFF, or DWARF 2)@.  GDB can work with this debugging
3481 information.
3482
3483 On most systems that use stabs format, @option{-g} enables use of extra
3484 debugging information that only GDB can use; this extra information
3485 makes debugging work better in GDB but will probably make other debuggers
3486 crash or
3487 refuse to read the program.  If you want to control for certain whether
3488 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3489 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3490
3491 GCC allows you to use @option{-g} with
3492 @option{-O}.  The shortcuts taken by optimized code may occasionally
3493 produce surprising results: some variables you declared may not exist
3494 at all; flow of control may briefly move where you did not expect it;
3495 some statements may not be executed because they compute constant
3496 results or their values were already at hand; some statements may
3497 execute in different places because they were moved out of loops.
3498
3499 Nevertheless it proves possible to debug optimized output.  This makes
3500 it reasonable to use the optimizer for programs that might have bugs.
3501
3502 The following options are useful when GCC is generated with the
3503 capability for more than one debugging format.
3504
3505 @item -ggdb
3506 @opindex ggdb
3507 Produce debugging information for use by GDB@.  This means to use the
3508 most expressive format available (DWARF 2, stabs, or the native format
3509 if neither of those are supported), including GDB extensions if at all
3510 possible.
3511
3512 @item -gstabs
3513 @opindex gstabs
3514 Produce debugging information in stabs format (if that is supported),
3515 without GDB extensions.  This is the format used by DBX on most BSD
3516 systems.  On MIPS, Alpha and System V Release 4 systems this option
3517 produces stabs debugging output which is not understood by DBX or SDB@.
3518 On System V Release 4 systems this option requires the GNU assembler.
3519
3520 @item -feliminate-unused-debug-symbols
3521 @opindex feliminate-unused-debug-symbols
3522 Produce debugging information in stabs format (if that is supported),
3523 for only symbols that are actually used.
3524
3525 @item -gstabs+
3526 @opindex gstabs+
3527 Produce debugging information in stabs format (if that is supported),
3528 using GNU extensions understood only by the GNU debugger (GDB)@.  The
3529 use of these extensions is likely to make other debuggers crash or
3530 refuse to read the program.
3531
3532 @item -gcoff
3533 @opindex gcoff
3534 Produce debugging information in COFF format (if that is supported).
3535 This is the format used by SDB on most System V systems prior to
3536 System V Release 4.
3537
3538 @item -gxcoff
3539 @opindex gxcoff
3540 Produce debugging information in XCOFF format (if that is supported).
3541 This is the format used by the DBX debugger on IBM RS/6000 systems.
3542
3543 @item -gxcoff+
3544 @opindex gxcoff+
3545 Produce debugging information in XCOFF format (if that is supported),
3546 using GNU extensions understood only by the GNU debugger (GDB)@.  The
3547 use of these extensions is likely to make other debuggers crash or
3548 refuse to read the program, and may cause assemblers other than the GNU
3549 assembler (GAS) to fail with an error.
3550
3551 @item -gdwarf-2
3552 @opindex gdwarf-2
3553 Produce debugging information in DWARF version 2 format (if that is
3554 supported).  This is the format used by DBX on IRIX 6.  With this
3555 option, GCC uses features of DWARF version 3 when they are useful;
3556 version 3 is upward compatible with version 2, but may still cause
3557 problems for older debuggers.
3558
3559 @item -gvms
3560 @opindex gvms
3561 Produce debugging information in VMS debug format (if that is
3562 supported).  This is the format used by DEBUG on VMS systems.
3563
3564 @item -g@var{level}
3565 @itemx -ggdb@var{level}
3566 @itemx -gstabs@var{level}
3567 @itemx -gcoff@var{level}
3568 @itemx -gxcoff@var{level}
3569 @itemx -gvms@var{level}
3570 Request debugging information and also use @var{level} to specify how
3571 much information.  The default level is 2.
3572
3573 Level 1 produces minimal information, enough for making backtraces in
3574 parts of the program that you don't plan to debug.  This includes
3575 descriptions of functions and external variables, but no information
3576 about local variables and no line numbers.
3577
3578 Level 3 includes extra information, such as all the macro definitions
3579 present in the program.  Some debuggers support macro expansion when
3580 you use @option{-g3}.
3581
3582 @option{-gdwarf-2} does not accept a concatenated debug level, because
3583 GCC used to support an option @option{-gdwarf} that meant to generate
3584 debug information in version 1 of the DWARF format (which is very
3585 different from version 2), and it would have been too confusing.  That
3586 debug format is long obsolete, but the option cannot be changed now.
3587 Instead use an additional @option{-g@var{level}} option to change the
3588 debug level for DWARF2.
3589
3590 @item -feliminate-dwarf2-dups
3591 @opindex feliminate-dwarf2-dups
3592 Compress DWARF2 debugging information by eliminating duplicated
3593 information about each symbol.  This option only makes sense when
3594 generating DWARF2 debugging information with @option{-gdwarf-2}.
3595
3596 @cindex @command{prof}
3597 @item -p
3598 @opindex p
3599 Generate extra code to write profile information suitable for the
3600 analysis program @command{prof}.  You must use this option when compiling
3601 the source files you want data about, and you must also use it when
3602 linking.
3603
3604 @cindex @command{gprof}
3605 @item -pg
3606 @opindex pg
3607 Generate extra code to write profile information suitable for the
3608 analysis program @command{gprof}.  You must use this option when compiling
3609 the source files you want data about, and you must also use it when
3610 linking.
3611
3612 @item -Q
3613 @opindex Q
3614 Makes the compiler print out each function name as it is compiled, and
3615 print some statistics about each pass when it finishes.
3616
3617 @item -ftime-report
3618 @opindex ftime-report
3619 Makes the compiler print some statistics about the time consumed by each
3620 pass when it finishes.
3621
3622 @item -fmem-report
3623 @opindex fmem-report
3624 Makes the compiler print some statistics about permanent memory
3625 allocation when it finishes.
3626
3627 @item -fprofile-arcs
3628 @opindex fprofile-arcs
3629 Add code so that program flow @dfn{arcs} are instrumented.  During
3630 execution the program records how many times each branch and call is
3631 executed and how many times it is taken or returns.  When the compiled
3632 program exits it saves this data to a file called
3633 @file{@var{auxname}.gcda} for each source file.  The data may be used for
3634 profile-directed optimizations (@option{-fbranch-probabilities}), or for
3635 test coverage analysis (@option{-ftest-coverage}).  Each object file's
3636 @var{auxname} is generated from the name of the output file, if
3637 explicitly specified and it is not the final executable, otherwise it is
3638 the basename of the source file.  In both cases any suffix is removed
3639 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3640 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3641 @xref{Cross-profiling}.
3642
3643 @cindex @command{gcov}
3644 @item --coverage
3645 @opindex coverage
3646
3647 This option is used to compile and link code instrumented for coverage
3648 analysis.  The option is a synonym for @option{-fprofile-arcs}
3649 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3650 linking).  See the documentation for those options for more details.
3651
3652 @itemize
3653
3654 @item
3655 Compile the source files with @option{-fprofile-arcs} plus optimization
3656 and code generation options.  For test coverage analysis, use the
3657 additional @option{-ftest-coverage} option.  You do not need to profile
3658 every source file in a program.
3659
3660 @item
3661 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3662 (the latter implies the former).
3663
3664 @item
3665 Run the program on a representative workload to generate the arc profile
3666 information.  This may be repeated any number of times.  You can run
3667 concurrent instances of your program, and provided that the file system
3668 supports locking, the data files will be correctly updated.  Also
3669 @code{fork} calls are detected and correctly handled (double counting
3670 will not happen).
3671
3672 @item
3673 For profile-directed optimizations, compile the source files again with
3674 the same optimization and code generation options plus
3675 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3676 Control Optimization}).
3677
3678 @item
3679 For test coverage analysis, use @command{gcov} to produce human readable
3680 information from the @file{.gcno} and @file{.gcda} files.  Refer to the
3681 @command{gcov} documentation for further information.
3682
3683 @end itemize
3684
3685 With @option{-fprofile-arcs}, for each function of your program GCC
3686 creates a program flow graph, then finds a spanning tree for the graph.
3687 Only arcs that are not on the spanning tree have to be instrumented: the
3688 compiler adds code to count the number of times that these arcs are
3689 executed.  When an arc is the only exit or only entrance to a block, the
3690 instrumentation code can be added to the block; otherwise, a new basic
3691 block must be created to hold the instrumentation code.
3692
3693 @need 2000
3694 @item -ftest-coverage
3695 @opindex ftest-coverage
3696 Produce a notes file that the @command{gcov} code-coverage utility
3697 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3698 show program coverage.  Each source file's note file is called
3699 @file{@var{auxname}.gcno}.  Refer to the @option{-fprofile-arcs} option
3700 above for a description of @var{auxname} and instructions on how to
3701 generate test coverage data.  Coverage data will match the source files
3702 more closely, if you do not optimize.
3703
3704 @item -d@var{letters}
3705 @item -fdump-rtl-@var{pass}
3706 @opindex d
3707 Says to make debugging dumps during compilation at times specified by
3708 @var{letters}.    This is used for debugging the RTL-based passes of the
3709 compiler.  The file names for most of the dumps are made by appending a
3710 pass number and a word to the @var{dumpname}.  @var{dumpname} is generated
3711 from the name of the output file, if explicitly specified and it is not
3712 an executable, otherwise it is the basename of the source file.
3713
3714 Most debug dumps can be enabled either passing a letter to the @option{-d}
3715 option, or with a long @option{-fdump-rtl} switch; here are the possible
3716 letters for use in @var{letters} and @var{pass}, and their meanings:
3717
3718 @table @gcctabopt
3719 @item -dA
3720 @opindex dA
3721 Annotate the assembler output with miscellaneous debugging information.
3722
3723 @item -dB
3724 @itemx -fdump-rtl-bbro
3725 @opindex dB
3726 @opindex fdump-rtl-bbro
3727 Dump after block reordering, to @file{@var{file}.148r.bbro}.
3728
3729 @item -dc
3730 @itemx -fdump-rtl-combine
3731 @opindex dc
3732 @opindex fdump-rtl-combine
3733 Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3734
3735 @item -dC
3736 @itemx -fdump-rtl-ce1
3737 @itemx -fdump-rtl-ce2
3738 @opindex dC
3739 @opindex fdump-rtl-ce1
3740 @opindex fdump-rtl-ce2
3741 @option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3742 first if conversion, to the file @file{@var{file}.117r.ce1}.  @option{-dC}
3743 and @option{-fdump-rtl-ce2} enable dumping after the second if
3744 conversion, to the file @file{@var{file}.130r.ce2}.
3745
3746 @item -dd
3747 @itemx -fdump-rtl-btl
3748 @itemx -fdump-rtl-dbr
3749 @opindex dd
3750 @opindex fdump-rtl-btl
3751 @opindex fdump-rtl-dbr
3752 @option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3753 target load optimization, to @file{@var{file}.31.btl}.  @option{-dd}
3754 and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3755 scheduling, to @file{@var{file}.36.dbr}.
3756
3757 @item -dD
3758 @opindex dD
3759 Dump all macro definitions, at the end of preprocessing, in addition to
3760 normal output.
3761
3762 @item -dE
3763 @itemx -fdump-rtl-ce3
3764 @opindex dE
3765 @opindex fdump-rtl-ce3
3766 Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3767
3768 @item -df
3769 @itemx -fdump-rtl-cfg
3770 @itemx -fdump-rtl-life
3771 @opindex df
3772 @opindex fdump-rtl-cfg
3773 @opindex fdump-rtl-life
3774 @option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3775 and data flow analysis, to @file{@var{file}.116r.cfg}.  @option{-df}
3776 and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3777 to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3778
3779 @item -dg
3780 @itemx -fdump-rtl-greg
3781 @opindex dg
3782 @opindex fdump-rtl-greg
3783 Dump after global register allocation, to @file{@var{file}.139r.greg}.
3784
3785 @item -dG
3786 @itemx -fdump-rtl-gcse
3787 @itemx -fdump-rtl-bypass
3788 @opindex dG
3789 @opindex fdump-rtl-gcse
3790 @opindex fdump-rtl-bypass
3791 @option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3792 @file{@var{file}.114r.gcse}.  @option{-dG} and @option{-fdump-rtl-bypass}
3793 enable dumping after jump bypassing and control flow optimizations, to
3794 @file{@var{file}.115r.bypass}.
3795
3796 @item -dh
3797 @itemx -fdump-rtl-eh
3798 @opindex dh
3799 @opindex fdump-rtl-eh
3800 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3801
3802 @item -di
3803 @itemx -fdump-rtl-sibling
3804 @opindex di
3805 @opindex fdump-rtl-sibling
3806 Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3807
3808 @item -dj
3809 @itemx -fdump-rtl-jump
3810 @opindex dj
3811 @opindex fdump-rtl-jump
3812 Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3813
3814 @item -dk
3815 @itemx -fdump-rtl-stack
3816 @opindex dk
3817 @opindex fdump-rtl-stack
3818 Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3819
3820 @item -dl
3821 @itemx -fdump-rtl-lreg
3822 @opindex dl
3823 @opindex fdump-rtl-lreg
3824 Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3825
3826 @item -dL
3827 @itemx -fdump-rtl-loop2
3828 @opindex dL
3829 @opindex fdump-rtl-loop2
3830 @option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3831 loop optimization pass, to @file{@var{file}.119r.loop2},
3832 @file{@var{file}.120r.loop2_init},
3833 @file{@var{file}.121r.loop2_invariant}, and
3834 @file{@var{file}.125r.loop2_done}.
3835
3836 @item -dm
3837 @itemx -fdump-rtl-sms
3838 @opindex dm
3839 @opindex fdump-rtl-sms
3840 Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3841
3842 @item -dM
3843 @itemx -fdump-rtl-mach
3844 @opindex dM
3845 @opindex fdump-rtl-mach
3846 Dump after performing the machine dependent reorganization pass, to
3847 @file{@var{file}.155r.mach}.
3848
3849 @item -dn
3850 @itemx -fdump-rtl-rnreg
3851 @opindex dn
3852 @opindex fdump-rtl-rnreg
3853 Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3854
3855 @item -dN
3856 @itemx -fdump-rtl-regmove
3857 @opindex dN
3858 @opindex fdump-rtl-regmove
3859 Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3860
3861 @item -do
3862 @itemx -fdump-rtl-postreload
3863 @opindex do
3864 @opindex fdump-rtl-postreload
3865 Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3866
3867 @item -dr
3868 @itemx -fdump-rtl-expand
3869 @opindex dr
3870 @opindex fdump-rtl-expand
3871 Dump after RTL generation, to @file{@var{file}.104r.expand}.
3872
3873 @item -dR
3874 @itemx -fdump-rtl-sched2
3875 @opindex dR
3876 @opindex fdump-rtl-sched2
3877 Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3878
3879 @item -ds
3880 @itemx -fdump-rtl-cse
3881 @opindex ds
3882 @opindex fdump-rtl-cse
3883 Dump after CSE (including the jump optimization that sometimes follows
3884 CSE), to @file{@var{file}.113r.cse}.
3885
3886 @item -dS
3887 @itemx -fdump-rtl-sched
3888 @opindex dS
3889 @opindex fdump-rtl-sched
3890 Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3891
3892 @item -dt
3893 @itemx -fdump-rtl-cse2
3894 @opindex dt
3895 @opindex fdump-rtl-cse2
3896 Dump after the second CSE pass (including the jump optimization that
3897 sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3898
3899 @item -dT
3900 @itemx -fdump-rtl-tracer
3901 @opindex dT
3902 @opindex fdump-rtl-tracer
3903 Dump after running tracer, to @file{@var{file}.118r.tracer}.
3904
3905 @item -dV
3906 @itemx -fdump-rtl-vpt
3907 @itemx -fdump-rtl-vartrack
3908 @opindex dV
3909 @opindex fdump-rtl-vpt
3910 @opindex fdump-rtl-vartrack
3911 @option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3912 profile transformations, to @file{@var{file}.10.vpt}.  @option{-dV}
3913 and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3914 to @file{@var{file}.154r.vartrack}.
3915
3916 @item -dw
3917 @itemx -fdump-rtl-flow2
3918 @opindex dw
3919 @opindex fdump-rtl-flow2
3920 Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3921
3922 @item -dz
3923 @itemx -fdump-rtl-peephole2
3924 @opindex dz
3925 @opindex fdump-rtl-peephole2
3926 Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3927
3928 @item -dZ
3929 @itemx -fdump-rtl-web
3930 @opindex dZ
3931 @opindex fdump-rtl-web
3932 Dump after live range splitting, to @file{@var{file}.126r.web}.
3933
3934 @item -da
3935 @itemx -fdump-rtl-all
3936 @opindex da
3937 @opindex fdump-rtl-all
3938 Produce all the dumps listed above.
3939
3940 @item -dH
3941 @opindex dH
3942 Produce a core dump whenever an error occurs.
3943
3944 @item -dm
3945 @opindex dm
3946 Print statistics on memory usage, at the end of the run, to
3947 standard error.
3948
3949 @item -dp
3950 @opindex dp
3951 Annotate the assembler output with a comment indicating which
3952 pattern and alternative was used.  The length of each instruction is
3953 also printed.
3954
3955 @item -dP
3956 @opindex dP
3957 Dump the RTL in the assembler output as a comment before each instruction.
3958 Also turns on @option{-dp} annotation.
3959
3960 @item -dv
3961 @opindex dv
3962 For each of the other indicated dump files (either with @option{-d} or
3963 @option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3964 graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3965
3966 @item -dx
3967 @opindex dx
3968 Just generate RTL for a function instead of compiling it.  Usually used
3969 with @samp{r} (@option{-fdump-rtl-expand}).
3970
3971 @item -dy
3972 @opindex dy
3973 Dump debugging information during parsing, to standard error.
3974 @end table
3975
3976 @item -fdump-unnumbered
3977 @opindex fdump-unnumbered
3978 When doing debugging dumps (see @option{-d} option above), suppress instruction
3979 numbers and line number note output.  This makes it more feasible to
3980 use diff on debugging dumps for compiler invocations with different
3981 options, in particular with and without @option{-g}.
3982
3983 @item -fdump-translation-unit @r{(C++ only)}
3984 @itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3985 @opindex fdump-translation-unit
3986 Dump a representation of the tree structure for the entire translation
3987 unit to a file.  The file name is made by appending @file{.tu} to the
3988 source file name.  If the @samp{-@var{options}} form is used, @var{options}
3989 controls the details of the dump as described for the
3990 @option{-fdump-tree} options.
3991
3992 @item -fdump-class-hierarchy @r{(C++ only)}
3993 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3994 @opindex fdump-class-hierarchy
3995 Dump a representation of each class's hierarchy and virtual function
3996 table layout to a file.  The file name is made by appending @file{.class}
3997 to the source file name.  If the @samp{-@var{options}} form is used,
3998 @var{options} controls the details of the dump as described for the
3999 @option{-fdump-tree} options.
4000
4001 @item -fdump-ipa-@var{switch}
4002 @opindex fdump-ipa
4003 Control the dumping at various stages of inter-procedural analysis
4004 language tree to a file.  The file name is generated by appending a switch
4005 specific suffix to the source file name.  The following dumps are possible:
4006
4007 @table @samp
4008 @item all
4009 Enables all inter-procedural analysis dumps; currently the only produced
4010 dump is the @samp{cgraph} dump.
4011
4012 @item cgraph
4013 Dumps information about call-graph optimization, unused function removal,
4014 and inlining decisions.
4015 @end table
4016
4017 @item -fdump-tree-@var{switch}
4018 @itemx -fdump-tree-@var{switch}-@var{options}
4019 @opindex fdump-tree
4020 Control the dumping at various stages of processing the intermediate
4021 language tree to a file.  The file name is generated by appending a switch
4022 specific suffix to the source file name.  If the @samp{-@var{options}}
4023 form is used, @var{options} is a list of @samp{-} separated options that
4024 control the details of the dump.  Not all options are applicable to all
4025 dumps, those which are not meaningful will be ignored.  The following
4026 options are available
4027
4028 @table @samp
4029 @item address
4030 Print the address of each node.  Usually this is not meaningful as it
4031 changes according to the environment and source file.  Its primary use
4032 is for tying up a dump file with a debug environment.
4033 @item slim
4034 Inhibit dumping of members of a scope or body of a function merely
4035 because that scope has been reached.  Only dump such items when they
4036 are directly reachable by some other path.  When dumping pretty-printed
4037 trees, this option inhibits dumping the bodies of control structures.
4038 @item raw
4039 Print a raw representation of the tree.  By default, trees are
4040 pretty-printed into a C-like representation.
4041 @item details
4042 Enable more detailed dumps (not honored by every dump option).
4043 @item stats
4044 Enable dumping various statistics about the pass (not honored by every dump
4045 option).
4046 @item blocks
4047 Enable showing basic block boundaries (disabled in raw dumps).
4048 @item vops
4049 Enable showing virtual operands for every statement.
4050 @item lineno
4051 Enable showing line numbers for statements.
4052 @item uid
4053 Enable showing the unique ID (@code{DECL_UID}) for each variable.
4054 @item all
4055 Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4056 @end table
4057
4058 The following tree dumps are possible:
4059 @table @samp
4060
4061 @item original
4062 Dump before any tree based optimization, to @file{@var{file}.original}.
4063
4064 @item optimized
4065 Dump after all tree based optimization, to @file{@var{file}.optimized}.
4066
4067 @item inlined
4068 Dump after function inlining, to @file{@var{file}.inlined}.
4069
4070 @item gimple
4071 @opindex fdump-tree-gimple
4072 Dump each function before and after the gimplification pass to a file.  The
4073 file name is made by appending @file{.gimple} to the source file name.
4074
4075 @item cfg
4076 @opindex fdump-tree-cfg
4077 Dump the control flow graph of each function to a file.  The file name is
4078 made by appending @file{.cfg} to the source file name.
4079
4080 @item vcg
4081 @opindex fdump-tree-vcg
4082 Dump the control flow graph of each function to a file in VCG format.  The
4083 file name is made by appending @file{.vcg} to the source file name.  Note
4084 that if the file contains more than one function, the generated file cannot
4085 be used directly by VCG@.  You will need to cut and paste each function's
4086 graph into its own separate file first.
4087
4088 @item ch
4089 @opindex fdump-tree-ch
4090 Dump each function after copying loop headers.  The file name is made by
4091 appending @file{.ch} to the source file name.
4092
4093 @item ssa
4094 @opindex fdump-tree-ssa
4095 Dump SSA related information to a file.  The file name is made by appending
4096 @file{.ssa} to the source file name.
4097
4098 @item salias
4099 @opindex fdump-tree-salias
4100 Dump structure aliasing variable information to a file.  This file name
4101 is made by appending @file{.salias} to the source file name.
4102
4103 @item alias
4104 @opindex fdump-tree-alias
4105 Dump aliasing information for each function.  The file name is made by
4106 appending @file{.alias} to the source file name.
4107
4108 @item ccp
4109 @opindex fdump-tree-ccp
4110 Dump each function after CCP@.  The file name is made by appending
4111 @file{.ccp} to the source file name.
4112
4113 @item storeccp
4114 @opindex fdump-tree-storeccp
4115 Dump each function after STORE-CCP.  The file name is made by appending
4116 @file{.storeccp} to the source file name.
4117
4118 @item pre
4119 @opindex fdump-tree-pre
4120 Dump trees after partial redundancy elimination.  The file name is made
4121 by appending @file{.pre} to the source file name.
4122
4123 @item fre
4124 @opindex fdump-tree-fre
4125 Dump trees after full redundancy elimination.  The file name is made
4126 by appending @file{.fre} to the source file name.
4127
4128 @item copyprop
4129 @opindex fdump-tree-copyprop
4130 Dump trees after copy propagation.  The file name is made
4131 by appending @file{.copyprop} to the source file name.
4132
4133 @item store_copyprop
4134 @opindex fdump-tree-store_copyprop
4135 Dump trees after store copy-propagation.  The file name is made
4136 by appending @file{.store_copyprop} to the source file name.
4137
4138 @item dce
4139 @opindex fdump-tree-dce
4140 Dump each function after dead code elimination.  The file name is made by
4141 appending @file{.dce} to the source file name.
4142
4143 @item mudflap
4144 @opindex fdump-tree-mudflap
4145 Dump each function after adding mudflap instrumentation.  The file name is
4146 made by appending @file{.mudflap} to the source file name.
4147
4148 @item sra
4149 @opindex fdump-tree-sra
4150 Dump each function after performing scalar replacement of aggregates.  The
4151 file name is made by appending @file{.sra} to the source file name.
4152
4153 @item sink
4154 @opindex fdump-tree-sink
4155 Dump each function after performing code sinking.  The file name is made
4156 by appending @file{.sink} to the source file name. 
4157
4158 @item dom
4159 @opindex fdump-tree-dom
4160 Dump each function after applying dominator tree optimizations.  The file
4161 name is made by appending @file{.dom} to the source file name.
4162
4163 @item dse
4164 @opindex fdump-tree-dse
4165 Dump each function after applying dead store elimination.  The file
4166 name is made by appending @file{.dse} to the source file name.
4167
4168 @item phiopt
4169 @opindex fdump-tree-phiopt
4170 Dump each function after optimizing PHI nodes into straightline code.  The file
4171 name is made by appending @file{.phiopt} to the source file name.
4172
4173 @item forwprop
4174 @opindex fdump-tree-forwprop
4175 Dump each function after forward propagating single use variables.  The file
4176 name is made by appending @file{.forwprop} to the source file name.
4177
4178 @item copyrename
4179 @opindex fdump-tree-copyrename
4180 Dump each function after applying the copy rename optimization.  The file
4181 name is made by appending @file{.copyrename} to the source file name.
4182
4183 @item nrv
4184 @opindex fdump-tree-nrv
4185 Dump each function after applying the named return value optimization on
4186 generic trees.  The file name is made by appending @file{.nrv} to the source
4187 file name.
4188
4189 @item vect
4190 @opindex fdump-tree-vect
4191 Dump each function after applying vectorization of loops.  The file name is
4192 made by appending @file{.vect} to the source file name.
4193
4194 @item vrp
4195 @opindex fdump-tree-vrp
4196 Dump each function after Value Range Propagation (VRP).  The file name
4197 is made by appending @file{.vrp} to the source file name.
4198
4199 @item all
4200 @opindex fdump-tree-all
4201 Enable all the available tree dumps with the flags provided in this option.
4202 @end table
4203
4204 @item -ftree-vectorizer-verbose=@var{n}
4205 @opindex ftree-vectorizer-verbose
4206 This option controls the amount of debugging output the vectorizer prints.
4207 This information is written to standard error, unless 
4208 @option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified, 
4209 in which case it is output to the usual dump listing file, @file{.vect}.
4210 For @var{n}=0 no diagnostic information is reported.
4211 If @var{n}=1 the vectorizer reports each loop that got vectorized, 
4212 and the total number of loops that got vectorized.
4213 If @var{n}=2 the vectorizer also reports non-vectorized loops that passed 
4214 the first analysis phase (vect_analyze_loop_form) - i.e. countable, 
4215 inner-most, single-bb, single-entry/exit loops.  This is the same verbosity 
4216 level that @option{-fdump-tree-vect-stats} uses.
4217 Higher verbosity levels mean either more information dumped for each 
4218 reported loop, or same amount of information reported for more loops:
4219 If @var{n}=3, alignment related information is added to the reports.
4220 If @var{n}=4, data-references related information (e.g. memory dependences, 
4221 memory access-patterns) is added to the reports.
4222 If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops 
4223 that did not pass the first analysis phase (i.e. may not be countable, or 
4224 may have complicated control-flow).
4225 If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4226 For @var{n}=7, all the information the vectorizer generates during its 
4227 analysis and transformation is reported.  This is the same verbosity level
4228 that @option{-fdump-tree-vect-details} uses.
4229
4230 @item -frandom-seed=@var{string}
4231 @opindex frandom-string
4232 This option provides a seed that GCC uses when it would otherwise use
4233 random numbers.  It is used to generate certain symbol names
4234 that have to be different in every compiled file.  It is also used to
4235 place unique stamps in coverage data files and the object files that
4236 produce them.  You can use the @option{-frandom-seed} option to produce
4237 reproducibly identical object files.
4238
4239 The @var{string} should be different for every file you compile.
4240
4241 @item -fsched-verbose=@var{n}
4242 @opindex fsched-verbose
4243 On targets that use instruction scheduling, this option controls the
4244 amount of debugging output the scheduler prints.  This information is
4245 written to standard error, unless @option{-dS} or @option{-dR} is
4246 specified, in which case it is output to the usual dump
4247 listing file, @file{.sched} or @file{.sched2} respectively.  However
4248 for @var{n} greater than nine, the output is always printed to standard
4249 error.
4250
4251 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4252 same information as @option{-dRS}.  For @var{n} greater than one, it
4253 also output basic block probabilities, detailed ready list information
4254 and unit/insn info.  For @var{n} greater than two, it includes RTL
4255 at abort point, control-flow and regions info.  And for @var{n} over
4256 four, @option{-fsched-verbose} also includes dependence info.
4257
4258 @item -save-temps
4259 @opindex save-temps
4260 Store the usual ``temporary'' intermediate files permanently; place them
4261 in the current directory and name them based on the source file.  Thus,
4262 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4263 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.  This creates a
4264 preprocessed @file{foo.i} output file even though the compiler now
4265 normally uses an integrated preprocessor.
4266
4267 When used in combination with the @option{-x} command line option,
4268 @option{-save-temps} is sensible enough to avoid over writing an
4269 input source file with the same extension as an intermediate file.
4270 The corresponding intermediate file may be obtained by renaming the
4271 source file before using @option{-save-temps}.
4272
4273 @item -time
4274 @opindex time
4275 Report the CPU time taken by each subprocess in the compilation
4276 sequence.  For C source files, this is the compiler proper and assembler
4277 (plus the linker if linking is done).  The output looks like this:
4278
4279 @smallexample
4280 # cc1 0.12 0.01
4281 # as 0.00 0.01
4282 @end smallexample
4283
4284 The first number on each line is the ``user time'', that is time spent
4285 executing the program itself.  The second number is ``system time'',
4286 time spent executing operating system routines on behalf of the program.
4287 Both numbers are in seconds.
4288
4289 @item -fvar-tracking
4290 @opindex fvar-tracking
4291 Run variable tracking pass.  It computes where variables are stored at each
4292 position in code.  Better debugging information is then generated
4293 (if the debugging information format supports this information).
4294
4295 It is enabled by default when compiling with optimization (@option{-Os},
4296 @option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4297 the debug info format supports it.
4298
4299 @item -print-file-name=@var{library}
4300 @opindex print-file-name