OSDN Git Service

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