OSDN Git Service

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