OSDN Git Service

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