OSDN Git Service

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