OSDN Git Service

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