OSDN Git Service

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