OSDN Git Service

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