OSDN Git Service

2002-08-28 Sylvain Pion <pion@cs.nyu.edu>
[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 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 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.1 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
70 When you invoke GCC, it normally does preprocessing, compilation,
71 assembly and linking.  The ``overall options'' allow you to stop this
72 process at an intermediate stage.  For example, the @option{-c} option
73 says not to run the linker.  Then the output consists of object files
74 output by the assembler.
75
76 Other options are passed on to one stage of processing.  Some options
77 control the preprocessor and others the compiler itself.  Yet other
78 options control the assembler and linker; most of these are not
79 documented here, since you rarely need to use any of them.
80
81 @cindex C compilation options
82 Most of the command line options that you can use with GCC are useful
83 for C programs; when an option is only useful with another language
84 (usually C++), the explanation says so explicitly.  If the description
85 for a particular option does not mention a source language, you can use
86 that option with all supported languages.
87
88 @cindex C++ compilation options
89 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
90 options for compiling C++ programs.
91
92 @cindex grouping options
93 @cindex options, grouping
94 The @command{gcc} program accepts options and file names as operands.  Many
95 options have multi-letter names; therefore multiple single-letter options
96 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
97 -r}}.
98
99 @cindex order of options
100 @cindex options, order
101 You can mix options and other arguments.  For the most part, the order
102 you use doesn't matter.  Order does matter when you use several options
103 of the same kind; for example, if you specify @option{-L} more than once,
104 the directories are searched in the order specified.
105
106 Many options have long names starting with @samp{-f} or with
107 @samp{-W}---for example, @option{-fforce-mem},
108 @option{-fstrength-reduce}, @option{-Wformat} and so on.  Most of
109 these have both positive and negative forms; the negative form of
110 @option{-ffoo} would be @option{-fno-foo}.  This manual documents
111 only one of these two forms, whichever one is not the default.
112
113 @c man end
114
115 @xref{Option Index}, for an index to GCC's options.
116
117 @menu
118 * Option Summary::      Brief list of all options, without explanations.
119 * Overall Options::     Controlling the kind of output:
120                         an executable, object files, assembler files,
121                         or preprocessed source.
122 * Invoking G++::        Compiling C++ programs.
123 * C Dialect Options::   Controlling the variant of C language compiled.
124 * C++ Dialect Options:: Variations on C++.
125 * Objective-C Dialect Options:: Variations on Objective-C.
126 * Language Independent Options:: Controlling how diagnostics should be
127                         formatted.
128 * Warning Options::     How picky should the compiler be?
129 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
130 * Optimize Options::    How much optimization?
131 * Preprocessor Options:: Controlling header files and macro definitions.
132                          Also, getting dependency information for Make.
133 * Assembler Options::   Passing options to the assembler.
134 * Link Options::        Specifying libraries and so on.
135 * Directory Options::   Where to find header files and libraries.
136                         Where to find the compiler executable files.
137 * Spec Files::          How to pass switches to sub-processes.
138 * Target Options::      Running a cross-compiler, or an old version of GCC.
139 * Submodel Options::    Specifying minor hardware or convention variations,
140                         such as 68010 vs 68020.
141 * Code Gen Options::    Specifying conventions for function calls, data layout
142                         and register usage.
143 * Environment Variables:: Env vars that affect GCC.
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{
159 -c  -S  -E  -o @var{file}  -pipe  -pass-exit-codes  -x @var{language} @gol
160 -v  -###  --target-help  --help}
161
162 @item C Language Options
163 @xref{C Dialect Options,,Options Controlling C Dialect}.
164 @gccoptlist{
165 -ansi  -std=@var{standard}  -aux-info @var{filename} @gol
166 -fno-asm  -fno-builtin -fno-builtin-@var{function} @gol
167 -fhosted  -ffreestanding  -fms-extensions @gol
168 -trigraphs  -traditional  -traditional-cpp @gol
169 -fallow-single-precision  -fcond-mismatch @gol
170 -fsigned-bitfields  -fsigned-char @gol
171 -funsigned-bitfields  -funsigned-char @gol
172 -fwritable-strings  -fshort-wchar}
173
174 @item C++ Language Options
175 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
176 @gccoptlist{
177 -fno-access-control  -fcheck-new  -fconserve-space @gol
178 -fno-const-strings  -fdollars-in-identifiers @gol
179 -fno-elide-constructors @gol
180 -fno-enforce-eh-specs  -fexternal-templates @gol
181 -falt-external-templates @gol
182 -ffor-scope  -fno-for-scope  -fno-gnu-keywords @gol
183 -fno-implicit-templates @gol
184 -fno-implicit-inline-templates @gol
185 -fno-implement-inlines  -fms-extensions @gol
186 -fno-nonansi-builtins  -fno-operator-names @gol
187 -fno-optional-diags  -fpermissive @gol
188 -frepo  -fno-rtti  -fstats  -ftemplate-depth-@var{n} @gol
189 -fuse-cxa-atexit  -fvtable-gc  -fno-weak  -nostdinc++ @gol
190 -fno-default-inline -Wabi -Wctor-dtor-privacy @gol
191 -Wnon-virtual-dtor  -Wreorder @gol
192 -Weffc++  -Wno-deprecated @gol
193 -Wno-non-template-friend  -Wold-style-cast @gol
194 -Woverloaded-virtual  -Wno-pmf-conversions @gol
195 -Wsign-promo  -Wsynth}
196
197 @item Objective-C Language Options
198 @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}.
199 @gccoptlist{
200 -fconstant-string-class=@var{class-name} @gol
201 -fgnu-runtime  -fnext-runtime  -gen-decls @gol
202 -Wno-protocol  -Wselector}
203
204 @item Language Independent Options
205 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
206 @gccoptlist{
207 -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{
213 -fsyntax-only  -pedantic  -pedantic-errors @gol
214 -w  -W  -Wall -Waggregate-return @gol
215 -Wcast-align  -Wcast-qual  -Wchar-subscripts  -Wcomment @gol
216 -Wconversion  -Wno-deprecated-declarations @gol
217 -Wdisabled-optimization  -Wno-div-by-zero  -Werror @gol
218 -Wfloat-equal  -Wformat  -Wformat=2 @gol
219 -Wformat-nonliteral  -Wformat-security @gol
220 -Wimplicit  -Wimplicit-int  @gol
221 -Wimplicit-function-declaration @gol
222 -Werror-implicit-function-declaration @gol
223 -Wimport  -Winline -Wno-endif-labels @gol
224 -Wlarger-than-@var{len}  -Wlong-long @gol
225 -Wmain  -Wmissing-braces  -Wmissing-declarations @gol
226 -Wmissing-format-attribute  -Wmissing-noreturn @gol
227 -Wno-multichar  -Wno-format-extra-args  -Wno-format-y2k @gol
228 -Wno-import  -Wnonnull  -Wpacked  -Wpadded @gol
229 -Wparentheses  -Wpointer-arith  -Wredundant-decls @gol
230 -Wreturn-type  -Wsequence-point  -Wshadow @gol
231 -Wsign-compare  -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{
239 -Wbad-function-cast  -Wmissing-prototypes  -Wnested-externs @gol
240 -Wstrict-prototypes  -Wtraditional}
241
242 @item Debugging Options
243 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
244 @gccoptlist{
245 -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{]} -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
249 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
250 -fmem-report @gol
251 -fprofile-arcs  -ftest-coverage  -ftime-report @gol
252 -g  -g@var{level}  -gcoff  -gdwarf  -gdwarf-1  -gdwarf-1+  -gdwarf-2 @gol
253 -ggdb  -gstabs  -gstabs+  -gvms  -gxcoff  -gxcoff+ @gol
254 -p  -pg  -print-file-name=@var{library}  -print-libgcc-file-name @gol
255 -print-multi-directory  -print-multi-lib @gol
256 -print-prog-name=@var{program}  -print-search-dirs  -Q @gol
257 -save-temps  -time}
258
259 @item Optimization Options
260 @xref{Optimize Options,,Options that Control Optimization}.
261 @gccoptlist{
262 -falign-functions=@var{n}  -falign-jumps=@var{n} @gol
263 -falign-labels=@var{n}  -falign-loops=@var{n}  @gol
264 -fbranch-probabilities  -fcaller-saves -fcprop-registers @gol
265 -fcse-follow-jumps  -fcse-skip-blocks  -fdata-sections @gol
266 -fdelayed-branch  -fdelete-null-pointer-checks @gol
267 -fexpensive-optimizations  -ffast-math  -ffloat-store @gol
268 -fforce-addr  -fforce-mem  -ffunction-sections @gol
269 -fgcse  -fgcse-lm  -fgcse-sm -floop-optimize -fcrossjumping @gol
270 -fif-conversion -fif-conversion2 @gol
271 -finline-functions  -finline-limit=@var{n}  -fkeep-inline-functions @gol
272 -fkeep-static-consts  -fmerge-constants  -fmerge-all-constants @gol
273 -fmove-all-movables  -fnew-ra -fno-default-inline  -fno-defer-pop @gol
274 -fno-function-cse  -fno-guess-branch-probability @gol
275 -fno-inline  -fno-math-errno  -fno-peephole  -fno-peephole2 @gol
276 -funsafe-math-optimizations -ffinite-math-only -fno-trapping-math @gol
277 -fno-zero-initialized-in-bss @gol
278 -fomit-frame-pointer  -foptimize-register-move @gol
279 -foptimize-sibling-calls  -fprefetch-loop-arrays @gol
280 -freduce-all-givs -fregmove  -frename-registers @gol
281 -freorder-blocks -freorder-functions @gol
282 -frerun-cse-after-loop  -frerun-loop-opt @gol
283 -fschedule-insns  -fschedule-insns2 -fsignaling-nans @gol
284 -fsingle-precision-constant  -fssa -fssa-ccp -fssa-dce @gol
285 -fstrength-reduce  -fstrict-aliasing  -ftracer -fthread-jumps  -ftrapv @gol
286 -funroll-all-loops  -funroll-loops  @gol
287 --param @var{name}=@var{value}
288 -O  -O0  -O1  -O2  -O3  -Os}
289
290 @item Preprocessor Options
291 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
292 @gccoptlist{
293 -$  -A@var{question}=@var{answer}  -A-@var{question}@r{[}=@var{answer}@r{]} @gol
294 -C  -dD  -dI  -dM  -dN @gol
295 -D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H @gol
296 -idirafter @var{dir} @gol
297 -include @var{file}  -imacros @var{file} @gol
298 -iprefix @var{file}  -iwithprefix @var{dir} @gol
299 -iwithprefixbefore @var{dir}  -isystem @var{dir} @gol
300 -M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  -P  -remap @gol
301 -trigraphs  -undef  -U@var{macro}  -Wp,@var{option}}
302
303 @item Assembler Option
304 @xref{Assembler Options,,Passing Options to the Assembler}.
305 @gccoptlist{
306 -Wa,@var{option}}
307
308 @item Linker Options
309 @xref{Link Options,,Options for Linking}.
310 @gccoptlist{
311 @var{object-file-name}  -l@var{library} @gol
312 -nostartfiles  -nodefaultlibs  -nostdlib @gol
313 -s  -static  -static-libgcc  -shared  -shared-libgcc  -symbolic @gol
314 -Wl,@var{option}  -Xlinker @var{option} @gol
315 -u @var{symbol}}
316
317 @item Directory Options
318 @xref{Directory Options,,Options for Directory Search}.
319 @gccoptlist{
320 -B@var{prefix}  -I@var{dir}  -I-  -L@var{dir}  -specs=@var{file}}
321
322 @item Target Options
323 @c I wrote this xref this way to avoid overfull hbox. -- rms
324 @xref{Target Options}.
325 @gccoptlist{
326 -V @var{version} -b @var{machine}}
327
328 @item Machine Dependent Options
329 @xref{Submodel Options,,Hardware Models and Configurations}.
330
331 @emph{M680x0 Options}
332 @gccoptlist{
333 -m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040 @gol
334 -m68060  -mcpu32  -m5200  -m68881  -mbitfield  -mc68000  -mc68020   @gol
335 -mfpa  -mnobitfield  -mrtd  -mshort  -msoft-float  -mpcrel @gol
336 -malign-int  -mstrict-align}
337
338 @emph{M68hc1x Options}
339 @gccoptlist{
340 -m6811  -m6812  -m68hc11  -m68hc12 @gol
341 -mauto-incdec  -minmax  -mlong-calls  -mshort  -msoft-reg-count=@var{count}}
342
343 @emph{VAX Options}
344 @gccoptlist{
345 -mg  -mgnu  -munix}
346
347 @emph{SPARC Options}
348 @gccoptlist{
349 -mcpu=@var{cpu-type} @gol
350 -mtune=@var{cpu-type} @gol
351 -mcmodel=@var{code-model} @gol
352 -m32  -m64 @gol
353 -mapp-regs  -mbroken-saverestore  -mcypress @gol
354 -mfaster-structs  -mflat @gol
355 -mfpu  -mhard-float  -mhard-quad-float @gol
356 -mimpure-text  -mlive-g0  -mno-app-regs @gol
357 -mno-faster-structs  -mno-flat  -mno-fpu @gol
358 -mno-impure-text  -mno-stack-bias  -mno-unaligned-doubles @gol
359 -msoft-float  -msoft-quad-float  -msparclite  -mstack-bias @gol
360 -msupersparc  -munaligned-doubles  -mv8}
361
362 @emph{Convex Options}
363 @gccoptlist{
364 -mc1  -mc2  -mc32  -mc34  -mc38 @gol
365 -margcount  -mnoargcount @gol
366 -mlong32  -mlong64 @gol
367 -mvolatile-cache  -mvolatile-nocache}
368
369 @emph{AMD29K Options}
370 @gccoptlist{
371 -m29000  -m29050  -mbw  -mnbw  -mdw  -mndw @gol
372 -mlarge  -mnormal  -msmall @gol
373 -mkernel-registers  -mno-reuse-arg-regs @gol
374 -mno-stack-check  -mno-storem-bug @gol
375 -mreuse-arg-regs  -msoft-float  -mstack-check @gol
376 -mstorem-bug  -muser-registers}
377
378 @emph{ARM Options}
379 @gccoptlist{
380 -mapcs-frame  -mno-apcs-frame @gol
381 -mapcs-26  -mapcs-32 @gol
382 -mapcs-stack-check  -mno-apcs-stack-check @gol
383 -mapcs-float  -mno-apcs-float @gol
384 -mapcs-reentrant  -mno-apcs-reentrant @gol
385 -msched-prolog  -mno-sched-prolog @gol
386 -mlittle-endian  -mbig-endian  -mwords-little-endian @gol
387 -malignment-traps  -mno-alignment-traps @gol
388 -msoft-float  -mhard-float  -mfpe @gol
389 -mthumb-interwork  -mno-thumb-interwork @gol
390 -mcpu=@var{name}  -march=@var{name}  -mfpe=@var{name}  @gol
391 -mstructure-size-boundary=@var{n} @gol
392 -mbsd -mxopen  -mno-symrename @gol
393 -mabort-on-noreturn @gol
394 -mlong-calls  -mno-long-calls @gol
395 -msingle-pic-base  -mno-single-pic-base @gol
396 -mpic-register=@var{reg} @gol
397 -mnop-fun-dllimport @gol
398 -mpoke-function-name @gol
399 -mthumb  -marm @gol
400 -mtpcs-frame  -mtpcs-leaf-frame @gol
401 -mcaller-super-interworking  -mcallee-super-interworking }
402
403 @emph{MN10200 Options}
404 @gccoptlist{
405 -mrelax}
406
407 @emph{MN10300 Options}
408 @gccoptlist{
409 -mmult-bug  -mno-mult-bug @gol
410 -mam33  -mno-am33 @gol
411 -mno-crt0  -mrelax}
412
413 @emph{M32R/D Options}
414 @gccoptlist{
415 -m32rx -m32r -mcode-model=@var{model-type}  -msdata=@var{sdata-type} @gol
416 -G @var{num}}
417
418 @emph{M88K Options}
419 @gccoptlist{
420 -m88000  -m88100  -m88110  -mbig-pic @gol
421 -mcheck-zero-division  -mhandle-large-shift @gol
422 -midentify-revision  -mno-check-zero-division @gol
423 -mno-ocs-debug-info  -mno-ocs-frame-position @gol
424 -mno-optimize-arg-area  -mno-serialize-volatile @gol
425 -mno-underscores  -mocs-debug-info @gol
426 -mocs-frame-position  -moptimize-arg-area @gol
427 -mserialize-volatile  -mshort-data-@var{num}  -msvr3 @gol
428 -msvr4  -mtrap-large-shift  -muse-div-instruction @gol
429 -mversion-03.00  -mwarn-passed-structs}
430
431 @emph{RS/6000 and PowerPC Options}
432 @gccoptlist{
433 -mcpu=@var{cpu-type} @gol
434 -mtune=@var{cpu-type} @gol
435 -mpower  -mno-power  -mpower2  -mno-power2 @gol
436 -mpowerpc  -mpowerpc64  -mno-powerpc @gol
437 -maltivec -mno-altivec @gol
438 -mpowerpc-gpopt  -mno-powerpc-gpopt @gol
439 -mpowerpc-gfxopt  -mno-powerpc-gfxopt @gol
440 -mnew-mnemonics  -mold-mnemonics @gol
441 -mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc @gol
442 -m64  -m32  -mxl-call  -mno-xl-call  -mpe @gol
443 -msoft-float  -mhard-float  -mmultiple  -mno-multiple @gol
444 -mstring  -mno-string  -mupdate  -mno-update @gol
445 -mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align @gol
446 -mstrict-align  -mno-strict-align  -mrelocatable @gol
447 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
448 -mtoc  -mno-toc -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
449 -mcall-aix -mcall-sysv -mcall-netbsd @gol
450 -maix-struct-return -msvr4-struct-return
451 -mabi=altivec -mabi=no-altivec @gol
452 -mabi=spe -mabi=no-spe @gol
453 -misel=yes -misel=no @gol
454 -mprototype  -mno-prototype @gol
455 -msim  -mmvme  -mads  -myellowknife  -memb -msdata @gol
456 -msdata=@var{opt}  -mvxworks -mwindiss -G @var{num} -pthread}
457
458 @emph{RT Options}
459 @gccoptlist{
460 -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs @gol
461 -mfull-fp-blocks  -mhc-struct-return  -min-line-mul @gol
462 -mminimum-fp-blocks  -mnohc-struct-return}
463
464 @emph{MIPS Options}
465 @gccoptlist{
466 -mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol
467 -mcpu=@var{cpu-type} -membedded-data  -muninit-const-in-rodata @gol
468 -membedded-pic  -mfp32  -mfp64  -mfused-madd  -mno-fused-madd @gol
469 -mgas  -mgp32  -mgp64 @gol
470 -mgpopt  -mhalf-pic  -mhard-float  -mint64  -mips1 @gol
471 -mips2  -mips3  -mips4  -mlong64  -mlong32  -mlong-calls  -mmemcpy @gol
472 -mmips-as  -mmips-tfile  -mno-abicalls @gol
473 -mno-embedded-data  -mno-uninit-const-in-rodata @gol
474 -mno-embedded-pic  -mno-gpopt  -mno-long-calls @gol
475 -mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats @gol
476 -mrnames  -msoft-float @gol
477 -m4650  -msingle-float  -mmad @gol
478 -mstats  -EL  -EB  -G @var{num}  -nocpp @gol
479 -mabi=32  -mabi=n32  -mabi=64  -mabi=eabi @gol
480 -mfix7000  -mno-crt0 -mflush-func=@var{func} -mno-flush-func
481 -mbranch-likely -mno-branch-likely}
482
483 @emph{i386 and x86-64 Options}
484 @gccoptlist{
485 -mcpu=@var{cpu-type}  -march=@var{cpu-type} -mfpmath=@var{unit} @gol
486 -masm=@var{dialect}  -mno-fancy-math-387 @gol
487 -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib @gol
488 -mno-wide-multiply  -mrtd  -malign-double @gol
489 -mpreferred-stack-boundary=@var{num} @gol
490 -mmmx  -msse -msse2 -msse-math -m3dnow @gol
491 -mthreads  -mno-align-stringops  -minline-all-stringops @gol
492 -mpush-args  -maccumulate-outgoing-args  -m128bit-long-double @gol
493 -m96bit-long-double  -mregparm=@var{num}  -momit-leaf-frame-pointer @gol
494 -mno-red-zone@gol
495 -mcmodel=@var{code-model} @gol
496 -m32 -m64}
497
498 @emph{HPPA Options}
499 @gccoptlist{
500 -march=@var{architecture-type} @gol
501 -mbig-switch  -mdisable-fpregs  -mdisable-indexing @gol
502 -mfast-indirect-calls  -mgas  -mjump-in-delay @gol
503 -mlong-load-store  -mno-big-switch  -mno-disable-fpregs @gol
504 -mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas @gol
505 -mno-jump-in-delay  -mno-long-load-store @gol
506 -mno-portable-runtime  -mno-soft-float @gol
507 -mno-space-regs  -msoft-float  -mpa-risc-1-0 @gol
508 -mpa-risc-1-1  -mpa-risc-2-0  -mportable-runtime @gol
509 -mschedule=@var{cpu-type}  -mspace-regs}
510
511 @emph{Intel 960 Options}
512 @gccoptlist{
513 -m@var{cpu-type}  -masm-compat  -mclean-linkage @gol
514 -mcode-align  -mcomplex-addr  -mleaf-procedures @gol
515 -mic-compat  -mic2.0-compat  -mic3.0-compat @gol
516 -mintel-asm  -mno-clean-linkage  -mno-code-align @gol
517 -mno-complex-addr  -mno-leaf-procedures @gol
518 -mno-old-align  -mno-strict-align  -mno-tail-call @gol
519 -mnumerics  -mold-align  -msoft-float  -mstrict-align @gol
520 -mtail-call}
521
522 @emph{DEC Alpha Options}
523 @gccoptlist{
524 -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 -mmemory-latency=@var{time}}
533
534 @emph{DEC Alpha/VMS Options}
535 @gccoptlist{
536 -mvms-return-codes}
537
538 @emph{Clipper Options}
539 @gccoptlist{
540 -mc300  -mc400}
541
542 @emph{H8/300 Options}
543 @gccoptlist{
544 -mrelax  -mh  -ms  -mint32  -malign-300}
545
546 @emph{SH Options}
547 @gccoptlist{
548 -m1  -m2  -m3  -m3e @gol
549 -m4-nofpu  -m4-single-only  -m4-single  -m4 @gol
550 -m5-64media -m5-64media-nofpu @gol
551 -m5-32media -m5-32media-nofpu @gol
552 -m5-compact -m5-compact-nofpu @gol
553 -mb  -ml  -mdalign  -mrelax @gol
554 -mbigtable  -mfmovd  -mhitachi  -mnomacsave @gol
555 -mieee  -misize  -mpadstruct  -mspace @gol
556 -mprefergot  -musermode}
557
558 @emph{System V Options}
559 @gccoptlist{
560 -Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}}
561
562 @emph{ARC Options}
563 @gccoptlist{
564 -EB  -EL @gol
565 -mmangle-cpu  -mcpu=@var{cpu}  -mtext=@var{text-section} @gol
566 -mdata=@var{data-section}  -mrodata=@var{readonly-data-section}}
567
568 @emph{TMS320C3x/C4x Options}
569 @gccoptlist{
570 -mcpu=@var{cpu}  -mbig  -msmall  -mregparm  -mmemparm @gol
571 -mfast-fix  -mmpyi  -mbk  -mti  -mdp-isr-reload @gol
572 -mrpts=@var{count}  -mrptb  -mdb  -mloop-unsigned @gol
573 -mparallel-insns  -mparallel-mpy  -mpreserve-float}
574
575 @emph{V850 Options}
576 @gccoptlist{
577 -mlong-calls  -mno-long-calls  -mep  -mno-ep @gol
578 -mprolog-function  -mno-prolog-function  -mspace @gol
579 -mtda=@var{n}  -msda=@var{n}  -mzda=@var{n} @gol
580 -mapp-regs -mno-app-regs @gol
581 -mdisable-callt -mno-disable-callt @gol
582 -mv850e @gol
583 -mv850  -mbig-switch}
584
585 @emph{NS32K Options}
586 @gccoptlist{
587 -m32032  -m32332  -m32532  -m32081  -m32381 @gol
588 -mmult-add  -mnomult-add  -msoft-float  -mrtd  -mnortd @gol
589 -mregparam  -mnoregparam  -msb  -mnosb @gol
590 -mbitfield  -mnobitfield  -mhimem  -mnohimem}
591
592 @emph{AVR Options}
593 @gccoptlist{
594 -mmcu=@var{mcu}  -msize  -minit-stack=@var{n}  -mno-interrupts @gol
595 -mcall-prologues  -mno-tablejump  -mtiny-stack}
596
597 @emph{MCore Options}
598 @gccoptlist{
599 -mhardlit  -mno-hardlit  -mdiv  -mno-div  -mrelax-immediates @gol
600 -mno-relax-immediates  -mwide-bitfields  -mno-wide-bitfields @gol
601 -m4byte-functions  -mno-4byte-functions  -mcallgraph-data @gol
602 -mno-callgraph-data  -mslow-bytes  -mno-slow-bytes  -mno-lsim @gol
603 -mlittle-endian  -mbig-endian  -m210  -m340  -mstack-increment}
604
605 @emph{MMIX Options}
606 @gccoptlist{
607 -mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
608 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
609 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
610 -mno-base-addresses -msingle-exit -mno-single-exit}
611
612 @emph{IA-64 Options}
613 @gccoptlist{
614 -mbig-endian  -mlittle-endian  -mgnu-as  -mgnu-ld  -mno-pic @gol
615 -mvolatile-asm-stop  -mb-step  -mregister-names  -mno-sdata @gol
616 -mconstant-gp  -mauto-pic  -minline-divide-min-latency @gol
617 -minline-divide-max-throughput  -mno-dwarf2-asm @gol
618 -mfixed-range=@var{register-range}}
619
620 @emph{D30V Options}
621 @gccoptlist{
622 -mextmem  -mextmemory  -monchip  -mno-asm-optimize  -masm-optimize @gol
623 -mbranch-cost=@var{n} -mcond-exec=@var{n}}
624
625 @emph{S/390 and zSeries Options}
626 @gccoptlist{
627 -mhard-float  -msoft-float  -mbackchain  -mno-backchain @gol
628 -msmall-exec  -mno-small-exec  -mmvcle -mno-mvcle @gol
629 -m64 -m31 -mdebug -mno-debug}
630
631 @emph{CRIS Options}
632 @gccoptlist{
633 -mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
634 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
635 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
636 -mstack-align -mdata-align -mconst-align @gol
637 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
638 -melf -maout -melinux -mlinux -sim -sim2}
639
640 @emph{PDP-11 Options}
641 @gccoptlist{
642 -mfpu  -msoft-float  -mac0  -mno-ac0  -m40  -m45  -m10 @gol
643 -mbcopy  -mbcopy-builtin  -mint32  -mno-int16 @gol
644 -mint16  -mno-int32  -mfloat32  -mno-float64 @gol
645 -mfloat64  -mno-float32  -mabshi  -mno-abshi @gol
646 -mbranch-expensive  -mbranch-cheap @gol
647 -msplit  -mno-split  -munix-asm  -mdec-asm}
648
649 @emph{Xstormy16 Options}
650 @gccoptlist{
651 -msim}
652
653 @emph{Xtensa Options}
654 @gccoptlist{
655 -mbig-endian -mlittle-endian @gol
656 -mdensity -mno-density @gol
657 -mmac16 -mno-mac16 @gol
658 -mmul16 -mno-mul16 @gol
659 -mmul32 -mno-mul32 @gol
660 -mnsa -mno-nsa @gol
661 -mminmax -mno-minmax @gol
662 -msext -mno-sext @gol
663 -mbooleans -mno-booleans @gol
664 -mhard-float -msoft-float @gol
665 -mfused-madd -mno-fused-madd @gol
666 -mserialize-volatile -mno-serialize-volatile @gol
667 -mtext-section-literals -mno-text-section-literals @gol
668 -mtarget-align -mno-target-align @gol
669 -mlongcalls -mno-longcalls}
670
671 @item Code Generation Options
672 @xref{Code Gen Options,,Options for Code Generation Conventions}.
673 @gccoptlist{
674 -fcall-saved-@var{reg}  -fcall-used-@var{reg} @gol
675 -ffixed-@var{reg} -fexceptions @gol
676 -fnon-call-exceptions  -funwind-tables @gol
677 -fasynchronous-unwind-tables @gol
678 -finhibit-size-directive  -finstrument-functions @gol
679 -fno-common  -fno-ident  -fno-gnu-linker @gol
680 -fpcc-struct-return  -fpic  -fPIC @gol
681 -freg-struct-return  -fshared-data  -fshort-enums @gol
682 -fshort-double  -fvolatile @gol
683 -fvolatile-global  -fvolatile-static @gol
684 -fverbose-asm  -fpack-struct  -fstack-check @gol
685 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
686 -fargument-alias  -fargument-noalias @gol
687 -fargument-noalias-global  -fleading-underscore -ftls-model=@var{model}}
688 @end table
689
690 @menu
691 * Overall Options::     Controlling the kind of output:
692                         an executable, object files, assembler files,
693                         or preprocessed source.
694 * C Dialect Options::   Controlling the variant of C language compiled.
695 * C++ Dialect Options:: Variations on C++.
696 * Objective-C Dialect Options:: Variations on Objective-C.
697 * Language Independent Options:: Controlling how diagnostics should be
698                         formatted.
699 * Warning Options::     How picky should the compiler be?
700 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
701 * Optimize Options::    How much optimization?
702 * Preprocessor Options:: Controlling header files and macro definitions.
703                          Also, getting dependency information for Make.
704 * Assembler Options::   Passing options to the assembler.
705 * Link Options::        Specifying libraries and so on.
706 * Directory Options::   Where to find header files and libraries.
707                         Where to find the compiler executable files.
708 * Spec Files::          How to pass switches to sub-processes.
709 * Target Options::      Running a cross-compiler, or an old version of GCC.
710 @end menu
711
712 @node Overall Options
713 @section Options Controlling the Kind of Output
714
715 Compilation can involve up to four stages: preprocessing, compilation
716 proper, assembly and linking, always in that order.  The first three
717 stages apply to an individual source file, and end by producing an
718 object file; linking combines all the object files (those newly
719 compiled, and those specified as input) into an executable file.
720
721 @cindex file name suffix
722 For any given input file, the file name suffix determines what kind of
723 compilation is done:
724
725 @table @gcctabopt
726 @item @var{file}.c
727 C source code which must be preprocessed.
728
729 @item @var{file}.i
730 C source code which should not be preprocessed.
731
732 @item @var{file}.ii
733 C++ source code which should not be preprocessed.
734
735 @item @var{file}.m
736 Objective-C source code.  Note that you must link with the library
737 @file{libobjc.a} to make an Objective-C program work.
738
739 @item @var{file}.mi
740 Objective-C source code which should not be preprocessed.
741
742 @item @var{file}.h
743 C header file (not to be compiled or linked).
744
745 @item @var{file}.cc
746 @itemx @var{file}.cp
747 @itemx @var{file}.cxx
748 @itemx @var{file}.cpp
749 @itemx @var{file}.c++
750 @itemx @var{file}.C
751 C++ source code which must be preprocessed.  Note that in @samp{.cxx},
752 the last two letters must both be literally @samp{x}.  Likewise,
753 @samp{.C} refers to a literal capital C@.
754
755 @item @var{file}.f
756 @itemx @var{file}.for
757 @itemx @var{file}.FOR
758 Fortran source code which should not be preprocessed.
759
760 @item @var{file}.F
761 @itemx @var{file}.fpp
762 @itemx @var{file}.FPP
763 Fortran source code which must be preprocessed (with the traditional
764 preprocessor).
765
766 @item @var{file}.r
767 Fortran source code which must be preprocessed with a RATFOR
768 preprocessor (not included with GCC)@.
769
770 @xref{Overall Options,,Options Controlling the Kind of Output, g77,
771 Using and Porting GNU Fortran}, for more details of the handling of
772 Fortran input files.
773
774 @c FIXME: Descriptions of Java file types.
775 @c @var{file}.java
776 @c @var{file}.class
777 @c @var{file}.zip
778 @c @var{file}.jar
779
780 @item @var{file}.ads
781 Ada source code file which contains a library unit declaration (a
782 declaration of a package, subprogram, or generic, or a generic
783 instantiation), or a library unit renaming declaration (a package,
784 generic, or subprogram renaming declaration).  Such files are also
785 called @dfn{specs}.
786
787 @itemx @var{file}.adb
788 Ada source code file containing a library unit body (a subprogram or
789 package body).  Such files are also called @dfn{bodies}.
790
791 @c GCC also knows about some suffixes for languages not yet included:
792 @c Pascal:
793 @c @var{file}.p
794 @c @var{file}.pas
795
796 @item @var{file}.s
797 Assembler code.
798
799 @item @var{file}.S
800 Assembler code which must be preprocessed.
801
802 @item @var{other}
803 An object file to be fed straight into linking.
804 Any file name with no recognized suffix is treated this way.
805 @end table
806
807 @opindex x
808 You can specify the input language explicitly with the @option{-x} option:
809
810 @table @gcctabopt
811 @item -x @var{language}
812 Specify explicitly the @var{language} for the following input files
813 (rather than letting the compiler choose a default based on the file
814 name suffix).  This option applies to all following input files until
815 the next @option{-x} option.  Possible values for @var{language} are:
816 @example
817 c  c-header  cpp-output
818 c++  c++-cpp-output
819 objective-c  objc-cpp-output
820 assembler  assembler-with-cpp
821 ada
822 f77  f77-cpp-input  ratfor
823 java
824 treelang
825 @end example
826
827 @item -x none
828 Turn off any specification of a language, so that subsequent files are
829 handled according to their file name suffixes (as they are if @option{-x}
830 has not been used at all).
831
832 @item -pass-exit-codes
833 @opindex pass-exit-codes
834 Normally the @command{gcc} program will exit with the code of 1 if any
835 phase of the compiler returns a non-success return code.  If you specify
836 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
837 numerically highest error produced by any phase that returned an error
838 indication.
839 @end table
840
841 If you only want some of the stages of compilation, you can use
842 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
843 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
844 @command{gcc} is to stop.  Note that some combinations (for example,
845 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
846
847 @table @gcctabopt
848 @item -c
849 @opindex c
850 Compile or assemble the source files, but do not link.  The linking
851 stage simply is not done.  The ultimate output is in the form of an
852 object file for each source file.
853
854 By default, the object file name for a source file is made by replacing
855 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
856
857 Unrecognized input files, not requiring compilation or assembly, are
858 ignored.
859
860 @item -S
861 @opindex S
862 Stop after the stage of compilation proper; do not assemble.  The output
863 is in the form of an assembler code file for each non-assembler input
864 file specified.
865
866 By default, the assembler file name for a source file is made by
867 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
868
869 Input files that don't require compilation are ignored.
870
871 @item -E
872 @opindex E
873 Stop after the preprocessing stage; do not run the compiler proper.  The
874 output is in the form of preprocessed source code, which is sent to the
875 standard output.
876
877 Input files which don't require preprocessing are ignored.
878
879 @cindex output file option
880 @item -o @var{file}
881 @opindex o
882 Place output in file @var{file}.  This applies regardless to whatever
883 sort of output is being produced, whether it be an executable file,
884 an object file, an assembler file or preprocessed C code.
885
886 Since only one output file can be specified, it does not make sense to
887 use @option{-o} when compiling more than one input file, unless you are
888 producing an executable file as output.
889
890 If @option{-o} is not specified, the default is to put an executable file
891 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
892 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
893 all preprocessed C source on standard output.
894
895 @item -v
896 @opindex v
897 Print (on standard error output) the commands executed to run the stages
898 of compilation.  Also print the version number of the compiler driver
899 program and of the preprocessor and the compiler proper.
900
901 @item -###
902 @opindex ###
903 Like @option{-v} except the commands are not executed and all command
904 arguments are quoted.  This is useful for shell scripts to capture the
905 driver-generated command lines.
906
907 @item -pipe
908 @opindex pipe
909 Use pipes rather than temporary files for communication between the
910 various stages of compilation.  This fails to work on some systems where
911 the assembler is unable to read from a pipe; but the GNU assembler has
912 no trouble.
913
914 @item --help
915 @opindex help
916 Print (on the standard output) a description of the command line options
917 understood by @command{gcc}.  If the @option{-v} option is also specified
918 then @option{--help} will also be passed on to the various processes
919 invoked by @command{gcc}, so that they can display the command line options
920 they accept.  If the @option{-W} option is also specified then command
921 line options which have no documentation associated with them will also
922 be displayed.
923
924 @item --target-help
925 @opindex target-help
926 Print (on the standard output) a description of target specific command
927 line options for each tool.
928 @end table
929
930 @node Invoking G++
931 @section Compiling C++ Programs
932
933 @cindex suffixes for C++ source
934 @cindex C++ source file suffixes
935 C++ source files conventionally use one of the suffixes @samp{.C},
936 @samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx};
937 preprocessed C++ files use the suffix @samp{.ii}.  GCC recognizes
938 files with these names and compiles them as C++ programs even if you
939 call the compiler the same way as for compiling C programs (usually with
940 the name @command{gcc}).
941
942 @findex g++
943 @findex c++
944 However, C++ programs often require class libraries as well as a
945 compiler that understands the C++ language---and under some
946 circumstances, you might want to compile programs from standard input,
947 or otherwise without a suffix that flags them as C++ programs.
948 @command{g++} is a program that calls GCC with the default language
949 set to C++, and automatically specifies linking against the C++
950 library.  On many systems, @command{g++} is also
951 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 @item 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 @cindex traditional C language
1160 @cindex C language, traditional
1161 @item -traditional
1162 @itemx -traditional-cpp
1163 @opindex traditional-cpp
1164 @opindex traditional
1165 Formerly, these options caused GCC to attempt to emulate a pre-standard
1166 C compiler.  They are now only supported with the @option{-E} switch.
1167 The preprocessor continues to support a pre-standard mode.  See the GNU
1168 CPP manual for details.
1169
1170 @item -fcond-mismatch
1171 @opindex fcond-mismatch
1172 Allow conditional expressions with mismatched types in the second and
1173 third arguments.  The value of such an expression is void.  This option
1174 is not supported for C++.
1175
1176 @item -funsigned-char
1177 @opindex funsigned-char
1178 Let the type @code{char} be unsigned, like @code{unsigned char}.
1179
1180 Each kind of machine has a default for what @code{char} should
1181 be.  It is either like @code{unsigned char} by default or like
1182 @code{signed char} by default.
1183
1184 Ideally, a portable program should always use @code{signed char} or
1185 @code{unsigned char} when it depends on the signedness of an object.
1186 But many programs have been written to use plain @code{char} and
1187 expect it to be signed, or expect it to be unsigned, depending on the
1188 machines they were written for.  This option, and its inverse, let you
1189 make such a program work with the opposite default.
1190
1191 The type @code{char} is always a distinct type from each of
1192 @code{signed char} or @code{unsigned char}, even though its behavior
1193 is always just like one of those two.
1194
1195 @item -fsigned-char
1196 @opindex fsigned-char
1197 Let the type @code{char} be signed, like @code{signed char}.
1198
1199 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1200 the negative form of @option{-funsigned-char}.  Likewise, the option
1201 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1202
1203 @item -fsigned-bitfields
1204 @itemx -funsigned-bitfields
1205 @itemx -fno-signed-bitfields
1206 @itemx -fno-unsigned-bitfields
1207 @opindex fsigned-bitfields
1208 @opindex funsigned-bitfields
1209 @opindex fno-signed-bitfields
1210 @opindex fno-unsigned-bitfields
1211 These options control whether a bit-field is signed or unsigned, when the
1212 declaration does not use either @code{signed} or @code{unsigned}.  By
1213 default, such a bit-field is signed, because this is consistent: the
1214 basic integer types such as @code{int} are signed types.
1215
1216 @item -fwritable-strings
1217 @opindex fwritable-strings
1218 Store string constants in the writable data segment and don't uniquize
1219 them.  This is for compatibility with old programs which assume they can
1220 write into string constants.
1221
1222 Writing into string constants is a very bad idea; ``constants'' should
1223 be constant.
1224
1225 @item -fshort-wchar
1226 @opindex fshort-wchar
1227 Override the underlying type for @samp{wchar_t} to be @samp{short
1228 unsigned int} instead of the default for the target.  This option is
1229 useful for building programs to run under WINE@.
1230 @end table
1231
1232 @node C++ Dialect Options
1233 @section Options Controlling C++ Dialect
1234
1235 @cindex compiler options, C++
1236 @cindex C++ options, command line
1237 @cindex options, C++
1238 This section describes the command-line options that are only meaningful
1239 for C++ programs; but you can also use most of the GNU compiler options
1240 regardless of what language your program is in.  For example, you
1241 might compile a file @code{firstClass.C} like this:
1242
1243 @example
1244 g++ -g -frepo -O -c firstClass.C
1245 @end example
1246
1247 @noindent
1248 In this example, only @option{-frepo} is an option meant
1249 only for C++ programs; you can use the other options with any
1250 language supported by GCC@.
1251
1252 Here is a list of options that are @emph{only} for compiling C++ programs:
1253
1254 @table @gcctabopt
1255 @item -fno-access-control
1256 @opindex fno-access-control
1257 Turn off all access checking.  This switch is mainly useful for working
1258 around bugs in the access control code.
1259
1260 @item -fcheck-new
1261 @opindex fcheck-new
1262 Check that the pointer returned by @code{operator new} is non-null
1263 before attempting to modify the storage allocated.  The current Working
1264 Paper requires that @code{operator new} never return a null pointer, so
1265 this check is normally unnecessary.
1266
1267 An alternative to using this option is to specify that your
1268 @code{operator new} does not throw any exceptions; if you declare it
1269 @samp{throw()}, G++ will check the return value.  See also @samp{new
1270 (nothrow)}.
1271
1272 @item -fconserve-space
1273 @opindex fconserve-space
1274 Put uninitialized or runtime-initialized global variables into the
1275 common segment, as C does.  This saves space in the executable at the
1276 cost of not diagnosing duplicate definitions.  If you compile with this
1277 flag and your program mysteriously crashes after @code{main()} has
1278 completed, you may have an object that is being destroyed twice because
1279 two definitions were merged.
1280
1281 This option is no longer useful on most targets, now that support has
1282 been added for putting variables into BSS without making them common.
1283
1284 @item -fno-const-strings
1285 @opindex fno-const-strings
1286 Give string constants type @code{char *} instead of type @code{const
1287 char *}.  By default, G++ uses type @code{const char *} as required by
1288 the standard.  Even if you use @option{-fno-const-strings}, you cannot
1289 actually modify the value of a string constant, unless you also use
1290 @option{-fwritable-strings}.
1291
1292 This option might be removed in a future release of G++.  For maximum
1293 portability, you should structure your code so that it works with
1294 string constants that have type @code{const char *}.
1295
1296 @item -fdollars-in-identifiers
1297 @opindex fdollars-in-identifiers
1298 Accept @samp{$} in identifiers.  You can also explicitly prohibit use of
1299 @samp{$} with the option @option{-fno-dollars-in-identifiers}.  (GNU C allows
1300 @samp{$} by default on most target systems, but there are a few exceptions.)
1301 Traditional C allowed the character @samp{$} to form part of
1302 identifiers.  However, ISO C and C++ forbid @samp{$} in identifiers.
1303
1304 @item -fno-elide-constructors
1305 @opindex fno-elide-constructors
1306 The C++ standard allows an implementation to omit creating a temporary
1307 which is only used to initialize another object of the same type.
1308 Specifying this option disables that optimization, and forces G++ to
1309 call the copy constructor in all cases.
1310
1311 @item -fno-enforce-eh-specs
1312 @opindex fno-enforce-eh-specs
1313 Don't check for violation of exception specifications at runtime.  This
1314 option violates the C++ standard, but may be useful for reducing code
1315 size in production builds, much like defining @samp{NDEBUG}.  The compiler
1316 will still optimize based on the exception specifications.
1317
1318 @item -fexternal-templates
1319 @opindex fexternal-templates
1320
1321 Cause @samp{#pragma interface} and @samp{implementation} to apply to
1322 template instantiation; template instances are emitted or not according
1323 to the location of the template definition.  @xref{Template
1324 Instantiation}, for more information.
1325
1326 This option is deprecated.
1327
1328 @item -falt-external-templates
1329 @opindex falt-external-templates
1330 Similar to @option{-fexternal-templates}, but template instances are
1331 emitted or not according to the place where they are first instantiated.
1332 @xref{Template Instantiation}, for more information.
1333
1334 This option is deprecated.
1335
1336 @item -ffor-scope
1337 @itemx -fno-for-scope
1338 @opindex ffor-scope
1339 @opindex fno-for-scope
1340 If @option{-ffor-scope} is specified, the scope of variables declared in
1341 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1342 as specified by the C++ standard.
1343 If @option{-fno-for-scope} is specified, the scope of variables declared in
1344 a @i{for-init-statement} extends to the end of the enclosing scope,
1345 as was the case in old versions of G++, and other (traditional)
1346 implementations of C++.
1347
1348 The default if neither flag is given to follow the standard,
1349 but to allow and give a warning for old-style code that would
1350 otherwise be invalid, or have different behavior.
1351
1352 @item -fno-gnu-keywords
1353 @opindex fno-gnu-keywords
1354 Do not recognize @code{typeof} as a keyword, so that code can use this
1355 word as an identifier.  You can use the keyword @code{__typeof__} instead.
1356 @option{-ansi} implies @option{-fno-gnu-keywords}.
1357
1358 @item -fno-implicit-templates
1359 @opindex fno-implicit-templates
1360 Never emit code for non-inline templates which are instantiated
1361 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1362 @xref{Template Instantiation}, for more information.
1363
1364 @item -fno-implicit-inline-templates
1365 @opindex fno-implicit-inline-templates
1366 Don't emit code for implicit instantiations of inline templates, either.
1367 The default is to handle inlines differently so that compiles with and
1368 without optimization will need the same set of explicit instantiations.
1369
1370 @item -fno-implement-inlines
1371 @opindex fno-implement-inlines
1372 To save space, do not emit out-of-line copies of inline functions
1373 controlled by @samp{#pragma implementation}.  This will cause linker
1374 errors if these functions are not inlined everywhere they are called.
1375
1376 @item -fms-extensions
1377 @opindex fms-extensions
1378 Disable pedantic warnings about constructs used in MFC, such as implicit
1379 int and getting a pointer to member function via non-standard syntax.
1380
1381 @item -fno-nonansi-builtins
1382 @opindex fno-nonansi-builtins
1383 Disable built-in declarations of functions that are not mandated by
1384 ANSI/ISO C@.  These include @code{ffs}, @code{alloca}, @code{_exit},
1385 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1386
1387 @item -fno-operator-names
1388 @opindex fno-operator-names
1389 Do not treat the operator name keywords @code{and}, @code{bitand},
1390 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1391 synonyms as keywords.
1392
1393 @item -fno-optional-diags
1394 @opindex fno-optional-diags
1395 Disable diagnostics that the standard says a compiler does not need to
1396 issue.  Currently, the only such diagnostic issued by G++ is the one for
1397 a name having multiple meanings within a class.
1398
1399 @item -fpermissive
1400 @opindex fpermissive
1401 Downgrade messages about nonconformant code from errors to warnings.  By
1402 default, G++ effectively sets @option{-pedantic-errors} without
1403 @option{-pedantic}; this option reverses that.  This behavior and this
1404 option are superseded by @option{-pedantic}, which works as it does for GNU C@.
1405
1406 @item -frepo
1407 @opindex frepo
1408 Enable automatic template instantiation at link time.  This option also
1409 implies @option{-fno-implicit-templates}.  @xref{Template
1410 Instantiation}, for more information.
1411
1412 @item -fno-rtti
1413 @opindex fno-rtti
1414 Disable generation of information about every class with virtual
1415 functions for use by the C++ runtime type identification features
1416 (@samp{dynamic_cast} and @samp{typeid}).  If you don't use those parts
1417 of the language, you can save some space by using this flag.  Note that
1418 exception handling uses the same information, but it will generate it as
1419 needed.
1420
1421 @item -fstats
1422 @opindex fstats
1423 Emit statistics about front-end processing at the end of the compilation.
1424 This information is generally only useful to the G++ development team.
1425
1426 @item -ftemplate-depth-@var{n}
1427 @opindex ftemplate-depth
1428 Set the maximum instantiation depth for template classes to @var{n}.
1429 A limit on the template instantiation depth is needed to detect
1430 endless recursions during template class instantiation.  ANSI/ISO C++
1431 conforming programs must not rely on a maximum depth greater than 17.
1432
1433 @item -fuse-cxa-atexit
1434 @opindex fuse-cxa-atexit
1435 Register destructors for objects with static storage duration with the
1436 @code{__cxa_atexit} function rather than the @code{atexit} function.
1437 This option is required for fully standards-compliant handling of static
1438 destructors, but will only work if your C library supports
1439 @code{__cxa_atexit}.
1440
1441 @item -fvtable-gc
1442 @opindex fvtable-gc
1443 Emit special relocations for vtables and virtual function references
1444 so that the linker can identify unused virtual functions and zero out
1445 vtable slots that refer to them.  This is most useful with
1446 @option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to
1447 also discard the functions themselves.
1448
1449 This optimization requires GNU as and GNU ld.  Not all systems support
1450 this option.  @option{-Wl,--gc-sections} is ignored without @option{-static}.
1451
1452 @item -fno-weak
1453 @opindex fno-weak
1454 Do not use weak symbol support, even if it is provided by the linker.
1455 By default, G++ will use weak symbols if they are available.  This
1456 option exists only for testing, and should not be used by end-users;
1457 it will result in inferior code and has no benefits.  This option may
1458 be removed in a future release of G++.
1459
1460 @item -nostdinc++
1461 @opindex nostdinc++
1462 Do not search for header files in the standard directories specific to
1463 C++, but do still search the other standard directories.  (This option
1464 is used when building the C++ library.)
1465 @end table
1466
1467 In addition, these optimization, warning, and code generation options
1468 have meanings only for C++ programs:
1469
1470 @table @gcctabopt
1471 @item -fno-default-inline
1472 @opindex fno-default-inline
1473 Do not assume @samp{inline} for functions defined inside a class scope.
1474 @xref{Optimize Options,,Options That Control Optimization}.  Note that these
1475 functions will have linkage like inline functions; they just won't be
1476 inlined by default.
1477
1478 @item -Wabi @r{(C++ only)}
1479 @opindex Wabi
1480 Warn when G++ generates code that is probably not compatible with the
1481 vendor-neutral C++ ABI.  Although an effort has been made to warn about
1482 all such cases, there are probably some cases that are not warned about, 
1483 even though G++ is generating incompatible code.  There may also be
1484 cases where warnings are emitted even though the code that is generated
1485 will be compatible.
1486
1487 You should rewrite your code to avoid these warnings if you are
1488 concerned about the fact that code generated by G++ may not be binary
1489 compatible with code generated by other compilers.
1490
1491 The known incompatibilites at this point include:
1492
1493 @itemize @bullet
1494
1495 @item
1496 Incorrect handling of tail-padding for bit-fields.  G++ may attempt to
1497 pack data into the same byte as a base class.  For example:
1498
1499 @smallexample
1500 struct A @{ virtual void f(); int f1 : 1; @};
1501 struct B : public A @{ int f2 : 1; @};
1502 @end smallexample
1503
1504 @noindent
1505 In this case, G++ will place @code{B::f2} into the same byte
1506 as@code{A::f1}; other compilers will not.  You can avoid this problem 
1507 by explicitly padding @code{A} so that its size is a multiple of the
1508 byte size on your platform; that will cause G++ and other compilers to
1509 layout @code{B} identically.
1510
1511 @item
1512 Incorrect handling of tail-padding for virtual bases.  G++ does not use
1513 tail padding when laying out virtual bases.  For example:
1514
1515 @smallexample
1516 struct A @{ virtual void f(); char c1; @};
1517 struct B @{ B(); char c2; @};
1518 struct C : public A, public virtual B @{@};
1519 @end smallexample
1520
1521 @noindent
1522 In this case, G++ will not place @code{B} into the tail-padding for
1523 @code{A}; other compilers will.  You can avoid this problem by
1524 explicitly padding @code{A} so that its size is a multiple of its
1525 alignment (ignoring virtual base classes); that will cause G++ and other
1526 compilers to layout @code{C} identically.
1527
1528 @end itemize
1529
1530 @item -Wctor-dtor-privacy @r{(C++ only)}
1531 @opindex Wctor-dtor-privacy
1532 Warn when a class seems unusable, because all the constructors or
1533 destructors in a class are private and the class has no friends or
1534 public static member functions.  This warning is enabled by default.
1535
1536 @item -Wnon-virtual-dtor @r{(C++ only)}
1537 @opindex Wnon-virtual-dtor
1538 Warn when a class declares a non-virtual destructor that should probably
1539 be virtual, because it looks like the class will be used polymorphically.
1540 This warning is enabled by @option{-Wall}.
1541
1542 @item -Wreorder @r{(C++ only)}
1543 @opindex Wreorder
1544 @cindex reordering, warning
1545 @cindex warning for reordering of member initializers
1546 Warn when the order of member initializers given in the code does not
1547 match the order in which they must be executed.  For instance:
1548
1549 @smallexample
1550 struct A @{
1551   int i;
1552   int j;
1553   A(): j (0), i (1) @{ @}
1554 @};
1555 @end smallexample
1556
1557 Here the compiler will warn that the member initializers for @samp{i}
1558 and @samp{j} will be rearranged to match the declaration order of the
1559 members.  This warning is enabled by @option{-Wall}.
1560 @end table
1561
1562 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1563
1564 @table @gcctabopt
1565 @item -Weffc++ @r{(C++ only)}
1566 @opindex Weffc++
1567 Warn about violations of the following style guidelines from Scott Meyers'
1568 @cite{Effective C++} book:
1569
1570 @itemize @bullet
1571 @item
1572 Item 11:  Define a copy constructor and an assignment operator for classes
1573 with dynamically allocated memory.
1574
1575 @item
1576 Item 12:  Prefer initialization to assignment in constructors.
1577
1578 @item
1579 Item 14:  Make destructors virtual in base classes.
1580
1581 @item
1582 Item 15:  Have @code{operator=} return a reference to @code{*this}.
1583
1584 @item
1585 Item 23:  Don't try to return a reference when you must return an object.
1586
1587 @end itemize
1588
1589 and about violations of the following style guidelines from Scott Meyers'
1590 @cite{More Effective C++} book:
1591
1592 @itemize @bullet
1593 @item
1594 Item 6:  Distinguish between prefix and postfix forms of increment and
1595 decrement operators.
1596
1597 @item
1598 Item 7:  Never overload @code{&&}, @code{||}, or @code{,}.
1599
1600 @end itemize
1601
1602 If you use this option, you should be aware that the standard library
1603 headers do not obey all of these guidelines; you can use @samp{grep -v}
1604 to filter out those warnings.
1605
1606 @item -Wno-deprecated @r{(C++ only)}
1607 @opindex Wno-deprecated
1608 Do not warn about usage of deprecated features.  @xref{Deprecated Features}.
1609
1610 @item -Wno-non-template-friend @r{(C++ only)}
1611 @opindex Wno-non-template-friend
1612 Disable warnings when non-templatized friend functions are declared
1613 within a template.  With the advent of explicit template specification
1614 support in G++, if the name of the friend is an unqualified-id (i.e.,
1615 @samp{friend foo(int)}), the C++ language specification demands that the
1616 friend declare or define an ordinary, nontemplate function.  (Section
1617 14.5.3).  Before G++ implemented explicit specification, unqualified-ids
1618 could be interpreted as a particular specialization of a templatized
1619 function.  Because this non-conforming behavior is no longer the default
1620 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1621 check existing code for potential trouble spots, and is on by default.
1622 This new compiler behavior can be turned off with
1623 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1624 but disables the helpful warning.
1625
1626 @item -Wold-style-cast @r{(C++ only)}
1627 @opindex Wold-style-cast
1628 Warn if an old-style (C-style) cast to a non-void type is used within
1629 a C++ program.  The new-style casts (@samp{static_cast},
1630 @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to
1631 unintended effects, and much easier to grep for.
1632
1633 @item -Woverloaded-virtual @r{(C++ only)}
1634 @opindex Woverloaded-virtual
1635 @cindex overloaded virtual fn, warning
1636 @cindex warning for overloaded virtual fn
1637 Warn when a function declaration hides virtual functions from a
1638 base class.  For example, in:
1639
1640 @smallexample
1641 struct A @{
1642   virtual void f();
1643 @};
1644
1645 struct B: public A @{
1646   void f(int);
1647 @};
1648 @end smallexample
1649
1650 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1651 like this:
1652
1653 @smallexample
1654 B* b;
1655 b->f();
1656 @end smallexample
1657
1658 will fail to compile.
1659
1660 @item -Wno-pmf-conversions @r{(C++ only)}
1661 @opindex Wno-pmf-conversions
1662 Disable the diagnostic for converting a bound pointer to member function
1663 to a plain pointer.
1664
1665 @item -Wsign-promo @r{(C++ only)}
1666 @opindex Wsign-promo
1667 Warn when overload resolution chooses a promotion from unsigned or
1668 enumeral type to a signed type over a conversion to an unsigned type of
1669 the same size.  Previous versions of G++ would try to preserve
1670 unsignedness, but the standard mandates the current behavior.
1671
1672 @item -Wsynth @r{(C++ only)}
1673 @opindex Wsynth
1674 @cindex warning for synthesized methods
1675 @cindex synthesized methods, warning
1676 Warn when G++'s synthesis behavior does not match that of cfront.  For
1677 instance:
1678
1679 @smallexample
1680 struct A @{
1681   operator int ();
1682   A& operator = (int);
1683 @};
1684
1685 main ()
1686 @{
1687   A a,b;
1688   a = b;
1689 @}
1690 @end smallexample
1691
1692 In this example, G++ will synthesize a default @samp{A& operator =
1693 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1694 @end table
1695
1696 @node Objective-C Dialect Options
1697 @section Options Controlling Objective-C Dialect
1698
1699 @cindex compiler options, Objective-C
1700 @cindex Objective-C options, command line
1701 @cindex options, Objective-C
1702 This section describes the command-line options that are only meaningful
1703 for Objective-C programs; but you can also use most of the GNU compiler
1704 options regardless of what language your program is in.  For example,
1705 you might compile a file @code{some_class.m} like this:
1706
1707 @example
1708 gcc -g -fgnu-runtime -O -c some_class.m
1709 @end example
1710
1711 @noindent
1712 In this example, only @option{-fgnu-runtime} is an option meant only for
1713 Objective-C programs; you can use the other options with any language
1714 supported by GCC@.
1715
1716 Here is a list of options that are @emph{only} for compiling Objective-C
1717 programs:
1718
1719 @table @gcctabopt
1720 @item -fconstant-string-class=@var{class-name}
1721 @opindex fconstant-string-class
1722 Use @var{class-name} as the name of the class to instantiate for each
1723 literal string specified with the syntax @code{@@"@dots{}"}.  The default
1724 class name is @code{NXConstantString}.
1725
1726 @item -fgnu-runtime
1727 @opindex fgnu-runtime
1728 Generate object code compatible with the standard GNU Objective-C
1729 runtime.  This is the default for most types of systems.
1730
1731 @item -fnext-runtime
1732 @opindex fnext-runtime
1733 Generate output compatible with the NeXT runtime.  This is the default
1734 for NeXT-based systems, including Darwin and Mac OS X@.
1735
1736 @item -gen-decls
1737 @opindex gen-decls
1738 Dump interface declarations for all classes seen in the source file to a
1739 file named @file{@var{sourcename}.decl}.
1740
1741 @item -Wno-protocol
1742 @opindex Wno-protocol
1743 Do not warn if methods required by a protocol are not implemented
1744 in the class adopting it.
1745
1746 @item -Wselector
1747 @opindex Wselector
1748 Warn if a selector has multiple methods of different types defined.
1749
1750 @c not documented because only avail via -Wp
1751 @c @item -print-objc-runtime-info
1752
1753 @end table
1754
1755 @node Language Independent Options
1756 @section Options to Control Diagnostic Messages Formatting
1757 @cindex options to control diagnostics formatting
1758 @cindex diagnostic messages
1759 @cindex message formatting
1760
1761 Traditionally, diagnostic messages have been formatted irrespective of
1762 the output device's aspect (e.g.@: its width, @dots{}).  The options described
1763 below can be used to control the diagnostic messages formatting
1764 algorithm, e.g.@: how many characters per line, how often source location
1765 information should be reported.  Right now, only the C++ front end can
1766 honor these options.  However it is expected, in the near future, that
1767 the remaining front ends would be able to digest them correctly.
1768
1769 @table @gcctabopt
1770 @item -fmessage-length=@var{n}
1771 @opindex fmessage-length
1772 Try to format error messages so that they fit on lines of about @var{n}
1773 characters.  The default is 72 characters for @command{g++} and 0 for the rest of
1774 the front ends supported by GCC@.  If @var{n} is zero, then no
1775 line-wrapping will be done; each error message will appear on a single
1776 line.
1777
1778 @opindex fdiagnostics-show-location
1779 @item -fdiagnostics-show-location=once
1780 Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
1781 reporter to emit @emph{once} source location information; that is, in
1782 case the message is too long to fit on a single physical line and has to
1783 be wrapped, the source location won't be emitted (as prefix) again,
1784 over and over, in subsequent continuation lines.  This is the default
1785 behavior.
1786
1787 @item -fdiagnostics-show-location=every-line
1788 Only meaningful in line-wrapping mode.  Instructs the diagnostic
1789 messages reporter to emit the same source location information (as
1790 prefix) for physical lines that result from the process of breaking
1791 a message which is too long to fit on a single line.
1792
1793 @end table
1794
1795 @node Warning Options
1796 @section Options to Request or Suppress Warnings
1797 @cindex options to control warnings
1798 @cindex warning messages
1799 @cindex messages, warning
1800 @cindex suppressing warnings
1801
1802 Warnings are diagnostic messages that report constructions which
1803 are not inherently erroneous but which are risky or suggest there
1804 may have been an error.
1805
1806 You can request many specific warnings with options beginning @samp{-W},
1807 for example @option{-Wimplicit} to request warnings on implicit
1808 declarations.  Each of these specific warning options also has a
1809 negative form beginning @samp{-Wno-} to turn off warnings;
1810 for example, @option{-Wno-implicit}.  This manual lists only one of the
1811 two forms, whichever is not the default.
1812
1813 The following options control the amount and kinds of warnings produced
1814 by GCC; for further, language-specific options also refer to
1815 @ref{C++ Dialect Options} and @ref{Objective-C Dialect Options}.
1816
1817 @table @gcctabopt
1818 @cindex syntax checking
1819 @item -fsyntax-only
1820 @opindex fsyntax-only
1821 Check the code for syntax errors, but don't do anything beyond that.
1822
1823 @item -pedantic
1824 @opindex pedantic
1825 Issue all the warnings demanded by strict ISO C and ISO C++;
1826 reject all programs that use forbidden extensions, and some other
1827 programs that do not follow ISO C and ISO C++.  For ISO C, follows the
1828 version of the ISO C standard specified by any @option{-std} option used.
1829
1830 Valid ISO C and ISO C++ programs should compile properly with or without
1831 this option (though a rare few will require @option{-ansi} or a
1832 @option{-std} option specifying the required version of ISO C)@.  However,
1833 without this option, certain GNU extensions and traditional C and C++
1834 features are supported as well.  With this option, they are rejected.
1835
1836 @option{-pedantic} does not cause warning messages for use of the
1837 alternate keywords whose names begin and end with @samp{__}.  Pedantic
1838 warnings are also disabled in the expression that follows
1839 @code{__extension__}.  However, only system header files should use
1840 these escape routes; application programs should avoid them.
1841 @xref{Alternate Keywords}.
1842
1843 Some users try to use @option{-pedantic} to check programs for strict ISO
1844 C conformance.  They soon find that it does not do quite what they want:
1845 it finds some non-ISO practices, but not all---only those for which
1846 ISO C @emph{requires} a diagnostic, and some others for which
1847 diagnostics have been added.
1848
1849 A feature to report any failure to conform to ISO C might be useful in
1850 some instances, but would require considerable additional work and would
1851 be quite different from @option{-pedantic}.  We don't have plans to
1852 support such a feature in the near future.
1853
1854 Where the standard specified with @option{-std} represents a GNU
1855 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
1856 corresponding @dfn{base standard}, the version of ISO C on which the GNU
1857 extended dialect is based.  Warnings from @option{-pedantic} are given
1858 where they are required by the base standard.  (It would not make sense
1859 for such warnings to be given only for features not in the specified GNU
1860 C dialect, since by definition the GNU dialects of C include all
1861 features the compiler supports with the given option, and there would be
1862 nothing to warn about.)
1863
1864 @item -pedantic-errors
1865 @opindex pedantic-errors
1866 Like @option{-pedantic}, except that errors are produced rather than
1867 warnings.
1868
1869 @item -w
1870 @opindex w
1871 Inhibit all warning messages.
1872
1873 @item -Wno-import
1874 @opindex Wno-import
1875 Inhibit warning messages about the use of @samp{#import}.
1876
1877 @item -Wchar-subscripts
1878 @opindex Wchar-subscripts
1879 Warn if an array subscript has type @code{char}.  This is a common cause
1880 of error, as programmers often forget that this type is signed on some
1881 machines.
1882
1883 @item -Wcomment
1884 @opindex Wcomment
1885 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1886 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1887
1888 @item -Wformat
1889 @opindex Wformat
1890 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1891 the arguments supplied have types appropriate to the format string
1892 specified, and that the conversions specified in the format string make
1893 sense.  This includes standard functions, and others specified by format
1894 attributes (@pxref{Function Attributes}), in the @code{printf},
1895 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
1896 not in the C standard) families.
1897
1898 The formats are checked against the format features supported by GNU
1899 libc version 2.2.  These include all ISO C90 and C99 features, as well
1900 as features from the Single Unix Specification and some BSD and GNU
1901 extensions.  Other library implementations may not support all these
1902 features; GCC does not support warning about features that go beyond a
1903 particular library's limitations.  However, if @option{-pedantic} is used
1904 with @option{-Wformat}, warnings will be given about format features not
1905 in the selected standard version (but not for @code{strfmon} formats,
1906 since those are not in any version of the C standard).  @xref{C Dialect
1907 Options,,Options Controlling C Dialect}.
1908
1909 Since @option{-Wformat} also checks for null format arguments for
1910 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
1911
1912 @option{-Wformat} is included in @option{-Wall}.  For more control over some
1913 aspects of format checking, the options @option{-Wno-format-y2k},
1914 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
1915 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
1916 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
1917
1918 @item -Wno-format-y2k
1919 @opindex Wno-format-y2k
1920 If @option{-Wformat} is specified, do not warn about @code{strftime}
1921 formats which may yield only a two-digit year.
1922
1923 @item -Wno-format-extra-args
1924 @opindex Wno-format-extra-args
1925 If @option{-Wformat} is specified, do not warn about excess arguments to a
1926 @code{printf} or @code{scanf} format function.  The C standard specifies
1927 that such arguments are ignored.
1928
1929 Where the unused arguments lie between used arguments that are
1930 specified with @samp{$} operand number specifications, normally
1931 warnings are still given, since the implementation could not know what
1932 type to pass to @code{va_arg} to skip the unused arguments.  However,
1933 in the case of @code{scanf} formats, this option will suppress the
1934 warning if the unused arguments are all pointers, since the Single
1935 Unix Specification says that such unused arguments are allowed.
1936
1937 @item -Wno-format-zero-length
1938 @opindex Wno-format-zero-length
1939 If @option{-Wformat} is specified, do not warn about zero-length formats.
1940 The C standard specifies that zero-length formats are allowed.
1941
1942 @item -Wformat-nonliteral
1943 @opindex Wformat-nonliteral
1944 If @option{-Wformat} is specified, also warn if the format string is not a
1945 string literal and so cannot be checked, unless the format function
1946 takes its format arguments as a @code{va_list}.
1947
1948 @item -Wformat-security
1949 @opindex Wformat-security
1950 If @option{-Wformat} is specified, also warn about uses of format
1951 functions that represent possible security problems.  At present, this
1952 warns about calls to @code{printf} and @code{scanf} functions where the
1953 format string is not a string literal and there are no format arguments,
1954 as in @code{printf (foo);}.  This may be a security hole if the format
1955 string came from untrusted input and contains @samp{%n}.  (This is
1956 currently a subset of what @option{-Wformat-nonliteral} warns about, but
1957 in future warnings may be added to @option{-Wformat-security} that are not
1958 included in @option{-Wformat-nonliteral}.)
1959
1960 @item -Wformat=2
1961 @opindex Wformat=2
1962 Enable @option{-Wformat} plus format checks not included in
1963 @option{-Wformat}.  Currently equivalent to @samp{-Wformat
1964 -Wformat-nonliteral -Wformat-security}.
1965
1966 @item -Wnonnull
1967 @opindex Wnonnull
1968 Enable warning about passing a null pointer for arguments marked as
1969 requiring a non-null value by the @code{nonnull} function attribute.
1970
1971 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}.  It
1972 can be disabled with the @option{-Wno-nonnull} option.
1973
1974 @item -Wimplicit-int
1975 @opindex Wimplicit-int
1976 Warn when a declaration does not specify a type.
1977
1978 @item -Wimplicit-function-declaration
1979 @itemx -Werror-implicit-function-declaration
1980 @opindex Wimplicit-function-declaration
1981 @opindex Werror-implicit-function-declaration
1982 Give a warning (or error) whenever a function is used before being
1983 declared.
1984
1985 @item -Wimplicit
1986 @opindex Wimplicit
1987 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
1988
1989 @item -Wmain
1990 @opindex Wmain
1991 Warn if the type of @samp{main} is suspicious.  @samp{main} should be a
1992 function with external linkage, returning int, taking either zero
1993 arguments, two, or three arguments of appropriate types.
1994
1995 @item -Wmissing-braces
1996 @opindex Wmissing-braces
1997 Warn if an aggregate or union initializer is not fully bracketed.  In
1998 the following example, the initializer for @samp{a} is not fully
1999 bracketed, but that for @samp{b} is fully bracketed.
2000
2001 @smallexample
2002 int a[2][2] = @{ 0, 1, 2, 3 @};
2003 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2004 @end smallexample
2005
2006 @item -Wparentheses
2007 @opindex Wparentheses
2008 Warn if parentheses are omitted in certain contexts, such
2009 as when there is an assignment in a context where a truth value
2010 is expected, or when operators are nested whose precedence people
2011 often get confused about.
2012
2013 Also warn about constructions where there may be confusion to which
2014 @code{if} statement an @code{else} branch belongs.  Here is an example of
2015 such a case:
2016
2017 @smallexample
2018 @group
2019 @{
2020   if (a)
2021     if (b)
2022       foo ();
2023   else
2024     bar ();
2025 @}
2026 @end group
2027 @end smallexample
2028
2029 In C, every @code{else} branch belongs to the innermost possible @code{if}
2030 statement, which in this example is @code{if (b)}.  This is often not
2031 what the programmer expected, as illustrated in the above example by
2032 indentation the programmer chose.  When there is the potential for this
2033 confusion, GCC will issue a warning when this flag is specified.
2034 To eliminate the warning, add explicit braces around the innermost
2035 @code{if} statement so there is no way the @code{else} could belong to
2036 the enclosing @code{if}.  The resulting code would look like this:
2037
2038 @smallexample
2039 @group
2040 @{
2041   if (a)
2042     @{
2043       if (b)
2044         foo ();
2045       else
2046         bar ();
2047     @}
2048 @}
2049 @end group
2050 @end smallexample
2051
2052 @item -Wsequence-point
2053 @opindex Wsequence-point
2054 Warn about code that may have undefined semantics because of violations
2055 of sequence point rules in the C standard.
2056
2057 The C standard defines the order in which expressions in a C program are
2058 evaluated in terms of @dfn{sequence points}, which represent a partial
2059 ordering between the execution of parts of the program: those executed
2060 before the sequence point, and those executed after it.  These occur
2061 after the evaluation of a full expression (one which is not part of a
2062 larger expression), after the evaluation of the first operand of a
2063 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2064 function is called (but after the evaluation of its arguments and the
2065 expression denoting the called function), and in certain other places.
2066 Other than as expressed by the sequence point rules, the order of
2067 evaluation of subexpressions of an expression is not specified.  All
2068 these rules describe only a partial order rather than a total order,
2069 since, for example, if two functions are called within one expression
2070 with no sequence point between them, the order in which the functions
2071 are called is not specified.  However, the standards committee have
2072 ruled that function calls do not overlap.
2073
2074 It is not specified when between sequence points modifications to the
2075 values of objects take effect.  Programs whose behavior depends on this
2076 have undefined behavior; the C standard specifies that ``Between the
2077 previous and next sequence point an object shall have its stored value
2078 modified at most once by the evaluation of an expression.  Furthermore,
2079 the prior value shall be read only to determine the value to be
2080 stored.''.  If a program breaks these rules, the results on any
2081 particular implementation are entirely unpredictable.
2082
2083 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2084 = b[n++]} and @code{a[i++] = i;}.  Some more complicated cases are not
2085 diagnosed by this option, and it may give an occasional false positive
2086 result, but in general it has been found fairly effective at detecting
2087 this sort of problem in programs.
2088
2089 The present implementation of this option only works for C programs.  A
2090 future implementation may also work for C++ programs.
2091
2092 The C standard is worded confusingly, therefore there is some debate
2093 over the precise meaning of the sequence point rules in subtle cases.
2094 Links to discussions of the problem, including proposed formal
2095 definitions, may be found on our readings page, at
2096 @w{@uref{http://gcc.gnu.org/readings.html}}.
2097
2098 @item -Wreturn-type
2099 @opindex Wreturn-type
2100 Warn whenever a function is defined with a return-type that defaults to
2101 @code{int}.  Also warn about any @code{return} statement with no
2102 return-value in a function whose return-type is not @code{void}.
2103
2104 For C++, a function without return type always produces a diagnostic
2105 message, even when @option{-Wno-return-type} is specified.  The only
2106 exceptions are @samp{main} and functions defined in system headers.
2107
2108 @item -Wswitch
2109 @opindex Wswitch
2110 Warn whenever a @code{switch} statement has an index of enumeral type
2111 and lacks a @code{case} for one or more of the named codes of that
2112 enumeration.  (The presence of a @code{default} label prevents this
2113 warning.)  @code{case} labels outside the enumeration range also
2114 provoke warnings when this option is used.
2115
2116 @item -Wswitch-default
2117 @opindex Wswitch-switch
2118 Warn whenever a @code{switch} statement does not have a @code{default}
2119 case.
2120
2121 @item -Wswitch-enum
2122 @opindex Wswitch-enum
2123 Warn whenever a @code{switch} statement has an index of enumeral type
2124 and lacks a @code{case} for one or more of the named codes of that
2125 enumeration.  @code{case} labels outside the enumeration range also
2126 provoke warnings when this option is used.
2127
2128 @item -Wtrigraphs
2129 @opindex Wtrigraphs
2130 Warn if any trigraphs are encountered that might change the meaning of
2131 the program (trigraphs within comments are not warned about).
2132
2133 @item -Wunused-function
2134 @opindex Wunused-function
2135 Warn whenever a static function is declared but not defined or a
2136 non\-inline static function is unused.
2137
2138 @item -Wunused-label
2139 @opindex Wunused-label
2140 Warn whenever a label is declared but not used.
2141
2142 To suppress this warning use the @samp{unused} attribute
2143 (@pxref{Variable Attributes}).
2144
2145 @item -Wunused-parameter
2146 @opindex Wunused-parameter
2147 Warn whenever a function parameter is unused aside from its declaration.
2148
2149 To suppress this warning use the @samp{unused} attribute
2150 (@pxref{Variable Attributes}).
2151
2152 @item -Wunused-variable
2153 @opindex Wunused-variable
2154 Warn whenever a local variable or non-constant static variable is unused
2155 aside from its declaration
2156
2157 To suppress this warning use the @samp{unused} attribute
2158 (@pxref{Variable Attributes}).
2159
2160 @item -Wunused-value
2161 @opindex Wunused-value
2162 Warn whenever a statement computes a result that is explicitly not used.
2163
2164 To suppress this warning cast the expression to @samp{void}.
2165
2166 @item -Wunused
2167 @opindex Wunused
2168 All the above @option{-Wunused} options combined.
2169
2170 In order to get a warning about an unused function parameter, you must
2171 either specify @samp{-W -Wunused} or separately specify
2172 @option{-Wunused-parameter}.
2173
2174 @item -Wuninitialized
2175 @opindex Wuninitialized
2176 Warn if an automatic variable is used without first being initialized or
2177 if a variable may be clobbered by a @code{setjmp} call.
2178
2179 These warnings are possible only in optimizing compilation,
2180 because they require data flow information that is computed only
2181 when optimizing.  If you don't specify @option{-O}, you simply won't
2182 get these warnings.
2183
2184 These warnings occur only for variables that are candidates for
2185 register allocation.  Therefore, they do not occur for a variable that
2186 is declared @code{volatile}, or whose address is taken, or whose size
2187 is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
2188 structures, unions or arrays, even when they are in registers.
2189
2190 Note that there may be no warning about a variable that is used only
2191 to compute a value that itself is never used, because such
2192 computations may be deleted by data flow analysis before the warnings
2193 are printed.
2194
2195 These warnings are made optional because GCC is not smart
2196 enough to see all the reasons why the code might be correct
2197 despite appearing to have an error.  Here is one example of how
2198 this can happen:
2199
2200 @smallexample
2201 @group
2202 @{
2203   int x;
2204   switch (y)
2205     @{
2206     case 1: x = 1;
2207       break;
2208     case 2: x = 4;
2209       break;
2210     case 3: x = 5;
2211     @}
2212   foo (x);
2213 @}
2214 @end group
2215 @end smallexample
2216
2217 @noindent
2218 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2219 always initialized, but GCC doesn't know this.  Here is
2220 another common case:
2221
2222 @smallexample
2223 @{
2224   int save_y;
2225   if (change_y) save_y = y, y = new_y;
2226   @dots{}
2227   if (change_y) y = save_y;
2228 @}
2229 @end smallexample
2230
2231 @noindent
2232 This has no bug because @code{save_y} is used only if it is set.
2233
2234 @cindex @code{longjmp} warnings
2235 This option also warns when a non-volatile automatic variable might be
2236 changed by a call to @code{longjmp}.  These warnings as well are possible
2237 only in optimizing compilation.
2238
2239 The compiler sees only the calls to @code{setjmp}.  It cannot know
2240 where @code{longjmp} will be called; in fact, a signal handler could
2241 call it at any point in the code.  As a result, you may get a warning
2242 even when there is in fact no problem because @code{longjmp} cannot
2243 in fact be called at the place which would cause a problem.
2244
2245 Some spurious warnings can be avoided if you declare all the functions
2246 you use that never return as @code{noreturn}.  @xref{Function
2247 Attributes}.
2248
2249 @item -Wunknown-pragmas
2250 @opindex Wunknown-pragmas
2251 @cindex warning for unknown pragmas
2252 @cindex unknown pragmas, warning
2253 @cindex pragmas, warning of unknown
2254 Warn when a #pragma directive is encountered which is not understood by
2255 GCC@.  If this command line option is used, warnings will even be issued
2256 for unknown pragmas in system header files.  This is not the case if
2257 the warnings were only enabled by the @option{-Wall} command line option.
2258
2259 @item -Wall
2260 @opindex Wall
2261 All of the above @samp{-W} options combined.  This enables all the
2262 warnings about constructions that some users consider questionable, and
2263 that are easy to avoid (or modify to prevent the warning), even in
2264 conjunction with macros.  This also enables some language-specific
2265 warnings described in @ref{C++ Dialect Options} and
2266 @ref{Objective-C Dialect Options}.
2267 @end table
2268
2269 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2270 Some of them warn about constructions that users generally do not
2271 consider questionable, but which occasionally you might wish to check
2272 for; others warn about constructions that are necessary or hard to avoid
2273 in some cases, and there is no simple way to modify the code to suppress
2274 the warning.
2275
2276 @table @gcctabopt
2277 @item -W
2278 @opindex W
2279 Print extra warning messages for these events:
2280
2281 @itemize @bullet
2282 @item
2283 A function can return either with or without a value.  (Falling
2284 off the end of the function body is considered returning without
2285 a value.)  For example, this function would evoke such a
2286 warning:
2287
2288 @smallexample
2289 @group
2290 foo (a)
2291 @{
2292   if (a > 0)
2293     return a;
2294 @}
2295 @end group
2296 @end smallexample
2297
2298 @item
2299 An expression-statement or the left-hand side of a comma expression
2300 contains no side effects.
2301 To suppress the warning, cast the unused expression to void.
2302 For example, an expression such as @samp{x[i,j]} will cause a warning,
2303 but @samp{x[(void)i,j]} will not.
2304
2305 @item
2306 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
2307
2308 @item
2309 A comparison like @samp{x<=y<=z} appears; this is equivalent to
2310 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
2311 that of ordinary mathematical notation.
2312
2313 @item
2314 Storage-class specifiers like @code{static} are not the first things in
2315 a declaration.  According to the C Standard, this usage is obsolescent.
2316
2317 @item
2318 The return type of a function has a type qualifier such as @code{const}.
2319 Such a type qualifier has no effect, since the value returned by a
2320 function is not an lvalue.  (But don't warn about the GNU extension of
2321 @code{volatile void} return types.  That extension will be warned about
2322 if @option{-pedantic} is specified.)
2323
2324 @item
2325 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2326 arguments.
2327
2328 @item
2329 A comparison between signed and unsigned values could produce an
2330 incorrect result when the signed value is converted to unsigned.
2331 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2332
2333 @item
2334 An aggregate has a partly bracketed initializer.
2335 For example, the following code would evoke such a warning,
2336 because braces are missing around the initializer for @code{x.h}:
2337
2338 @smallexample
2339 struct s @{ int f, g; @};
2340 struct t @{ struct s h; int i; @};
2341 struct t x = @{ 1, 2, 3 @};
2342 @end smallexample
2343
2344 @item
2345 An aggregate has an initializer which does not initialize all members.
2346 For example, the following code would cause such a warning, because
2347 @code{x.h} would be implicitly initialized to zero:
2348
2349 @smallexample
2350 struct s @{ int f, g, h; @};
2351 struct s x = @{ 3, 4 @};
2352 @end smallexample
2353 @end itemize
2354
2355 @item -Wno-div-by-zero
2356 @opindex Wno-div-by-zero
2357 @opindex Wdiv-by-zero
2358 Do not warn about compile-time integer division by zero.  Floating point
2359 division by zero is not warned about, as it can be a legitimate way of
2360 obtaining infinities and NaNs.
2361
2362 @item -Wsystem-headers
2363 @opindex Wsystem-headers
2364 @cindex warnings from system headers
2365 @cindex system headers, warnings from
2366 Print warning messages for constructs found in system header files.
2367 Warnings from system headers are normally suppressed, on the assumption
2368 that they usually do not indicate real problems and would only make the
2369 compiler output harder to read.  Using this command line option tells
2370 GCC to emit warnings from system headers as if they occurred in user
2371 code.  However, note that using @option{-Wall} in conjunction with this
2372 option will @emph{not} warn about unknown pragmas in system
2373 headers---for that, @option{-Wunknown-pragmas} must also be used.
2374
2375 @item -Wfloat-equal
2376 @opindex Wfloat-equal
2377 Warn if floating point values are used in equality comparisons.
2378
2379 The idea behind this is that sometimes it is convenient (for the
2380 programmer) to consider floating-point values as approximations to
2381 infinitely precise real numbers.  If you are doing this, then you need
2382 to compute (by analysing the code, or in some other way) the maximum or
2383 likely maximum error that the computation introduces, and allow for it
2384 when performing comparisons (and when producing output, but that's a
2385 different problem).  In particular, instead of testing for equality, you
2386 would check to see whether the two values have ranges that overlap; and
2387 this is done with the relational operators, so equality comparisons are
2388 probably mistaken.
2389
2390 @item -Wtraditional @r{(C only)}
2391 @opindex Wtraditional
2392 Warn about certain constructs that behave differently in traditional and
2393 ISO C@.  Also warn about ISO C constructs that have no traditional C
2394 equivalent, and/or problematic constructs which should be avoided.
2395
2396 @itemize @bullet
2397 @item
2398 Macro parameters that appear within string literals in the macro body.
2399 In traditional C macro replacement takes place within string literals,
2400 but does not in ISO C@.
2401
2402 @item
2403 In traditional C, some preprocessor directives did not exist.
2404 Traditional preprocessors would only consider a line to be a directive
2405 if the @samp{#} appeared in column 1 on the line.  Therefore
2406 @option{-Wtraditional} warns about directives that traditional C
2407 understands but would ignore because the @samp{#} does not appear as the
2408 first character on the line.  It also suggests you hide directives like
2409 @samp{#pragma} not understood by traditional C by indenting them.  Some
2410 traditional implementations would not recognize @samp{#elif}, so it
2411 suggests avoiding it altogether.
2412
2413 @item
2414 A function-like macro that appears without arguments.
2415
2416 @item
2417 The unary plus operator.
2418
2419 @item
2420 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2421 constant suffixes.  (Traditional C does support the @samp{L} suffix on integer
2422 constants.)  Note, these suffixes appear in macros defined in the system
2423 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2424 Use of these macros in user code might normally lead to spurious
2425 warnings, however gcc's integrated preprocessor has enough context to
2426 avoid warning in these cases.
2427
2428 @item
2429 A function declared external in one block and then used after the end of
2430 the block.
2431
2432 @item
2433 A @code{switch} statement has an operand of type @code{long}.
2434
2435 @item
2436 A non-@code{static} function declaration follows a @code{static} one.
2437 This construct is not accepted by some traditional C compilers.
2438
2439 @item
2440 The ISO type of an integer constant has a different width or
2441 signedness from its traditional type.  This warning is only issued if
2442 the base of the constant is ten.  I.e.@: hexadecimal or octal values, which
2443 typically represent bit patterns, are not warned about.
2444
2445 @item
2446 Usage of ISO string concatenation is detected.
2447
2448 @item
2449 Initialization of automatic aggregates.
2450
2451 @item
2452 Identifier conflicts with labels.  Traditional C lacks a separate
2453 namespace for labels.
2454
2455 @item
2456 Initialization of unions.  If the initializer is zero, the warning is
2457 omitted.  This is done under the assumption that the zero initializer in
2458 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2459 initializer warnings and relies on default initialization to zero in the
2460 traditional C case.
2461
2462 @item
2463 Conversions by prototypes between fixed/floating point values and vice
2464 versa.  The absence of these prototypes when compiling with traditional
2465 C would cause serious problems.  This is a subset of the possible
2466 conversion warnings, for the full set use @option{-Wconversion}.
2467
2468 @item
2469 Use of ISO C style function definitions.  This warning intentionally is
2470 @emph{not} issued for prototype declarations or variadic functions
2471 because these ISO C features will appear in your code when using
2472 libiberty's traditional C compatibility macros, @code{PARAMS} and
2473 @code{VPARAMS}.  This warning is also bypassed for nested functions
2474 because that feature is already a gcc extension and thus not relevant to
2475 traditional C compatibility.
2476 @end itemize
2477
2478 @item -Wundef
2479 @opindex Wundef
2480 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2481
2482 @item -Wendif-labels
2483 @opindex Wendif-labels
2484 Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2485
2486 @item -Wshadow
2487 @opindex Wshadow
2488 Warn whenever a local variable shadows another local variable, parameter or
2489 global variable or whenever a built-in function is shadowed.
2490
2491 @item -Wlarger-than-@var{len}
2492 @opindex Wlarger-than
2493 Warn whenever an object of larger than @var{len} bytes is defined.
2494
2495 @item -Wpointer-arith
2496 @opindex Wpointer-arith
2497 Warn about anything that depends on the ``size of'' a function type or
2498 of @code{void}.  GNU C assigns these types a size of 1, for
2499 convenience in calculations with @code{void *} pointers and pointers
2500 to functions.
2501
2502 @item -Wbad-function-cast @r{(C only)}
2503 @opindex Wbad-function-cast
2504 Warn whenever a function call is cast to a non-matching type.
2505 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2506
2507 @item -Wcast-qual
2508 @opindex Wcast-qual
2509 Warn whenever a pointer is cast so as to remove a type qualifier from
2510 the target type.  For example, warn if a @code{const char *} is cast
2511 to an ordinary @code{char *}.
2512
2513 @item -Wcast-align
2514 @opindex Wcast-align
2515 Warn whenever a pointer is cast such that the required alignment of the
2516 target is increased.  For example, warn if a @code{char *} is cast to
2517 an @code{int *} on machines where integers can only be accessed at
2518 two- or four-byte boundaries.
2519
2520 @item -Wwrite-strings
2521 @opindex Wwrite-strings
2522 When compiling C, give string constants the type @code{const
2523 char[@var{length}]} so that
2524 copying the address of one into a non-@code{const} @code{char *}
2525 pointer will get a warning; when compiling C++, warn about the
2526 deprecated conversion from string constants to @code{char *}.
2527 These warnings will help you find at
2528 compile time code that can try to write into a string constant, but
2529 only if you have been very careful about using @code{const} in
2530 declarations and prototypes.  Otherwise, it will just be a nuisance;
2531 this is why we did not make @option{-Wall} request these warnings.
2532
2533 @item -Wconversion
2534 @opindex Wconversion
2535 Warn if a prototype causes a type conversion that is different from what
2536 would happen to the same argument in the absence of a prototype.  This
2537 includes conversions of fixed point to floating and vice versa, and
2538 conversions changing the width or signedness of a fixed point argument
2539 except when the same as the default promotion.
2540
2541 Also, warn if a negative integer constant expression is implicitly
2542 converted to an unsigned type.  For example, warn about the assignment
2543 @code{x = -1} if @code{x} is unsigned.  But do not warn about explicit
2544 casts like @code{(unsigned) -1}.
2545
2546 @item -Wsign-compare
2547 @opindex Wsign-compare
2548 @cindex warning for comparison of signed and unsigned values
2549 @cindex comparison of signed and unsigned values, warning
2550 @cindex signed and unsigned values, comparison warning
2551 Warn when a comparison between signed and unsigned values could produce
2552 an incorrect result when the signed value is converted to unsigned.
2553 This warning is also enabled by @option{-W}; to get the other warnings
2554 of @option{-W} without this warning, use @samp{-W -Wno-sign-compare}.
2555
2556 @item -Waggregate-return
2557 @opindex Waggregate-return
2558 Warn if any functions that return structures or unions are defined or
2559 called.  (In languages where you can return an array, this also elicits
2560 a warning.)
2561
2562 @item -Wstrict-prototypes @r{(C only)}
2563 @opindex Wstrict-prototypes
2564 Warn if a function is declared or defined without specifying the
2565 argument types.  (An old-style function definition is permitted without
2566 a warning if preceded by a declaration which specifies the argument
2567 types.)
2568
2569 @item -Wmissing-prototypes @r{(C only)}
2570 @opindex Wmissing-prototypes
2571 Warn if a global function is defined without a previous prototype
2572 declaration.  This warning is issued even if the definition itself
2573 provides a prototype.  The aim is to detect global functions that fail
2574 to be declared in header files.
2575
2576 @item -Wmissing-declarations
2577 @opindex Wmissing-declarations
2578 Warn if a global function is defined without a previous declaration.
2579 Do so even if the definition itself provides a prototype.
2580 Use this option to detect global functions that are not declared in
2581 header files.
2582
2583 @item -Wmissing-noreturn
2584 @opindex Wmissing-noreturn
2585 Warn about functions which might be candidates for attribute @code{noreturn}.
2586 Note these are only possible candidates, not absolute ones.  Care should
2587 be taken to manually verify functions actually do not ever return before
2588 adding the @code{noreturn} attribute, otherwise subtle code generation
2589 bugs could be introduced.  You will not get a warning for @code{main} in
2590 hosted C environments.
2591
2592 @item -Wmissing-format-attribute
2593 @opindex Wmissing-format-attribute
2594 @opindex Wformat
2595 If @option{-Wformat} is enabled, also warn about functions which might be
2596 candidates for @code{format} attributes.  Note these are only possible
2597 candidates, not absolute ones.  GCC will guess that @code{format}
2598 attributes might be appropriate for any function that calls a function
2599 like @code{vprintf} or @code{vscanf}, but this might not always be the
2600 case, and some functions for which @code{format} attributes are
2601 appropriate may not be detected.  This option has no effect unless
2602 @option{-Wformat} is enabled (possibly by @option{-Wall}).
2603
2604 @item -Wno-multichar
2605 @opindex Wno-multichar
2606 @opindex Wmultichar
2607 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
2608 Usually they indicate a typo in the user's code, as they have
2609 implementation-defined values, and should not be used in portable code.
2610
2611 @item -Wno-deprecated-declarations
2612 @opindex Wno-deprecated-declarations
2613 Do not warn about uses of functions, variables, and types marked as
2614 deprecated by using the @code{deprecated} attribute.
2615 (@pxref{Function Attributes}, @pxref{Variable Attributes},
2616 @pxref{Type Attributes}.)
2617
2618 @item -Wpacked
2619 @opindex Wpacked
2620 Warn if a structure is given the packed attribute, but the packed
2621 attribute has no effect on the layout or size of the structure.
2622 Such structures may be mis-aligned for little benefit.  For
2623 instance, in this code, the variable @code{f.x} in @code{struct bar}
2624 will be misaligned even though @code{struct bar} does not itself
2625 have the packed attribute:
2626
2627 @smallexample
2628 @group
2629 struct foo @{
2630   int x;
2631   char a, b, c, d;
2632 @} __attribute__((packed));
2633 struct bar @{
2634   char z;
2635   struct foo f;
2636 @};
2637 @end group
2638 @end smallexample
2639
2640 @item -Wpadded
2641 @opindex Wpadded
2642 Warn if padding is included in a structure, either to align an element
2643 of the structure or to align the whole structure.  Sometimes when this
2644 happens it is possible to rearrange the fields of the structure to
2645 reduce the padding and so make the structure smaller.
2646
2647 @item -Wredundant-decls
2648 @opindex Wredundant-decls
2649 Warn if anything is declared more than once in the same scope, even in
2650 cases where multiple declaration is valid and changes nothing.
2651
2652 @item -Wnested-externs @r{(C only)}
2653 @opindex Wnested-externs
2654 Warn if an @code{extern} declaration is encountered within a function.
2655
2656 @item -Wunreachable-code
2657 @opindex Wunreachable-code
2658 Warn if the compiler detects that code will never be executed.
2659
2660 This option is intended to warn when the compiler detects that at
2661 least a whole line of source code will never be executed, because
2662 some condition is never satisfied or because it is after a
2663 procedure that never returns.
2664
2665 It is possible for this option to produce a warning even though there
2666 are circumstances under which part of the affected line can be executed,
2667 so care should be taken when removing apparently-unreachable code.
2668
2669 For instance, when a function is inlined, a warning may mean that the
2670 line is unreachable in only one inlined copy of the function.
2671
2672 This option is not made part of @option{-Wall} because in a debugging
2673 version of a program there is often substantial code which checks
2674 correct functioning of the program and is, hopefully, unreachable
2675 because the program does work.  Another common use of unreachable
2676 code is to provide behavior which is selectable at compile-time.
2677
2678 @item -Winline
2679 @opindex Winline
2680 Warn if a function can not be inlined and it was declared as inline.
2681
2682 @item -Wlong-long
2683 @opindex Wlong-long
2684 @opindex Wno-long-long
2685 Warn if @samp{long long} type is used.  This is default.  To inhibit
2686 the warning messages, use @option{-Wno-long-long}.  Flags
2687 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
2688 only when @option{-pedantic} flag is used.
2689
2690 @item -Wdisabled-optimization
2691 @opindex Wdisabled-optimization
2692 Warn if a requested optimization pass is disabled.  This warning does
2693 not generally indicate that there is anything wrong with your code; it
2694 merely indicates that GCC's optimizers were unable to handle the code
2695 effectively.  Often, the problem is that your code is too big or too
2696 complex; GCC will refuse to optimize programs when the optimization
2697 itself is likely to take inordinate amounts of time.
2698
2699 @item -Werror
2700 @opindex Werror
2701 Make all warnings into errors.
2702 @end table
2703
2704 @node Debugging Options
2705 @section Options for Debugging Your Program or GCC
2706 @cindex options, debugging
2707 @cindex debugging information options
2708
2709 GCC has various special options that are used for debugging
2710 either your program or GCC:
2711
2712 @table @gcctabopt
2713 @item -g
2714 @opindex g
2715 Produce debugging information in the operating system's native format
2716 (stabs, COFF, XCOFF, or DWARF)@.  GDB can work with this debugging
2717 information.
2718
2719 On most systems that use stabs format, @option{-g} enables use of extra
2720 debugging information that only GDB can use; this extra information
2721 makes debugging work better in GDB but will probably make other debuggers
2722 crash or
2723 refuse to read the program.  If you want to control for certain whether
2724 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
2725 @option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1},
2726 or @option{-gvms} (see below).
2727
2728 Unlike most other C compilers, GCC allows you to use @option{-g} with
2729 @option{-O}.  The shortcuts taken by optimized code may occasionally
2730 produce surprising results: some variables you declared may not exist
2731 at all; flow of control may briefly move where you did not expect it;
2732 some statements may not be executed because they compute constant
2733 results or their values were already at hand; some statements may
2734 execute in different places because they were moved out of loops.
2735
2736 Nevertheless it proves possible to debug optimized output.  This makes
2737 it reasonable to use the optimizer for programs that might have bugs.
2738
2739 The following options are useful when GCC is generated with the
2740 capability for more than one debugging format.
2741
2742 @item -ggdb
2743 @opindex ggdb
2744 Produce debugging information for use by GDB@.  This means to use the
2745 most expressive format available (DWARF 2, stabs, or the native format
2746 if neither of those are supported), including GDB extensions if at all
2747 possible.
2748
2749 @item -gstabs
2750 @opindex gstabs
2751 Produce debugging information in stabs format (if that is supported),
2752 without GDB extensions.  This is the format used by DBX on most BSD
2753 systems.  On MIPS, Alpha and System V Release 4 systems this option
2754 produces stabs debugging output which is not understood by DBX or SDB@.
2755 On System V Release 4 systems this option requires the GNU assembler.
2756
2757 @item -gstabs+
2758 @opindex gstabs+
2759 Produce debugging information in stabs format (if that is supported),
2760 using GNU extensions understood only by the GNU debugger (GDB)@.  The
2761 use of these extensions is likely to make other debuggers crash or
2762 refuse to read the program.
2763
2764 @item -gcoff
2765 @opindex gcoff
2766 Produce debugging information in COFF format (if that is supported).
2767 This is the format used by SDB on most System V systems prior to
2768 System V Release 4.
2769
2770 @item -gxcoff
2771 @opindex gxcoff
2772 Produce debugging information in XCOFF format (if that is supported).
2773 This is the format used by the DBX debugger on IBM RS/6000 systems.
2774
2775 @item -gxcoff+
2776 @opindex gxcoff+
2777 Produce debugging information in XCOFF format (if that is supported),
2778 using GNU extensions understood only by the GNU debugger (GDB)@.  The
2779 use of these extensions is likely to make other debuggers crash or
2780 refuse to read the program, and may cause assemblers other than the GNU
2781 assembler (GAS) to fail with an error.
2782
2783 @item -gdwarf
2784 @opindex gdwarf
2785 Produce debugging information in DWARF version 1 format (if that is
2786 supported).  This is the format used by SDB on most System V Release 4
2787 systems.
2788
2789 This option is deprecated.
2790
2791 @item -gdwarf+
2792 @opindex gdwarf+
2793 Produce debugging information in DWARF version 1 format (if that is
2794 supported), using GNU extensions understood only by the GNU debugger
2795 (GDB)@.  The use of these extensions is likely to make other debuggers
2796 crash or refuse to read the program.
2797
2798 This option is deprecated.
2799
2800 @item -gdwarf-2
2801 @opindex gdwarf-2
2802 Produce debugging information in DWARF version 2 format (if that is
2803 supported).  This is the format used by DBX on IRIX 6.
2804
2805 @item -gvms
2806 @opindex gvms
2807 Produce debugging information in VMS debug format (if that is
2808 supported).  This is the format used by DEBUG on VMS systems.
2809
2810 @item -g@var{level}
2811 @itemx -ggdb@var{level}
2812 @itemx -gstabs@var{level}
2813 @itemx -gcoff@var{level}
2814 @itemx -gxcoff@var{level}
2815 @itemx -gvms@var{level}
2816 Request debugging information and also use @var{level} to specify how
2817 much information.  The default level is 2.
2818
2819 Level 1 produces minimal information, enough for making backtraces in
2820 parts of the program that you don't plan to debug.  This includes
2821 descriptions of functions and external variables, but no information
2822 about local variables and no line numbers.
2823
2824 Level 3 includes extra information, such as all the macro definitions
2825 present in the program.  Some debuggers support macro expansion when
2826 you use @option{-g3}.
2827
2828 Note that in order to avoid confusion between DWARF1 debug level 2,
2829 and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept
2830 a concatenated debug level.  Instead use an additional @option{-g@var{level}}
2831 option to change the debug level for DWARF1 or DWARF2.
2832
2833 @cindex @code{prof}
2834 @item -p
2835 @opindex p
2836 Generate extra code to write profile information suitable for the
2837 analysis program @code{prof}.  You must use this option when compiling
2838 the source files you want data about, and you must also use it when
2839 linking.
2840
2841 @cindex @code{gprof}
2842 @item -pg
2843 @opindex pg
2844 Generate extra code to write profile information suitable for the
2845 analysis program @code{gprof}.  You must use this option when compiling
2846 the source files you want data about, and you must also use it when
2847 linking.
2848
2849 @item -Q
2850 @opindex Q
2851 Makes the compiler print out each function name as it is compiled, and
2852 print some statistics about each pass when it finishes.
2853
2854 @item -ftime-report
2855 @opindex ftime-report
2856 Makes the compiler print some statistics about the time consumed by each
2857 pass when it finishes.
2858
2859 @item -fmem-report
2860 @opindex fmem-report
2861 Makes the compiler print some statistics about permanent memory
2862 allocation when it finishes.
2863
2864 @item -fprofile-arcs
2865 @opindex fprofile-arcs
2866 Instrument @dfn{arcs} during compilation to generate coverage data or
2867 for profile-directed block ordering.  During execution the program
2868 records how many times each branch is executed and how many times it is
2869 taken.  When the compiled program exits it saves this data to a file
2870 called @file{@var{auxname}.da} for each source file.  @var{auxname} is
2871 generated from the name of the output file, if explicitly specified and
2872 it is not the final executable, otherwise it is the basename of the
2873 source file. In both cases any suffix is removed (e.g.  @file{foo.da}
2874 for input file @file{dir/foo.c}, or @file{dir/foo.da} for output file
2875 specified as @option{-o dir/foo.o}).
2876
2877 For profile-directed block ordering, compile the program with
2878 @option{-fprofile-arcs} plus optimization and code generation options,
2879 generate the arc profile information by running the program on a
2880 selected workload, and then compile the program again with the same
2881 optimization and code generation options plus
2882 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
2883 Control Optimization}).
2884
2885 The other use of @option{-fprofile-arcs} is for use with @code{gcov},
2886 when it is used with the @option{-ftest-coverage} option.
2887
2888 With @option{-fprofile-arcs}, for each function of your program GCC
2889 creates a program flow graph, then finds a spanning tree for the graph.
2890 Only arcs that are not on the spanning tree have to be instrumented: the
2891 compiler adds code to count the number of times that these arcs are
2892 executed.  When an arc is the only exit or only entrance to a block, the
2893 instrumentation code can be added to the block; otherwise, a new basic
2894 block must be created to hold the instrumentation code.
2895
2896 @need 2000
2897 @item -ftest-coverage
2898 @opindex ftest-coverage
2899 Create data files for the @code{gcov} code-coverage utility
2900 (@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}).  See
2901 @option{-fprofile-arcs} option above for a description of @var{auxname}.
2902
2903 @table @gcctabopt
2904 @item @var{auxname}.bb
2905 A mapping from basic blocks to line numbers, which @code{gcov} uses to
2906 associate basic block execution counts with line numbers.
2907
2908 @item @var{auxname}.bbg
2909 A list of all arcs in the program flow graph.  This allows @code{gcov}
2910 to reconstruct the program flow graph, so that it can compute all basic
2911 block and arc execution counts from the information in the
2912 @file{@var{auxname}.da} file.
2913 @end table
2914
2915 Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter
2916 option adds instrumentation to the program, which then writes
2917 execution counts to another data file:
2918
2919 @table @gcctabopt
2920 @item @var{auxname}.da
2921 Runtime arc execution counts, used in conjunction with the arc
2922 information in the file @file{@var{auxname}.bbg}.
2923 @end table
2924
2925 Coverage data will map better to the source files if
2926 @option{-ftest-coverage} is used without optimization.
2927
2928 @item -d@var{letters}
2929 @opindex d
2930 Says to make debugging dumps during compilation at times specified by
2931 @var{letters}.  This is used for debugging the compiler.  The file names
2932 for most of the dumps are made by appending a pass number and a word to
2933 the @var{dumpname}. @var{dumpname} is generated from the name of the
2934 output file, if explicitly specified and it is not an executable,
2935 otherwise it is the basename of the source file. In both cases any
2936 suffix is removed (e.g.  @file{foo.00.rtl} or @file{foo.01.sibling}).
2937 Here are the possible letters for use in @var{letters}, and their
2938 meanings:
2939
2940 @table @samp
2941 @item A
2942 @opindex dA
2943 Annotate the assembler output with miscellaneous debugging information.
2944 @item b
2945 @opindex db
2946 Dump after computing branch probabilities, to @file{@var{file}.15.bp}.
2947 @item B
2948 @opindex dB
2949 Dump after block reordering, to @file{@var{file}.30.bbro}.
2950 @item c
2951 @opindex dc
2952 Dump after instruction combination, to the file @file{@var{file}.17.combine}.
2953 @item C
2954 @opindex dC
2955 Dump after the first if conversion, to the file @file{@var{file}.18.ce}.
2956 @item d
2957 @opindex dd
2958 Dump after delayed branch scheduling, to @file{@var{file}.32.dbr}.
2959 @item D
2960 @opindex dD
2961 Dump all macro definitions, at the end of preprocessing, in addition to
2962 normal output.
2963 @item e
2964 @opindex de
2965 Dump after SSA optimizations, to @file{@var{file}.04.ssa} and
2966 @file{@var{file}.07.ussa}.
2967 @item E
2968 @opindex dE
2969 Dump after the second if conversion, to @file{@var{file}.27.ce2}.
2970 @item f
2971 @opindex df
2972 Dump after life analysis, to @file{@var{file}.16.life}.
2973 @item F
2974 @opindex dF
2975 Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}.
2976 @item g
2977 @opindex dg
2978 Dump after global register allocation, to @file{@var{file}.22.greg}.
2979 @item h
2980 @opindex dh
2981 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
2982 @item k
2983 @opindex dk
2984 Dump after reg-to-stack conversion, to @file{@var{file}.29.stack}.
2985 @item o
2986 @opindex do
2987 Dump after post-reload optimizations, to @file{@var{file}.23.postreload}.
2988 @item G
2989 @opindex dG
2990 Dump after GCSE, to @file{@var{file}.11.gcse}.
2991 @item i
2992 @opindex di
2993 Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
2994 @item j
2995 @opindex dj
2996 Dump after the first jump optimization, to @file{@var{file}.03.jump}.
2997 @item k
2998 @opindex dk
2999 Dump after conversion from registers to stack, to @file{@var{file}.33.stack}.
3000 @item l
3001 @opindex dl
3002 Dump after local register allocation, to @file{@var{file}.21.lreg}.
3003 @item L
3004 @opindex dL
3005 Dump after loop optimization, to @file{@var{file}.12.loop}.
3006 @item M
3007 @opindex dM
3008 Dump after performing the machine dependent reorganisation pass, to
3009 @file{@var{file}.31.mach}.
3010 @item n
3011 @opindex dn
3012 Dump after register renumbering, to @file{@var{file}.26.rnreg}.
3013 @item N
3014 @opindex dN
3015 Dump after the register move pass, to @file{@var{file}.19.regmove}.
3016 @item r
3017 @opindex dr
3018 Dump after RTL generation, to @file{@var{file}.00.rtl}.
3019 @item R
3020 @opindex dR
3021 Dump after the second scheduling pass, to @file{@var{file}.28.sched2}.
3022 @item s
3023 @opindex ds
3024 Dump after CSE (including the jump optimization that sometimes follows
3025 CSE), to @file{@var{file}.09.cse}.
3026 @item S
3027 @opindex dS
3028 Dump after the first scheduling pass, to @file{@var{file}.20.sched}.
3029 @item t
3030 @opindex dt
3031 Dump after the second CSE pass (including the jump optimization that
3032 sometimes follows CSE), to @file{@var{file}.13.cse2}.
3033 @item u
3034 @opindex du
3035 Dump after null pointer ellimination pass ti @file{@var{file}.08.null}.
3036 @item w
3037 @opindex dw
3038 Dump after the second flow pass, to @file{@var{file}.24.flow2}.
3039 @item X
3040 @opindex dX
3041 Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}.
3042 @item z
3043 @opindex dz
3044 Dump after the peephole pass, to @file{@var{file}.25.peephole2}.
3045 @item a
3046 @opindex da
3047 Produce all the dumps listed above.
3048 @item m
3049 @opindex dm
3050 Print statistics on memory usage, at the end of the run, to
3051 standard error.
3052 @item p
3053 @opindex dp
3054 Annotate the assembler output with a comment indicating which
3055 pattern and alternative was used.  The length of each instruction is
3056 also printed.
3057 @item P
3058 @opindex dP
3059 Dump the RTL in the assembler output as a comment before each instruction.
3060 Also turns on @option{-dp} annotation.
3061 @item v
3062 @opindex dv
3063 For each of the other indicated dump files (except for
3064 @file{@var{file}.00.rtl}), dump a representation of the control flow graph
3065 suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3066 @item x
3067 @opindex dx
3068 Just generate RTL for a function instead of compiling it.  Usually used
3069 with @samp{r}.
3070 @item y
3071 @opindex dy
3072 Dump debugging information during parsing, to standard error.
3073 @end table
3074
3075 @item -fdump-unnumbered
3076 @opindex fdump-unnumbered
3077 When doing debugging dumps (see @option{-d} option above), suppress instruction
3078 numbers and line number note output.  This makes it more feasible to
3079 use diff on debugging dumps for compiler invocations with different
3080 options, in particular with and without @option{-g}.
3081
3082 @item -fdump-translation-unit @r{(C and C++ only)}
3083 @itemx -fdump-translation-unit-@var{options} @r{(C and C++ only)}
3084 @opindex fdump-translation-unit
3085 Dump a representation of the tree structure for the entire translation
3086 unit to a file.  The file name is made by appending @file{.tu} to the
3087 source file name.  If the @samp{-@var{options}} form is used, @var{options}
3088 controls the details of the dump as described for the
3089 @option{-fdump-tree} options.
3090
3091 @item -fdump-class-hierarchy @r{(C++ only)}
3092 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3093 @opindex fdump-class-hierarchy
3094 Dump a representation of each class's hierarchy and virtual function
3095 table layout to a file.  The file name is made by appending @file{.class}
3096 to the source file name.  If the @samp{-@var{options}} form is used,
3097 @var{options} controls the details of the dump as described for the
3098 @option{-fdump-tree} options.
3099
3100 @item -fdump-tree-@var{switch} @r{(C++ only)}
3101 @itemx -fdump-tree-@var{switch}-@var{options} @r{(C++ only)}
3102 @opindex fdump-tree
3103 Control the dumping at various stages of processing the intermediate
3104 language tree to a file.  The file name is generated by appending a switch
3105 specific suffix to the source file name.  If the @samp{-@var{options}}
3106 form is used, @var{options} is a list of @samp{-} separated options that
3107 control the details of the dump. Not all options are applicable to all
3108 dumps, those which are not meaningful will be ignored. The following
3109 options are available
3110
3111 @table @samp
3112 @item address
3113 Print the address of each node.  Usually this is not meaningful as it
3114 changes according to the environment and source file. Its primary use
3115 is for tying up a dump file with a debug environment.
3116 @item slim
3117 Inhibit dumping of members of a scope or body of a function merely
3118 because that scope has been reached. Only dump such items when they
3119 are directly reachable by some other path.
3120 @item all
3121 Turn on all options.
3122 @end table
3123
3124 The following tree dumps are possible:
3125 @table @samp
3126 @item original
3127 Dump before any tree based optimization, to @file{@var{file}.original}.
3128 @item optimized
3129 Dump after all tree based optimization, to @file{@var{file}.optimized}.
3130 @item inlined
3131 Dump after function inlining, to @file{@var{file}.inlined}.
3132 @end table
3133
3134 @item -save-temps
3135 @opindex save-temps
3136 Store the usual ``temporary'' intermediate files permanently; place them
3137 in the current directory and name them based on the source file.  Thus,
3138 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
3139 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.  This creates a
3140 preprocessed @file{foo.i} output file even though the compiler now
3141 normally uses an integrated preprocessor.
3142
3143 @item -time
3144 @opindex time
3145 Report the CPU time taken by each subprocess in the compilation
3146 sequence.  For C source files, this is the compiler proper and assembler
3147 (plus the linker if linking is done).  The output looks like this:
3148
3149 @smallexample
3150 # cc1 0.12 0.01
3151 # as 0.00 0.01
3152 @end smallexample
3153
3154 The first number on each line is the ``user time,'' that is time spent
3155 executing the program itself.  The second number is ``system time,''
3156 time spent executing operating system routines on behalf of the program.
3157 Both numbers are in seconds.
3158
3159 @item -print-file-name=@var{library}
3160 @opindex print-file-name
3161 Print the full absolute name of the library file @var{library} that
3162 would be used when linking---and don't do anything else.  With this
3163 option, GCC does not compile or link anything; it just prints the
3164 file name.
3165
3166 @item -print-multi-directory
3167 @opindex print-multi-directory
3168 Print the directory name corresponding to the multilib selected by any
3169 other switches present in the command line.  This directory is supposed
3170 to exist in @env{GCC_EXEC_PREFIX}.
3171
3172 @item -print-multi-lib
3173 @opindex print-multi-lib
3174 Print the mapping from multilib directory names to compiler switches
3175 that enable them.  The directory name is separated from the switches by
3176 @samp{;}, and each switch starts with an @samp{@@} instead of the
3177 @samp{-}, without spaces between multiple switches.  This is supposed to
3178 ease shell-processing.
3179
3180 @item -print-prog-name=@var{program}
3181 @opindex print-prog-name
3182 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
3183
3184 @item -print-libgcc-file-name
3185 @opindex print-libgcc-file-name
3186 Same as @option{-print-file-name=libgcc.a}.
3187
3188 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
3189 but you do want to link with @file{libgcc.a}.  You can do
3190
3191 @example
3192 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
3193 @end example
3194
3195 @item -print-search-dirs
3196 @opindex print-search-dirs
3197 Print the name of the configured installation directory and a list of
3198 program and library directories gcc will search---and don't do anything else.
3199
3200 This is useful when gcc prints the error message
3201 @samp{installation problem, cannot exec cpp0: No such file or directory}.
3202 To resolve this you either need to put @file{cpp0} and the other compiler
3203 components where gcc expects to find them, or you can set the environment
3204 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
3205 Don't forget the trailing '/'.
3206 @xref{Environment Variables}.
3207
3208 @item -dumpmachine
3209 @opindex dumpmachine
3210 Print the compiler's target machine (for example,
3211 @samp{i686-pc-linux-gnu})---and don't do anything else.
3212
3213 @item -dumpversion
3214 @opindex dumpversion
3215 Print the compiler version (for example, @samp{3.0})---and don't do
3216 anything else.
3217
3218 @item -dumpspecs
3219 @opindex dumpspecs
3220 Print the compiler's built-in specs---and don't do anything else.  (This
3221 is used when GCC itself is being built.)  @xref{Spec Files}.
3222 @end table
3223
3224 @node Optimize Options
3225 @section Options That Control Optimization
3226 @cindex optimize options
3227 @cindex options, optimization
3228
3229 These options control various sorts of optimizations:
3230
3231 @table @gcctabopt
3232 @item -O
3233 @itemx -O1
3234 @opindex O
3235 @opindex O1
3236 Optimize.  Optimizing compilation takes somewhat more time, and a lot
3237 more memory for a large function.
3238
3239 Without @option{-O}, the compiler's goal is to reduce the cost of
3240 compilation and to make debugging produce the expected results.
3241 Statements are independent: if you stop the program with a breakpoint
3242 between statements, you can then assign a new value to any variable or
3243 change the program counter to any other statement in the function and
3244 get exactly the results you would expect from the source code.
3245
3246 With @option{-O}, the compiler tries to reduce code size and execution
3247 time, without performing any optimizations that take a great deal of
3248 compilation time.
3249
3250 @item -O2
3251 @opindex O2
3252 Optimize even more.  GCC performs nearly all supported optimizations
3253 that do not involve a space-speed tradeoff.  The compiler does not
3254 perform loop unrolling or function inlining when you specify @option{-O2}.
3255 As compared to @option{-O}, this option increases both compilation time
3256 and the performance of the generated code.
3257
3258 @option{-O2} turns on all optional optimizations except for loop
3259 unrolling, function inlining, and register renaming.  It also turns on
3260 the @option{-fforce-mem} and @option{-fstrict-aliasing} option on all
3261 machines and frame pointer elimination on machines where doing so does
3262 not interfere with debugging.
3263
3264 Please note the warning under @option{-fgcse} about
3265 invoking @option{-O2} on programs that use computed gotos.
3266
3267 @item -O3
3268 @opindex O3
3269 Optimize yet more.  @option{-O3} turns on all optimizations specified by
3270 @option{-O2} and also turns on the @option{-finline-functions} and
3271 @option{-frename-registers} options.
3272
3273 @item -O0
3274 @opindex O0
3275 Do not optimize.
3276
3277 @item -Os
3278 @opindex Os
3279 Optimize for size.  @option{-Os} enables all @option{-O2} optimizations that
3280 do not typically increase code size.  It also performs further
3281 optimizations designed to reduce code size.
3282
3283 If you use multiple @option{-O} options, with or without level numbers,
3284 the last such option is the one that is effective.
3285 @end table
3286
3287 Options of the form @option{-f@var{flag}} specify machine-independent
3288 flags.  Most flags have both positive and negative forms; the negative
3289 form of @option{-ffoo} would be @option{-fno-foo}.  In the table below,
3290 only one of the forms is listed---the one which is not the default.
3291 You can figure out the other form by either removing @samp{no-} or
3292 adding it.
3293
3294 @table @gcctabopt
3295 @item -ffloat-store
3296 @opindex ffloat-store
3297 Do not store floating point variables in registers, and inhibit other
3298 options that might change whether a floating point value is taken from a
3299 register or memory.
3300
3301 @cindex floating point precision
3302 This option prevents undesirable excess precision on machines such as
3303 the 68000 where the floating registers (of the 68881) keep more
3304 precision than a @code{double} is supposed to have.  Similarly for the
3305 x86 architecture.  For most programs, the excess precision does only
3306 good, but a few programs rely on the precise definition of IEEE floating
3307 point.  Use @option{-ffloat-store} for such programs, after modifying
3308 them to store all pertinent intermediate computations into variables.
3309
3310 @item -fno-default-inline
3311 @opindex fno-default-inline
3312 Do not make member functions inline by default merely because they are
3313 defined inside the class scope (C++ only).  Otherwise, when you specify
3314 @w{@option{-O}}, member functions defined inside class scope are compiled
3315 inline by default; i.e., you don't need to add @samp{inline} in front of
3316 the member function name.
3317
3318 @item -fno-defer-pop
3319 @opindex fno-defer-pop
3320 Always pop the arguments to each function call as soon as that function
3321 returns.  For machines which must pop arguments after a function call,
3322 the compiler normally lets arguments accumulate on the stack for several
3323 function calls and pops them all at once.
3324
3325 @item -fforce-mem
3326 @opindex fforce-mem
3327 Force memory operands to be copied into registers before doing
3328 arithmetic on them.  This produces better code by making all memory
3329 references potential common subexpressions.  When they are not common
3330 subexpressions, instruction combination should eliminate the separate
3331 register-load.  The @option{-O2} option turns on this option.
3332
3333 @item -fforce-addr
3334 @opindex fforce-addr
3335 Force memory address constants to be copied into registers before
3336 doing arithmetic on them.  This may produce better code just as
3337 @option{-fforce-mem} may.
3338
3339 @item -fomit-frame-pointer
3340 @opindex fomit-frame-pointer
3341 Don't keep the frame pointer in a register for functions that
3342 don't need one.  This avoids the instructions to save, set up and
3343 restore frame pointers; it also makes an extra register available
3344 in many functions.  @strong{It also makes debugging impossible on
3345 some machines.}
3346
3347 On some machines, such as the VAX, this flag has no effect, because
3348 the standard calling sequence automatically handles the frame pointer
3349 and nothing is saved by pretending it doesn't exist.  The
3350 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
3351 whether a target machine supports this flag.  @xref{Registers,,Register
3352 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
3353
3354 @item -foptimize-sibling-calls
3355 @opindex foptimize-sibling-calls
3356 Optimize sibling and tail recursive calls.
3357
3358 @item -ftrapv
3359 @opindex ftrapv
3360 This option generates traps for signed overflow on addition, subtraction,
3361 multiplication operations.
3362
3363 @item -fno-inline
3364 @opindex fno-inline
3365 Don't pay attention to the @code{inline} keyword.  Normally this option
3366 is used to keep the compiler from expanding any functions inline.
3367 Note that if you are not optimizing, no functions can be expanded inline.
3368
3369 @item -finline-functions
3370 @opindex finline-functions
3371 Integrate all simple functions into their callers.  The compiler
3372 heuristically decides which functions are simple enough to be worth
3373 integrating in this way.
3374
3375 If all calls to a given function are integrated, and the function is
3376 declared @code{static}, then the function is normally not output as
3377 assembler code in its own right.
3378
3379 @item -finline-limit=@var{n}
3380 @opindex finline-limit
3381 By default, gcc limits the size of functions that can be inlined.  This flag
3382 allows the control of this limit for functions that are explicitly marked as
3383 inline (ie marked with the inline keyword or defined within the class
3384 definition in c++).  @var{n} is the size of functions that can be inlined in
3385 number of pseudo instructions (not counting parameter handling).  The default
3386 value of @var{n} is 600.
3387 Increasing this value can result in more inlined code at
3388 the cost of compilation time and memory consumption.  Decreasing usually makes
3389 the compilation faster and less code will be inlined (which presumably
3390 means slower programs).  This option is particularly useful for programs that
3391 use inlining heavily such as those based on recursive templates with C++.
3392
3393 @emph{Note:} pseudo instruction represents, in this particular context, an
3394 abstract measurement of function's size.  In no way, it represents a count
3395 of assembly instructions and as such its exact meaning might change from one
3396 release to an another.
3397
3398 @item -fkeep-inline-functions
3399 @opindex fkeep-inline-functions
3400 Even if all calls to a given function are integrated, and the function
3401 is declared @code{static}, nevertheless output a separate run-time
3402 callable version of the function.  This switch does not affect
3403 @code{extern inline} functions.
3404
3405 @item -fkeep-static-consts
3406 @opindex fkeep-static-consts
3407 Emit variables declared @code{static const} when optimization isn't turned
3408 on, even if the variables aren't referenced.
3409
3410 GCC enables this option by default.  If you want to force the compiler to
3411 check if the variable was referenced, regardless of whether or not
3412 optimization is turned on, use the @option{-fno-keep-static-consts} option.
3413
3414 @item -fmerge-constants
3415 Attempt to merge identical constants (string constants and floating point
3416 constants) accross compilation units.
3417
3418 This option is default for optimized compilation if assembler and linker
3419 support it.  Use @option{-fno-merge-constants} to inhibit this behavior.
3420
3421 @item -fmerge-all-constants
3422 Attempt to merge identical constants and identical variables.
3423
3424 This option implies @option{-fmerge-constants}.  In addition to
3425 @option{-fmerge-constants} this considers e.g. even constant initialized
3426 arrays or initialized constant variables with integral or floating point
3427 types.  Languages like C or C++ require each non-automatic variable to
3428 have distinct location, so using this option will result in non-conforming
3429 behavior.
3430
3431 @item -fnew-ra
3432 @opindex fnew-ra
3433 Use a graph coloring register allocator.  Currently this option is meant
3434 for testing, so we are interested to hear about miscompilations with
3435 @option{-fnew-ra}.
3436
3437 @item -fno-function-cse
3438 @opindex fno-function-cse
3439 Do not put function addresses in registers; make each instruction that
3440 calls a constant function contain the function's address explicitly.
3441
3442 This option results in less efficient code, but some strange hacks
3443 that alter the assembler output may be confused by the optimizations
3444 performed when this option is not used.
3445
3446 @item -ffast-math
3447 @opindex ffast-math
3448 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
3449 @option{-fno-trapping-math}, @option{-ffinite-math-only} and @*
3450 @option{-fno-signaling-nans}.
3451
3452 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
3453
3454 This option should never be turned on by any @option{-O} option since
3455 it can result in incorrect output for programs which depend on
3456 an exact implementation of IEEE or ISO rules/specifications for
3457 math functions.
3458
3459 @item -fno-math-errno
3460 @opindex fno-math-errno
3461 Do not set ERRNO after calling math functions that are executed
3462 with a single instruction, e.g., sqrt.  A program that relies on
3463 IEEE exceptions for math error handling may want to use this flag
3464 for speed while maintaining IEEE arithmetic compatibility.
3465
3466 This option should never be turned on by any @option{-O} option since
3467 it can result in incorrect output for programs which depend on
3468 an exact implementation of IEEE or ISO rules/specifications for
3469 math functions.
3470
3471 The default is @option{-fmath-errno}.
3472
3473 @item -funsafe-math-optimizations
3474 @opindex funsafe-math-optimizations
3475 Allow optimizations for floating-point arithmetic that (a) assume
3476 that arguments and results are valid and (b) may violate IEEE or
3477 ANSI standards.  When used at link-time, it may include libraries
3478 or startup files that change the default FPU control word or other
3479 similar optimizations.
3480
3481 This option should never be turned on by any @option{-O} option since
3482 it can result in incorrect output for programs which depend on
3483 an exact implementation of IEEE or ISO rules/specifications for
3484 math functions.
3485
3486 The default is @option{-fno-unsafe-math-optimizations}.
3487
3488 @item -ffinite-math-only
3489 @opindex ffinite-math-only
3490 Allow optimizations for floating-point arithmetic that assume
3491 that arguments and results are not NaNs or +-Infs.
3492
3493 This option should never be turned on by any @option{-O} option since
3494 it can result in incorrect output for programs which depend on
3495 an exact implementation of IEEE or ISO rules/specifications.
3496
3497 The default is @option{-fno-finite-math-only}.
3498
3499 @item -fno-trapping-math
3500 @opindex fno-trapping-math
3501 Compile code assuming that floating-point operations cannot generate
3502 user-visible traps.  These traps include division by zero, overflow,
3503 underflow, inexact result and invalid operation.  This option implies
3504 @option{-fno-signaling-nans}.  Setting this option may allow faster
3505 code if one relies on ``non-stop'' IEEE arithmetic, for example.
3506
3507 This option should never be turned on by any @option{-O} option since
3508 it can result in incorrect output for programs which depend on
3509 an exact implementation of IEEE or ISO rules/specifications for
3510 math functions.
3511
3512 The default is @option{-ftrapping-math}.
3513
3514 @item -fsignaling-nans
3515 @opindex fsignaling-nans
3516 Compile code assuming that IEEE signaling NaNs may generate user-visible
3517 traps during floating-point operations.  Setting this option disables
3518 optimizations that may change the number of exceptions visible with
3519 signaling NaNs.  This option implies @option{-ftrapping-math}.
3520
3521 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
3522 be defined.
3523
3524 The default is @option{-fno-signaling-nans}.
3525
3526 This option is experimental and does not currently guarantee to
3527 disable all GCC optimizations that affect signaling NaN behavior.
3528
3529 @item -fno-zero-initialized-in-bss
3530 @opindex fno-zero-initialized-in-bss
3531 If the target supports a BSS section, GCC by default puts variables that
3532 are initialized to zero into BSS@.  This can save space in the resulting
3533 code.
3534
3535 This option turns off this behavior because some programs explicitly
3536 rely on variables going to the data section.  E.g., so that the
3537 resulting executable can find the beginning of that section and/or make
3538 assumptions based on that.
3539
3540 The default is @option{-fzero-initialized-in-bss}.
3541 @end table
3542
3543 The following options control specific optimizations.  The @option{-O2}
3544 option turns on all of these optimizations except @option{-funroll-loops}
3545 and @option{-funroll-all-loops}.  On most machines, the @option{-O} option
3546 turns on the @option{-fthread-jumps} and @option{-fdelayed-branch} options,
3547 but specific machines may handle it differently.
3548
3549 You can use the following flags in the rare cases when ``fine-tuning''
3550 of optimizations to be performed is desired.
3551
3552 Not all of the optimizations performed by GCC have @option{-f} options
3553 to control them.
3554
3555 @table @gcctabopt
3556 @item -fstrength-reduce
3557 @opindex fstrength-reduce
3558 Perform the optimizations of loop strength reduction and
3559 elimination of iteration variables.
3560
3561 @item -fthread-jumps
3562 @opindex fthread-jumps
3563 Perform optimizations where we check to see if a jump branches to a
3564 location where another comparison subsumed by the first is found.  If
3565 so, the first branch is redirected to either the destination of the
3566 second branch or a point immediately following it, depending on whether
3567 the condition is known to be true or false.
3568
3569 @item -fcse-follow-jumps
3570 @opindex fcse-follow-jumps
3571 In common subexpression elimination, scan through jump instructions
3572 when the target of the jump is not reached by any other path.  For
3573 example, when CSE encounters an @code{if} statement with an
3574 @code{else} clause, CSE will follow the jump when the condition
3575 tested is false.
3576
3577 @item -fcse-skip-blocks
3578 @opindex fcse-skip-blocks
3579 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
3580 follow jumps which conditionally skip over blocks.  When CSE
3581 encounters a simple @code{if} statement with no else clause,
3582 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
3583 body of the @code{if}.
3584
3585 @item -frerun-cse-after-loop
3586 @opindex frerun-cse-after-loop
3587 Re-run common subexpression elimination after loop optimizations has been
3588 performed.
3589
3590 @item -frerun-loop-opt
3591 @opindex frerun-loop-opt
3592 Run the loop optimizer twice.
3593
3594 @item -fgcse
3595 @opindex fgcse
3596 Perform a global common subexpression elimination pass.
3597 This pass also performs global constant and copy propagation.
3598
3599 @emph{Note:} When compiling a program using computed gotos, a GCC
3600 extension, you may get better runtime performance if you disable
3601 the global common subexpression elmination pass by adding
3602 @option{-fno-gcse} to the command line.
3603
3604 @item -fgcse-lm
3605 @opindex fgcse-lm
3606 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
3607 attempt to move loads which are only killed by stores into themselves.  This
3608 allows a loop containing a load/store sequence to be changed to a load outside
3609 the loop, and a copy/store within the loop.
3610
3611 @item -fgcse-sm
3612 @opindex fgcse-sm
3613 When @option{-fgcse-sm} is enabled, A store motion pass is run after global common
3614 subexpression elimination.  This pass will attempt to move stores out of loops.
3615 When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence
3616 can be changed to a load before the loop and a store after the loop.
3617
3618 @item -floop-optimize
3619 @opindex floop-optimize
3620 Perform loop optimizations: move constant expressions out of loops, simplify
3621 exit test conditions and optionally do strength-reduction and loop unrolling as
3622 well.
3623
3624 @item -fcrossjumping
3625 @opindex crossjumping
3626 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
3627 resulting code may or may not perform better than without cross-jumping.
3628
3629 @item -fif-conversion
3630 @opindex if-conversion
3631 Attempt to transform conditional jumps into branch-less equivalents.  This
3632 include use of conditional moves, min, max, set flags and abs instructions, and
3633 some tricks doable by standard arithmetics.  The use of conditional execution
3634 on chips where it is available is controlled by @code{if-conversion2}.
3635
3636 @item -fif-conversion2
3637 @opindex if-conversion2
3638 Use conditional execution (where available) to transform conditional jumps into
3639 branch-less equivalents.
3640
3641 @item -fdelete-null-pointer-checks
3642 @opindex fdelete-null-pointer-checks
3643 Use global dataflow analysis to identify and eliminate useless checks
3644 for null pointers.  The compiler assumes that dereferencing a null
3645 pointer would have halted the program.  If a pointer is checked after
3646 it has already been dereferenced, it cannot be null.
3647
3648 In some environments, this assumption is not true, and programs can
3649 safely dereference null pointers.  Use
3650 @option{-fno-delete-null-pointer-checks} to disable this optimization
3651 for programs which depend on that behavior.
3652
3653 @item -fexpensive-optimizations