OSDN Git Service

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