OSDN Git Service

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