OSDN Git Service

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