OSDN Git Service

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