OSDN Git Service

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