OSDN Git Service

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