OSDN Git Service

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