OSDN Git Service

e956baa902af807aa7bd40283118d80cfc7539b4
[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 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
5
6 @ignore
7 @c man begin COPYRIGHT
8 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997,
9 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
10
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.1 or
13 any later version published by the Free Software Foundation; with the
14 Invariant Sections being ``GNU General Public License'' and ``Funding
15 Free Software'', the Front-Cover texts being (a) (see below), and with
16 the Back-Cover Texts being (b) (see below).  A copy of the license is
17 included in the gfdl(7) man page.
18
19 (a) The FSF's Front-Cover Text is:
20
21      A GNU Manual
22
23 (b) The FSF's Back-Cover Text is:
24
25      You have freedom to copy and modify this GNU Manual, like GNU
26      software.  Copies published by the Free Software Foundation raise
27      funds for GNU development.
28 @c man end
29 @c Set file name and title for the man page.
30 @setfilename gcc
31 @settitle GNU project C and C++ compiler
32 @c man begin SYNOPSIS
33 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
34     [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
35     [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
36     [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
37     [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
38     [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
39     [@option{-o} @var{outfile}] @var{infile}@dots{}
40
41 Only the most useful options are listed here; see below for the
42 remainder.  @samp{g++} accepts mostly the same options as @samp{gcc}.
43 @c man end
44 @c man begin SEEALSO
45 gpl(7), gfdl(7), fsf-funding(7),
46 cpp(1), gcov(1), g77(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
47 and the Info entries for @file{gcc}, @file{cpp}, @file{g77}, @file{as},
48 @file{ld}, @file{binutils} and @file{gdb}.
49 @c man end
50 @c man begin BUGS
51 For instructions on reporting bugs, see
52 @w{@uref{http://gcc.gnu.org/bugs.html}}.  Use of the @command{gccbug}
53 script to report bugs is recommended.
54 @c man end
55 @c man begin AUTHOR
56 See the Info entry for @command{gcc}, or
57 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
58 for contributors to GCC@.
59 @c man end
60 @end ignore
61
62 @node Invoking GCC
63 @chapter GCC Command Options
64 @cindex GCC command options
65 @cindex command options
66 @cindex options, GCC command
67
68 @c man begin DESCRIPTION
69
70 When you invoke GCC, it normally does preprocessing, compilation,
71 assembly and linking.  The ``overall options'' allow you to stop this
72 process at an intermediate stage.  For example, the @option{-c} option
73 says not to run the linker.  Then the output consists of object files
74 output by the assembler.
75
76 Other options are passed on to one stage of processing.  Some options
77 control the preprocessor and others the compiler itself.  Yet other
78 options control the assembler and linker; most of these are not
79 documented here, since you rarely need to use any of them.
80
81 @cindex C compilation options
82 Most of the command line options that you can use with GCC are useful
83 for C programs; when an option is only useful with another language
84 (usually C++), the explanation says so explicitly.  If the description
85 for a particular option does not mention a source language, you can use
86 that option with all supported languages.
87
88 @cindex C++ compilation options
89 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
90 options for compiling C++ programs.
91
92 @cindex grouping options
93 @cindex options, grouping
94 The @command{gcc} program accepts options and file names as operands.  Many
95 options have multi-letter names; therefore multiple single-letter options
96 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
97 -r}}.
98
99 @cindex order of options
100 @cindex options, order
101 You can mix options and other arguments.  For the most part, the order
102 you use doesn't matter.  Order does matter when you use several options
103 of the same kind; for example, if you specify @option{-L} more than once,
104 the directories are searched in the order specified.
105
106 Many options have long names starting with @samp{-f} or with
107 @samp{-W}---for example, @option{-fforce-mem},
108 @option{-fstrength-reduce}, @option{-Wformat} and so on.  Most of
109 these have both positive and negative forms; the negative form of
110 @option{-ffoo} would be @option{-fno-foo}.  This manual documents
111 only one of these two forms, whichever one is not the default.
112
113 @c man end
114
115 @xref{Option Index}, for an index to GCC's options.
116
117 @menu
118 * Option Summary::      Brief list of all options, without explanations.
119 * Overall Options::     Controlling the kind of output:
120                         an executable, object files, assembler files,
121                         or preprocessed source.
122 * Invoking G++::        Compiling C++ programs.
123 * C Dialect Options::   Controlling the variant of C language compiled.
124 * C++ Dialect Options:: Variations on C++.
125 * Objective-C Dialect Options:: Variations on Objective-C.
126 * Language Independent Options:: Controlling how diagnostics should be
127                         formatted.
128 * Warning Options::     How picky should the compiler be?
129 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
130 * Optimize Options::    How much optimization?
131 * Preprocessor Options:: Controlling header files and macro definitions.
132                          Also, getting dependency information for Make.
133 * Assembler Options::   Passing options to the assembler.
134 * Link Options::        Specifying libraries and so on.
135 * Directory Options::   Where to find header files and libraries.
136                         Where to find the compiler executable files.
137 * Spec Files::          How to pass switches to sub-processes.
138 * Target Options::      Running a cross-compiler, or an old version of GCC.
139 * Submodel Options::    Specifying minor hardware or convention variations,
140                         such as 68010 vs 68020.
141 * Code Gen Options::    Specifying conventions for function calls, data layout
142                         and register usage.
143 * Environment Variables:: Env vars that affect GCC.
144 * Running Protoize::    Automatically adding or removing function prototypes.
145 @end menu
146
147 @c man begin OPTIONS
148
149 @node Option Summary
150 @section Option Summary
151
152 Here is a summary of all the options, grouped by type.  Explanations are
153 in the following sections.
154
155 @table @emph
156 @item Overall Options
157 @xref{Overall Options,,Options Controlling the Kind of Output}.
158 @gccoptlist{
159 -c  -S  -E  -o @var{file}  -pipe  -pass-exit-codes  -x @var{language} @gol
160 -v  -###  --target-help  --help}
161
162 @item C Language Options
163 @xref{C Dialect Options,,Options Controlling C Dialect}.
164 @gccoptlist{
165 -ansi  -std=@var{standard}  -aux-info @var{filename} @gol
166 -fno-asm  -fno-builtin -fno-builtin-@var{function} @gol
167 -fhosted  -ffreestanding  -fms-extensions @gol
168 -trigraphs  -traditional  -traditional-cpp @gol
169 -fallow-single-precision  -fcond-mismatch @gol
170 -fsigned-bitfields  -fsigned-char @gol
171 -funsigned-bitfields  -funsigned-char @gol
172 -fwritable-strings  -fshort-wchar}
173
174 @item C++ Language Options
175 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
176 @gccoptlist{
177 -fno-access-control  -fcheck-new  -fconserve-space @gol
178 -fno-const-strings  -fdollars-in-identifiers @gol
179 -fno-elide-constructors @gol
180 -fno-enforce-eh-specs  -fexternal-templates @gol
181 -falt-external-templates @gol
182 -ffor-scope  -fno-for-scope  -fno-gnu-keywords @gol
183 -fno-implicit-templates @gol
184 -fno-implicit-inline-templates @gol
185 -fno-implement-inlines  -fms-extensions @gol
186 -fno-nonansi-builtins  -fno-operator-names @gol
187 -fno-optional-diags  -fpermissive @gol
188 -frepo  -fno-rtti  -fstats  -ftemplate-depth-@var{n} @gol
189 -fuse-cxa-atexit  -fvtable-gc  -fno-weak  -nostdinc++ @gol
190 -fno-default-inline -Wabi -Wctor-dtor-privacy @gol
191 -Wnon-virtual-dtor  -Wreorder @gol
192 -Weffc++  -Wno-deprecated @gol
193 -Wno-non-template-friend  -Wold-style-cast @gol
194 -Woverloaded-virtual  -Wno-pmf-conversions @gol
195 -Wsign-promo  -Wsynth}
196
197 @item Objective-C Language Options
198 @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}.
199 @gccoptlist{
200 -fconstant-string-class=@var{class-name} @gol
201 -fgnu-runtime  -fnext-runtime  -gen-decls @gol
202 -Wno-protocol  -Wselector}
203
204 @item Language Independent Options
205 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
206 @gccoptlist{
207 -fmessage-length=@var{n}  @gol
208 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}}
209
210 @item Warning Options
211 @xref{Warning Options,,Options to Request or Suppress Warnings}.
212 @gccoptlist{
213 -fsyntax-only  -pedantic  -pedantic-errors @gol
214 -w  -W  -Wall -Waggregate-return @gol
215 -Wcast-align  -Wcast-qual  -Wchar-subscripts  -Wcomment @gol
216 -Wconversion  -Wno-deprecated-declarations @gol
217 -Wdisabled-optimization  -Wno-div-by-zero  -Werror @gol
218 -Wfloat-equal  -Wformat  -Wformat=2 @gol
219 -Wformat-nonliteral  -Wformat-security @gol
220 -Wimplicit  -Wimplicit-int  @gol
221 -Wimplicit-function-declaration @gol
222 -Werror-implicit-function-declaration @gol
223 -Wimport  -Winline -Wno-endif-labels @gol
224 -Wlarger-than-@var{len}  -Wlong-long @gol
225 -Wmain  -Wmissing-braces  -Wmissing-declarations @gol
226 -Wmissing-format-attribute  -Wmissing-noreturn @gol
227 -Wno-multichar  -Wno-format-extra-args  -Wno-format-y2k @gol
228 -Wno-import  -Wnonnull  -Wpacked  -Wpadded @gol
229 -Wparentheses  -Wpointer-arith  -Wredundant-decls @gol
230 -Wreturn-type  -Wsequence-point  -Wshadow @gol
231 -Wsign-compare  -Wswitch  -Wswitch-default -Wswitch-enum @gol
232 -Wsystem-headers -Wtrigraphs  -Wundef  -Wuninitialized @gol
233 -Wunknown-pragmas  -Wunreachable-code @gol
234 -Wunused  -Wunused-function  -Wunused-label  -Wunused-parameter @gol
235 -Wunused-value  -Wunused-variable  -Wwrite-strings}
236
237 @item C-only Warning Options
238 @gccoptlist{
239 -Wbad-function-cast  -Wmissing-prototypes  -Wnested-externs @gol
240 -Wstrict-prototypes  -Wtraditional}
241
242 @item Debugging Options
243 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
244 @gccoptlist{
245 -d@var{letters}  -dumpspecs  -dumpmachine  -dumpversion @gol
246 -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
247 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
248 -fdump-tree-original@r{[}-@var{n}@r{]} -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
249 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
250 -fmem-report @gol
251 -fprofile-arcs  -ftest-coverage  -ftime-report @gol
252 -g  -g@var{level}  -gcoff  -gdwarf  -gdwarf-1  -gdwarf-1+  -gdwarf-2 @gol
253 -ggdb  -gstabs  -gstabs+  -gvms  -gxcoff  -gxcoff+ @gol
254 -p  -pg  -print-file-name=@var{library}  -print-libgcc-file-name @gol
255 -print-multi-directory  -print-multi-lib @gol
256 -print-prog-name=@var{program}  -print-search-dirs  -Q @gol
257 -save-temps  -time}
258
259 @item Optimization Options
260 @xref{Optimize Options,,Options that Control Optimization}.
261 @gccoptlist{
262 -falign-functions=@var{n}  -falign-jumps=@var{n} @gol
263 -falign-labels=@var{n}  -falign-loops=@var{n}  @gol
264 -fbranch-probabilities  -fcaller-saves -fcprop-registers @gol
265 -fcse-follow-jumps  -fcse-skip-blocks  -fdata-sections @gol
266 -fdelayed-branch  -fdelete-null-pointer-checks @gol
267 -fexpensive-optimizations  -ffast-math  -ffloat-store @gol
268 -fforce-addr  -fforce-mem  -ffunction-sections @gol
269 -fgcse  -fgcse-lm  -fgcse-sm -floop-optimize -fcrossjumping @gol
270 -fif-conversion -fif-conversion2 @gol
271 -finline-functions  -finline-limit=@var{n}  -fkeep-inline-functions @gol
272 -fkeep-static-consts  -fmerge-constants  -fmerge-all-constants @gol
273 -fmove-all-movables  -fnew-ra -fno-default-inline  -fno-defer-pop @gol
274 -fno-function-cse  -fno-guess-branch-probability @gol
275 -fno-inline  -fno-math-errno  -fno-peephole  -fno-peephole2 @gol
276 -funsafe-math-optimizations -ffinite-math-only -fno-trapping-math @gol
277 -fno-zero-initialized-in-bss @gol
278 -fomit-frame-pointer  -foptimize-register-move @gol
279 -foptimize-sibling-calls  -fprefetch-loop-arrays @gol
280 -freduce-all-givs -fregmove  -frename-registers @gol
281 -freorder-blocks -freorder-functions @gol
282 -frerun-cse-after-loop  -frerun-loop-opt @gol
283 -fschedule-insns  -fschedule-insns2 -fsignaling-nans @gol
284 -fsingle-precision-constant  -fssa -fssa-ccp -fssa-dce @gol
285 -fstrength-reduce  -fstrict-aliasing  -ftracer -fthread-jumps  -ftrapv @gol
286 -funroll-all-loops  -funroll-loops  @gol
287 --param @var{name}=@var{value}
288 -O  -O0  -O1  -O2  -O3  -Os}
289
290 @item Preprocessor Options
291 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
292 @gccoptlist{
293 -$  -A@var{question}=@var{answer}  -A-@var{question}@r{[}=@var{answer}@r{]} @gol
294 -C  -dD  -dI  -dM  -dN @gol
295 -D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H @gol
296 -idirafter @var{dir} @gol
297 -include @var{file}  -imacros @var{file} @gol
298 -iprefix @var{file}  -iwithprefix @var{dir} @gol
299 -iwithprefixbefore @var{dir}  -isystem @var{dir} @gol
300 -M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  -P  -remap @gol
301 -trigraphs  -undef  -U@var{macro}  -Wp,@var{option}}
302
303 @item Assembler Option
304 @xref{Assembler Options,,Passing Options to the Assembler}.
305 @gccoptlist{
306 -Wa,@var{option}}
307
308 @item Linker Options
309 @xref{Link Options,,Options for Linking}.
310 @gccoptlist{
311 @var{object-file-name}  -l@var{library} @gol
312 -nostartfiles  -nodefaultlibs  -nostdlib @gol
313 -s  -static  -static-libgcc  -shared  -shared-libgcc  -symbolic @gol
314 -Wl,@var{option}  -Xlinker @var{option} @gol
315 -u @var{symbol}}
316
317 @item Directory Options
318 @xref{Directory Options,,Options for Directory Search}.
319 @gccoptlist{
320 -B@var{prefix}  -I@var{dir}  -I-  -L@var{dir}  -specs=@var{file}}
321
322 @item Target Options
323 @c I wrote this xref this way to avoid overfull hbox. -- rms
324 @xref{Target Options}.
325 @gccoptlist{
326 -V @var{version} -b @var{machine}}
327
328 @item Machine Dependent Options
329 @xref{Submodel Options,,Hardware Models and Configurations}.
330
331 @emph{M680x0 Options}
332 @gccoptlist{
333 -m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040 @gol
334 -m68060  -mcpu32  -m5200  -m68881  -mbitfield  -mc68000  -mc68020   @gol
335 -mfpa  -mnobitfield  -mrtd  -mshort  -msoft-float  -mpcrel @gol
336 -malign-int  -mstrict-align}
337
338 @emph{M68hc1x Options}
339 @gccoptlist{
340 -m6811  -m6812  -m68hc11  -m68hc12 @gol
341 -mauto-incdec  -minmax  -mlong-calls  -mshort  -msoft-reg-count=@var{count}}
342
343 @emph{VAX Options}
344 @gccoptlist{
345 -mg  -mgnu  -munix}
346
347 @emph{SPARC Options}
348 @gccoptlist{
349 -mcpu=@var{cpu-type} @gol
350 -mtune=@var{cpu-type} @gol
351 -mcmodel=@var{code-model} @gol
352 -m32  -m64 @gol
353 -mapp-regs  -mbroken-saverestore  -mcypress @gol
354 -mfaster-structs  -mflat @gol
355 -mfpu  -mhard-float  -mhard-quad-float @gol
356 -mimpure-text  -mlive-g0  -mno-app-regs @gol
357 -mno-faster-structs  -mno-flat  -mno-fpu @gol
358 -mno-impure-text  -mno-stack-bias  -mno-unaligned-doubles @gol
359 -msoft-float  -msoft-quad-float  -msparclite  -mstack-bias @gol
360 -msupersparc  -munaligned-doubles  -mv8}
361
362 @emph{Convex Options}
363 @gccoptlist{
364 -mc1  -mc2  -mc32  -mc34  -mc38 @gol
365 -margcount  -mnoargcount @gol
366 -mlong32  -mlong64 @gol
367 -mvolatile-cache  -mvolatile-nocache}
368
369 @emph{AMD29K Options}
370 @gccoptlist{
371 -m29000  -m29050  -mbw  -mnbw  -mdw  -mndw @gol
372 -mlarge  -mnormal  -msmall @gol
373 -mkernel-registers  -mno-reuse-arg-regs @gol
374 -mno-stack-check  -mno-storem-bug @gol
375 -mreuse-arg-regs  -msoft-float  -mstack-check @gol
376 -mstorem-bug  -muser-registers}
377
378 @emph{ARM Options}
379 @gccoptlist{
380 -mapcs-frame  -mno-apcs-frame @gol
381 -mapcs-26  -mapcs-32 @gol
382 -mapcs-stack-check  -mno-apcs-stack-check @gol
383 -mapcs-float  -mno-apcs-float @gol
384 -mapcs-reentrant  -mno-apcs-reentrant @gol
385 -msched-prolog  -mno-sched-prolog @gol
386 -mlittle-endian  -mbig-endian  -mwords-little-endian @gol
387 -malignment-traps  -mno-alignment-traps @gol
388 -msoft-float  -mhard-float  -mfpe @gol
389 -mthumb-interwork  -mno-thumb-interwork @gol
390 -mcpu=@var{name}  -march=@var{name}  -mfpe=@var{name}  @gol
391 -mstructure-size-boundary=@var{n} @gol
392 -mbsd -mxopen  -mno-symrename @gol
393 -mabort-on-noreturn @gol
394 -mlong-calls  -mno-long-calls @gol
395 -msingle-pic-base  -mno-single-pic-base @gol
396 -mpic-register=@var{reg} @gol
397 -mnop-fun-dllimport @gol
398 -mpoke-function-name @gol
399 -mthumb  -marm @gol
400 -mtpcs-frame  -mtpcs-leaf-frame @gol
401 -mcaller-super-interworking  -mcallee-super-interworking }
402
403 @emph{MN10200 Options}
404 @gccoptlist{
405 -mrelax}
406
407 @emph{MN10300 Options}
408 @gccoptlist{
409 -mmult-bug  -mno-mult-bug @gol
410 -mam33  -mno-am33 @gol
411 -mno-crt0  -mrelax}
412
413 @emph{M32R/D Options}
414 @gccoptlist{
415 -m32rx -m32r -mcode-model=@var{model-type}  -msdata=@var{sdata-type} @gol
416 -G @var{num}}
417
418 @emph{M88K Options}
419 @gccoptlist{
420 -m88000  -m88100  -m88110  -mbig-pic @gol
421 -mcheck-zero-division  -mhandle-large-shift @gol
422 -midentify-revision  -mno-check-zero-division @gol
423 -mno-ocs-debug-info  -mno-ocs-frame-position @gol
424 -mno-optimize-arg-area  -mno-serialize-volatile @gol
425 -mno-underscores  -mocs-debug-info @gol
426 -mocs-frame-position  -moptimize-arg-area @gol
427 -mserialize-volatile  -mshort-data-@var{num}  -msvr3 @gol
428 -msvr4  -mtrap-large-shift  -muse-div-instruction @gol
429 -mversion-03.00  -mwarn-passed-structs}
430
431 @emph{RS/6000 and PowerPC Options}
432 @gccoptlist{
433 -mcpu=@var{cpu-type} @gol
434 -mtune=@var{cpu-type} @gol
435 -mpower  -mno-power  -mpower2  -mno-power2 @gol
436 -mpowerpc  -mpowerpc64  -mno-powerpc @gol
437 -maltivec -mno-altivec @gol
438 -mpowerpc-gpopt  -mno-powerpc-gpopt @gol
439 -mpowerpc-gfxopt  -mno-powerpc-gfxopt @gol
440 -mnew-mnemonics  -mold-mnemonics @gol
441 -mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc @gol
442 -m64  -m32  -mxl-call  -mno-xl-call  -mpe @gol
443 -msoft-float  -mhard-float  -mmultiple  -mno-multiple @gol
444 -mstring  -mno-string  -mupdate  -mno-update @gol
445 -mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align @gol
446 -mstrict-align  -mno-strict-align  -mrelocatable @gol
447 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
448 -mtoc  -mno-toc -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
449 -mcall-aix -mcall-sysv -mcall-netbsd @gol
450 -maix-struct-return -msvr4-struct-return
451 -mabi=altivec -mabi=no-altivec @gol
452 -mabi=spe -mabi=no-spe @gol
453 -misel=yes -misel=no @gol
454 -mprototype  -mno-prototype @gol
455 -msim  -mmvme  -mads  -myellowknife  -memb -msdata @gol
456 -msdata=@var{opt}  -mvxworks -mwindiss -G @var{num} -pthread}
457
458 @emph{RT Options}
459 @gccoptlist{
460 -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs @gol
461 -mfull-fp-blocks  -mhc-struct-return  -min-line-mul @gol
462 -mminimum-fp-blocks  -mnohc-struct-return}
463
464 @emph{MIPS Options}
465 @gccoptlist{
466 -mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol
467 -mcpu=@var{cpu-type} -membedded-data  -muninit-const-in-rodata @gol
468 -membedded-pic  -mfp32  -mfp64  -mfused-madd  -mno-fused-madd @gol
469 -mgas  -mgp32  -mgp64 @gol
470 -mgpopt  -mhalf-pic  -mhard-float  -mint64  -mips1 @gol
471 -mips2  -mips3  -mips4  -mlong64  -mlong32  -mlong-calls  -mmemcpy @gol
472 -mmips-as  -mmips-tfile  -mno-abicalls @gol
473 -mno-embedded-data  -mno-uninit-const-in-rodata @gol
474 -mno-embedded-pic  -mno-gpopt  -mno-long-calls @gol
475 -mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats @gol
476 -mrnames  -msoft-float @gol
477 -m4650  -msingle-float  -mmad @gol
478 -mstats  -EL  -EB  -G @var{num}  -nocpp @gol
479 -mabi=32  -mabi=n32  -mabi=64  -mabi=eabi @gol
480 -mfix7000  -mno-crt0 -mflush-func=@var{func} -mno-flush-func
481 -mbranch-likely -mno-branch-likely}
482
483 @emph{i386 and x86-64 Options}
484 @gccoptlist{
485 -mcpu=@var{cpu-type}  -march=@var{cpu-type} -mfpmath=@var{unit} @gol
486 -masm=@var{dialect}  -mno-fancy-math-387 @gol
487 -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib @gol
488 -mno-wide-multiply  -mrtd  -malign-double @gol
489 -mpreferred-stack-boundary=@var{num} @gol
490 -mmmx  -msse -msse2 -msse-math -m3dnow @gol
491 -mthreads  -mno-align-stringops  -minline-all-stringops @gol
492 -mpush-args  -maccumulate-outgoing-args  -m128bit-long-double @gol
493 -m96bit-long-double  -mregparm=@var{num}  -momit-leaf-frame-pointer @gol
494 -mno-red-zone@gol
495 -mcmodel=@var{code-model} @gol
496 -m32 -m64}
497
498 @emph{HPPA Options}
499 @gccoptlist{
500 -march=@var{architecture-type} @gol
501 -mbig-switch  -mdisable-fpregs  -mdisable-indexing @gol
502 -mfast-indirect-calls  -mgas  -mjump-in-delay @gol
503 -mlong-load-store  -mno-big-switch  -mno-disable-fpregs @gol
504 -mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas @gol
505 -mno-jump-in-delay  -mno-long-load-store @gol
506 -mno-portable-runtime  -mno-soft-float @gol
507 -mno-space-regs  -msoft-float  -mpa-risc-1-0 @gol
508 -mpa-risc-1-1  -mpa-risc-2-0  -mportable-runtime @gol
509 -mschedule=@var{cpu-type}  -mspace-regs}
510
511 @emph{Intel 960 Options}
512 @gccoptlist{
513 -m@var{cpu-type}  -masm-compat  -mclean-linkage @gol
514 -mcode-align  -mcomplex-addr  -mleaf-procedures @gol
515 -mic-compat  -mic2.0-compat  -mic3.0-compat @gol
516 -mintel-asm  -mno-clean-linkage  -mno-code-align @gol
517 -mno-complex-addr  -mno-leaf-procedures @gol
518 -mno-old-align  -mno-strict-align  -mno-tail-call @gol
519 -mnumerics  -mold-align  -msoft-float  -mstrict-align @gol
520 -mtail-call}
521
522 @emph{DEC Alpha Options}
523 @gccoptlist{
524 -mno-fp-regs  -msoft-float  -malpha-as  -mgas @gol
525 -mieee  -mieee-with-inexact  -mieee-conformant @gol
526 -mfp-trap-mode=@var{mode}  -mfp-rounding-mode=@var{mode} @gol
527 -mtrap-precision=@var{mode}  -mbuild-constants @gol
528 -mcpu=@var{cpu-type}  -mtune=@var{cpu-type} @gol
529 -mbwx  -mmax  -mfix  -mcix @gol
530 -mfloat-vax  -mfloat-ieee @gol
531 -mexplicit-relocs  -msmall-data  -mlarge-data @gol
532 -mmemory-latency=@var{time}}
533
534 @emph{DEC Alpha/VMS Options}
535 @gccoptlist{
536 -mvms-return-codes}
537
538 @emph{Clipper Options}
539 @gccoptlist{
540 -mc300  -mc400}
541
542 @emph{H8/300 Options}
543 @gccoptlist{
544 -mrelax  -mh  -ms  -mint32  -malign-300}
545
546 @emph{SH Options}
547 @gccoptlist{
548 -m1  -m2  -m3  -m3e @gol
549 -m4-nofpu  -m4-single-only  -m4-single  -m4 @gol
550 -m5-64media -m5-64media-nofpu @gol
551 -m5-32media -m5-32media-nofpu @gol
552 -m5-compact -m5-compact-nofpu @gol
553 -mb  -ml  -mdalign  -mrelax @gol
554 -mbigtable  -mfmovd  -mhitachi  -mnomacsave @gol
555 -mieee  -misize  -mpadstruct  -mspace @gol
556 -mprefergot  -musermode}
557
558 @emph{System V Options}
559 @gccoptlist{
560 -Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}}
561
562 @emph{ARC Options}
563 @gccoptlist{
564 -EB  -EL @gol
565 -mmangle-cpu  -mcpu=@var{cpu}  -mtext=@var{text-section} @gol
566 -mdata=@var{data-section}  -mrodata=@var{readonly-data-section}}
567
568 @emph{TMS320C3x/C4x Options}
569 @gccoptlist{
570 -mcpu=@var{cpu}  -mbig  -msmall  -mregparm  -mmemparm @gol
571 -mfast-fix  -mmpyi  -mbk  -mti  -mdp-isr-reload @gol
572 -mrpts=@var{count}  -mrptb  -mdb  -mloop-unsigned @gol
573 -mparallel-insns  -mparallel-mpy  -mpreserve-float}
574
575 @emph{V850 Options}
576 @gccoptlist{
577 -mlong-calls  -mno-long-calls  -mep  -mno-ep @gol
578 -mprolog-function  -mno-prolog-function  -mspace @gol
579 -mtda=@var{n}  -msda=@var{n}  -mzda=@var{n} @gol
580 -mapp-regs -mno-app-regs @gol
581 -mdisable-callt -mno-disable-callt @gol
582 -mv850e @gol
583 -mv850  -mbig-switch}
584
585 @emph{NS32K Options}
586 @gccoptlist{
587 -m32032  -m32332  -m32532  -m32081  -m32381 @gol
588 -mmult-add  -mnomult-add  -msoft-float  -mrtd  -mnortd @gol
589 -mregparam  -mnoregparam  -msb  -mnosb @gol
590 -mbitfield  -mnobitfield  -mhimem  -mnohimem}
591
592 @emph{AVR Options}
593 @gccoptlist{
594 -mmcu=@var{mcu}  -msize  -minit-stack=@var{n}  -mno-interrupts @gol
595 -mcall-prologues  -mno-tablejump  -mtiny-stack}
596
597 @emph{MCore Options}
598 @gccoptlist{
599 -mhardlit  -mno-hardlit  -mdiv  -mno-div  -mrelax-immediates @gol
600 -mno-relax-immediates  -mwide-bitfields  -mno-wide-bitfields @gol
601 -m4byte-functions  -mno-4byte-functions  -mcallgraph-data @gol
602 -mno-callgraph-data  -mslow-bytes  -mno-slow-bytes  -mno-lsim @gol
603 -mlittle-endian  -mbig-endian  -m210  -m340  -mstack-increment}
604
605 @emph{MMIX Options}
606 @gccoptlist{
607 -mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
608 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
609 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
610 -mno-base-addresses -msingle-exit -mno-single-exit}
611
612 @emph{IA-64 Options}
613 @gccoptlist{
614 -mbig-endian  -mlittle-endian  -mgnu-as  -mgnu-ld  -mno-pic @gol
615 -mvolatile-asm-stop  -mb-step  -mregister-names  -mno-sdata @gol
616 -mconstant-gp  -mauto-pic  -minline-divide-min-latency @gol
617 -minline-divide-max-throughput  -mno-dwarf2-asm @gol
618 -mfixed-range=@var{register-range}}
619
620 @emph{D30V Options}
621 @gccoptlist{
622 -mextmem  -mextmemory  -monchip  -mno-asm-optimize  -masm-optimize @gol
623 -mbranch-cost=@var{n} -mcond-exec=@var{n}}
624
625 @emph{S/390 and zSeries Options}
626 @gccoptlist{
627 -mhard-float  -msoft-float  -mbackchain  -mno-backchain @gol
628 -msmall-exec  -mno-small-exec  -mmvcle -mno-mvcle @gol
629 -m64 -m31 -mdebug -mno-debug}
630
631 @emph{CRIS Options}
632 @gccoptlist{
633 -mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
634 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
635 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
636 -mstack-align -mdata-align -mconst-align @gol
637 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
638 -melf -maout -melinux -mlinux -sim -sim2}
639
640 @emph{PDP-11 Options}
641 @gccoptlist{
642 -mfpu  -msoft-float  -mac0  -mno-ac0  -m40  -m45  -m10 @gol
643 -mbcopy  -mbcopy-builtin  -mint32  -mno-int16 @gol
644 -mint16  -mno-int32  -mfloat32  -mno-float64 @gol
645 -mfloat64  -mno-float32  -mabshi  -mno-abshi @gol
646 -mbranch-expensive  -mbranch-cheap @gol
647 -msplit  -mno-split  -munix-asm  -mdec-asm}
648
649 @emph{Xstormy16 Options}
650 @gccoptlist{
651 -msim}
652
653 @emph{Xtensa Options}
654 @gccoptlist{
655 -mbig-endian -mlittle-endian @gol
656 -mdensity -mno-density @gol
657 -mmac16 -mno-mac16 @gol
658 -mmul16 -mno-mul16 @gol
659 -mmul32 -mno-mul32 @gol
660 -mnsa -mno-nsa @gol
661 -mminmax -mno-minmax @gol
662 -msext -mno-sext @gol
663 -mbooleans -mno-booleans @gol
664 -mhard-float -msoft-float @gol
665 -mfused-madd -mno-fused-madd @gol
666 -mserialize-volatile -mno-serialize-volatile @gol
667 -mtext-section-literals -mno-text-section-literals @gol
668 -mtarget-align -mno-target-align @gol
669 -mlongcalls -mno-longcalls}
670
671 @item Code Generation Options
672 @xref{Code Gen Options,,Options for Code Generation Conventions}.
673 @gccoptlist{
674 -fcall-saved-@var{reg}  -fcall-used-@var{reg} @gol
675 -ffixed-@var{reg} -fexceptions @gol
676 -fnon-call-exceptions  -funwind-tables @gol
677 -fasynchronous-unwind-tables @gol
678 -finhibit-size-directive  -finstrument-functions @gol
679 -fno-common  -fno-ident  -fno-gnu-linker @gol
680 -fpcc-struct-return  -fpic  -fPIC @gol
681 -freg-struct-return  -fshared-data  -fshort-enums @gol
682 -fshort-double  -fvolatile @gol
683 -fvolatile-global  -fvolatile-static @gol
684 -fverbose-asm  -fpack-struct  -fstack-check @gol
685 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
686 -fargument-alias  -fargument-noalias @gol
687 -fargument-noalias-global  -fleading-underscore -ftls-model=@var{model}}
688 @end table
689
690 @menu
691 * Overall Options::     Controlling the kind of output:
692                         an executable, object files, assembler files,
693                         or preprocessed source.
694 * C Dialect Options::   Controlling the variant of C language compiled.
695 * C++ Dialect Options:: Variations on C++.
696 * Objective-C Dialect Options:: Variations on Objective-C.
697 * Language Independent Options:: Controlling how diagnostics should be
698                         formatted.
699 * Warning Options::     How picky should the compiler be?
700 * Debugging Options::   Symbol tables, measurements, and debugging dumps.
701 * Optimize Options::    How much optimization?
702 * Preprocessor Options:: Controlling header files and macro definitions.
703                          Also, getting dependency information for Make.
704 * Assembler Options::   Passing options to the assembler.
705 * Link Options::        Specifying libraries and so on.
706 * Directory Options::   Where to find header files and libraries.
707                         Where to find the compiler executable files.
708 * Spec Files::          How to pass switches to sub-processes.
709 * Target Options::      Running a cross-compiler, or an old version of GCC.
710 @end menu
711
712 @node Overall Options
713 @section Options Controlling the Kind of Output
714
715 Compilation can involve up to four stages: preprocessing, compilation
716 proper, assembly and linking, always in that order.  The first three
717 stages apply to an individual source file, and end by producing an
718 object file; linking combines all the object files (those newly
719 compiled, and those specified as input) into an executable file.
720
721 @cindex file name suffix
722 For any given input file, the file name suffix determines what kind of
723 compilation is done:
724
725 @table @gcctabopt
726 @item @var{file}.c
727 C source code which must be preprocessed.
728
729 @item @var{file}.i
730 C source code which should not be preprocessed.
731
732 @item @var{file}.ii
733 C++ source code which should not be preprocessed.
734
735 @item @var{file}.m
736 Objective-C source code.  Note that you must link with the library
737 @file{libobjc.a} to make an Objective-C program work.
738
739 @item @var{file}.mi
740 Objective-C source code which should not be preprocessed.
741
742 @item @var{file}.h
743 C header file (not to be compiled or linked).
744
745 @item @var{file}.cc
746 @itemx @var{file}.cp
747 @itemx @var{file}.cxx
748 @itemx @var{file}.cpp
749 @itemx @var{file}.c++
750 @itemx @var{file}.C
751 C++ source code which must be preprocessed.  Note that in @samp{.cxx},
752 the last two letters must both be literally @samp{x}.  Likewise,
753 @samp{.C} refers to a literal capital C@.
754
755 @item @var{file}.f
756 @itemx @var{file}.for
757 @itemx @var{file}.FOR
758 Fortran source code which should not be preprocessed.
759
760 @item @var{file}.F
761 @itemx @var{file}.fpp
762 @itemx @var{file}.FPP
763 Fortran source code which must be preprocessed (with the traditional
764 preprocessor).
765
766 @item @var{file}.r
767 Fortran source code which must be preprocessed with a RATFOR
768 preprocessor (not included with GCC)@.
769
770 @xref{Overall Options,,Options Controlling the Kind of Output, g77,
771 Using and Porting GNU Fortran}, for more details of the handling of
772 Fortran input files.
773
774 @c FIXME: Descriptions of Java file types.
775 @c @var{file}.java
776 @c @var{file}.class
777 @c @var{file}.zip
778 @c @var{file}.jar
779
780 @item @var{file}.ads
781 Ada source code file which contains a library unit declaration (a
782 declaration of a package, subprogram, or generic, or a generic
783 instantiation), or a library unit renaming declaration (a package,
784 generic, or subprogram renaming declaration).  Such files are also
785 called @dfn{specs}.
786
787 @itemx @var{file}.adb
788 Ada source code file containing a library unit body (a subprogram or
789 package body).  Such files are also called @dfn{bodies}.
790
791 @c GCC also knows about some suffixes for languages not yet included:
792 @c Pascal:
793 @c @var{file}.p
794 @c @var{file}.pas
795
796 @item @var{file}.s
797 Assembler code.
798
799 @item @var{file}.S
800 Assembler code which must be preprocessed.
801
802 @item @var{other}
803 An object file to be fed straight into linking.
804 Any file name with no recognized suffix is treated this way.
805 @end table
806
807 @opindex x
808 You can specify the input language explicitly with the @option{-x} option:
809
810 @table @gcctabopt
811 @item -x @var{language}
812 Specify explicitly the @var{language} for the following input files
813 (rather than letting the compiler choose a default based on the file
814 name suffix).  This option applies to all following input files until
815 the next @option{-x} option.  Possible values for @var{language} are:
816 @example
817 c  c-header  cpp-output
818 c++  c++-cpp-output
819 objective-c  objc-cpp-output
820 assembler  assembler-with-cpp
821 ada
822 f77  f77-cpp-input  ratfor
823 java
824 treelang
825 @end example
826
827 @item -x none
828 Turn off any specification of a language, so that subsequent files are
829 handled according to their file name suffixes (as they are if @option{-x}
830 has not been used at all).
831
832 @item -pass-exit-codes
833 @opindex pass-exit-codes
834 Normally the @command{gcc} program will exit with the code of 1 if any
835 phase of the compiler returns a non-success return code.  If you specify
836 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
837 numerically highest error produced by any phase that returned an error
838 indication.
839 @end table
840
841 If you only want some of the stages of compilation, you can use
842 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
843 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
844 @command{gcc} is to stop.  Note that some combinations (for example,
845 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
846
847 @table @gcctabopt
848 @item -c
849 @opindex c
850 Compile or assemble the source files, but do not link.  The linking
851 stage simply is not done.  The ultimate output is in the form of an
852 object file for each source file.
853
854 By default, the object file name for a source file is made by replacing
855 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
856
857 Unrecognized input files, not requiring compilation or assembly, are
858 ignored.
859
860 @item -S
861 @opindex S
862 Stop after the stage of compilation proper; do not assemble.  The output
863 is in the form of an assembler code file for each non-assembler input
864 file specified.
865
866 By default, the assembler file name for a source file is made by
867 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
868
869 Input files that don't require compilation are ignored.
870
871 @item -E
872 @opindex E
873 Stop after the preprocessing stage; do not run the compiler proper.  The
874 output is in the form of preprocessed source code, which is sent to the
875 standard output.
876
877 Input files which don't require preprocessing are ignored.
878
879 @cindex output file option
880 @item -o @var{file}
881 @opindex o
882 Place output in file @var{file}.  This applies regardless to whatever
883 sort of output is being produced, whether it be an executable file,
884 an object file, an assembler file or preprocessed C code.
885
886 Since only one output file can be specified, it does not make sense to
887 use @option{-o} when compiling more than one input file, unless you are
888 producing an executable file as output.
889
890 If @option{-o} is not specified, the default is to put an executable file
891 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
892 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
893 all preprocessed C source on standard output.
894
895 @item -v
896 @opindex v
897 Print (on standard error output) the commands executed to run the stages
898 of compilation.  Also print the version number of the compiler driver
899 program and of the preprocessor and the compiler proper.
900
901 @item -###
902 @opindex ###
903 Like @option{-v} except the commands are not executed and all command
904 arguments are quoted.  This is useful for shell scripts to capture the
905 driver-generated command lines.
906
907 @item -pipe
908 @opindex pipe
909 Use pipes rather than temporary files for communication between the
910 various stages of compilation.  This fails to work on some systems where
911 the assembler is unable to read from a pipe; but the GNU assembler has
912 no trouble.
913
914 @item --help
915 @opindex help
916 Print (on the standard output) a description of the command line options
917 understood by @command{gcc}.  If the @option{-v} option is also specified
918 then @option{--help} will also be passed on to the various processes
919 invoked by @command{gcc}, so that they can display the command line options
920 they accept.  If the @option{-W} option is also specified then command
921 line options which have no documentation associated with them will also
922 be displayed.
923
924 @item --target-help
925 @opindex target-help
926 Print (on the standard output) a description of target specific command
927 line options for each tool.
928 @end table
929
930 @node Invoking G++
931 @section Compiling C++ Programs
932
933 @cindex suffixes for C++ source
934 @cindex C++ source file suffixes
935 C++ source files conventionally use one of the suffixes @samp{.C},
936 @samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx};
937 preprocessed C++ files use the suffix @samp{.ii}.  GCC recognizes
938 files with these names and compiles them as C++ programs even if you
939 call the compiler the same way as for compiling C programs (usually with
940 the name @command{gcc}).
941
942 @findex g++
943 @findex c++
944 However, C++ programs often require class libraries as well as a
945 compiler that understands the C++ language---and under some
946 circumstances, you might want to compile programs from standard input,
947 or otherwise without a suffix that flags them as C++ programs.
948 @command{g++} is a program that calls GCC with the default language
949 set to C++, and automatically specifies linking against the C++
950 library.  On many systems, @command{g++} is also
951 installed with the name @command{c++}.
952
953 @cindex invoking @command{g++}
954 When you compile C++ programs, you may specify many of the same
955 command-line options that you use for compiling programs in any
956 language; or command-line options meaningful for C and related
957 languages; or options that are meaningful only for C++ programs.
958 @xref{C Dialect Options,,Options Controlling C Dialect}, for
959 explanations of options for languages related to C@.
960 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
961 explanations of options that are meaningful only for C++ programs.
962
963 @node C Dialect Options
964 @section Options Controlling C Dialect
965 @cindex dialect options
966 @cindex language dialect options
967 @cindex options, dialect
968
969 The following options control the dialect of C (or languages derived
970 from C, such as C++ and Objective-C) that the compiler accepts:
971
972 @table @gcctabopt
973 @cindex ANSI support
974 @cindex ISO support
975 @item -ansi
976 @opindex ansi
977 In C mode, support all ISO C90 programs.  In C++ mode,
978 remove GNU extensions that conflict with ISO C++.
979
980 This turns off certain features of GCC that are incompatible with ISO
981 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
982 such as the @code{asm} and @code{typeof} keywords, and
983 predefined macros such as @code{unix} and @code{vax} that identify the
984 type of system you are using.  It also enables the undesirable and
985 rarely used ISO trigraph feature.  For the C compiler,
986 it disables recognition of C++ style @samp{//} comments as well as
987 the @code{inline} keyword.
988
989 The alternate keywords @code{__asm__}, @code{__extension__},
990 @code{__inline__} and @code{__typeof__} continue to work despite
991 @option{-ansi}.  You would not want to use them in an ISO C program, of
992 course, but it is useful to put them in header files that might be included
993 in compilations done with @option{-ansi}.  Alternate predefined macros
994 such as @code{__unix__} and @code{__vax__} are also available, with or
995 without @option{-ansi}.
996
997 The @option{-ansi} option does not cause non-ISO programs to be
998 rejected gratuitously.  For that, @option{-pedantic} is required in
999 addition to @option{-ansi}.  @xref{Warning Options}.
1000
1001 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1002 option is used.  Some header files may notice this macro and refrain
1003 from declaring certain functions or defining certain macros that the
1004 ISO standard doesn't call for; this is to avoid interfering with any
1005 programs that might use these names for other things.
1006
1007 Functions which would normally be built in but do not have semantics
1008 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1009 functions with @option{-ansi} is used.  @xref{Other Builtins,,Other
1010 built-in functions provided by GCC}, for details of the functions
1011 affected.
1012
1013 @item -std=
1014 @opindex std
1015 Determine the language standard.  This option is currently only
1016 supported when compiling C or C++.  A value for this option must be
1017 provided; possible values are
1018
1019 @table @samp
1020 @item c89
1021 @itemx iso9899:1990
1022 ISO C90 (same as @option{-ansi}).
1023
1024 @item iso9899:199409
1025 ISO C90 as modified in amendment 1.
1026
1027 @item c99
1028 @itemx c9x
1029 @itemx iso9899:1999
1030 @itemx iso9899:199x
1031 ISO C99.  Note that this standard is not yet fully supported; see
1032 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information.  The
1033 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1034
1035 @item gnu89
1036 Default, ISO C90 plus GNU extensions (including some C99 features).
1037
1038 @item gnu99
1039 @item gnu9x
1040 ISO C99 plus GNU extensions.  When ISO C99 is fully implemented in GCC,
1041 this will become the default.  The name @samp{gnu9x} is deprecated.
1042
1043 @item c++98
1044 The 1998 ISO C++ standard plus amendments.
1045
1046 @item gnu++98
1047 The same as @option{-std=c++98} plus GNU extensions.  This is the
1048 default for C++ code.
1049 @end table
1050
1051 Even when this option is not specified, you can still use some of the
1052 features of newer standards in so far as they do not conflict with
1053 previous C standards.  For example, you may use @code{__restrict__} even
1054 when @option{-std=c99} is not specified.
1055
1056 The @option{-std} options specifying some version of ISO C have the same
1057 effects as @option{-ansi}, except that features that were not in ISO C90
1058 but are in the specified version (for example, @samp{//} comments and
1059 the @code{inline} keyword in ISO C99) are not disabled.
1060
1061 @xref{Standards,,Language Standards Supported by GCC}, for details of
1062 these standard versions.
1063
1064 @item -aux-info @var{filename}
1065 @opindex aux-info
1066 Output to the given filename prototyped declarations for all functions
1067 declared and/or defined in a translation unit, including those in header
1068 files.  This option is silently ignored in any language other than C@.
1069
1070 Besides declarations, the file indicates, in comments, the origin of
1071 each declaration (source file and line), whether the declaration was
1072 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1073 @samp{O} for old, respectively, in the first character after the line
1074 number and the colon), and whether it came from a declaration or a
1075 definition (@samp{C} or @samp{F}, respectively, in the following
1076 character).  In the case of function definitions, a K&R-style list of
1077 arguments followed by their declarations is also provided, inside
1078 comments, after the declaration.
1079
1080 @item -fno-asm
1081 @opindex fno-asm
1082 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1083 keyword, so that code can use these words as identifiers.  You can use
1084 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1085 instead.  @option{-ansi} implies @option{-fno-asm}.
1086
1087 In C++, this switch only affects the @code{typeof} keyword, since
1088 @code{asm} and @code{inline} are standard keywords.  You may want to
1089 use the @option{-fno-gnu-keywords} flag instead, which has the same
1090 effect.  In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1091 switch only affects the @code{asm} and @code{typeof} keywords, since
1092 @code{inline} is a standard keyword in ISO C99.
1093
1094 @item -fno-builtin
1095 @itemx -fno-builtin-@var{function}
1096 @opindex fno-builtin
1097 @cindex built-in functions
1098 Don't recognize built-in functions that do not begin with
1099 @samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
1100 functions provided by GCC}, for details of the functions affected,
1101 including those which are not built-in functions when @option{-ansi} or
1102 @option{-std} options for strict ISO C conformance are used because they
1103 do not have an ISO standard meaning.
1104
1105 GCC normally generates special code to handle certain built-in functions
1106 more efficiently; for instance, calls to @code{alloca} may become single
1107 instructions that adjust the stack directly, and calls to @code{memcpy}
1108 may become inline copy loops.  The resulting code is often both smaller
1109 and faster, but since the function calls no longer appear as such, you
1110 cannot set a breakpoint on those calls, nor can you change the behavior
1111 of the functions by linking with a different library.
1112
1113 With the @option{-fno-builtin-@var{function}} option
1114 only the built-in function @var{function} is
1115 disabled.  @var{function} must not begin with @samp{__builtin_}.  If a
1116 function is named this is not built-in in this version of GCC, this
1117 option is ignored.  There is no corresponding
1118 @option{-fbuiltin-@var{function}} option; if you wish to enable
1119 built-in functions selectively when using @option{-fno-builtin} or
1120 @option{-ffreestanding}, you may define macros such as:
1121
1122 @smallexample
1123 #define abs(n)          __builtin_abs ((n))
1124 #define strcpy(d, s)    __builtin_strcpy ((d), (s))
1125 @end smallexample
1126
1127 @item -fhosted
1128 @opindex fhosted
1129 @cindex hosted environment
1130
1131 Assert that compilation takes place in a hosted environment.  This implies
1132 @option{-fbuiltin}.  A hosted environment is one in which the
1133 entire standard library is available, and in which @code{main} has a return
1134 type of @code{int}.  Examples are nearly everything except a kernel.
1135 This is equivalent to @option{-fno-freestanding}.
1136
1137 @item -ffreestanding
1138 @opindex ffreestanding
1139 @cindex hosted environment
1140
1141 Assert that compilation takes place in a freestanding environment.  This
1142 implies @option{-fno-builtin}.  A freestanding environment
1143 is one in which the standard library may not exist, and program startup may
1144 not necessarily be at @code{main}.  The most obvious example is an OS kernel.
1145 This is equivalent to @option{-fno-hosted}.
1146
1147 @xref{Standards,,Language Standards Supported by GCC}, for details of
1148 freestanding and hosted environments.
1149
1150 @item -fms-extensions
1151 @opindex fms-extensions
1152 Accept some non-standard constructs used in Microsoft header files.
1153
1154 @item -trigraphs
1155 @opindex trigraphs
1156 Support ISO C trigraphs.  The @option{-ansi} option (and @option{-std}
1157 options for strict ISO C conformance) implies @option{-trigraphs}.
1158
1159 @cindex traditional C language
1160 @cindex C language, traditional
1161 @item -traditional
1162 @itemx -traditional-cpp
1163 @opindex traditional-cpp
1164 @opindex traditional
1165 Formerly, these options caused GCC to attempt to emulate a pre-standard
1166 C compiler.  They are now only supported with the @option{-E} switch.
1167 The preprocessor continues to support a pre-standard mode.  See the GNU
1168 CPP manual for details.
1169
1170 @item -fcond-mismatch
1171 @opindex fcond-mismatch
1172 Allow conditional expressions with mismatched types in the second and
1173 third arguments.  The value of such an expression is void.  This option
1174 is not supported for C++.
1175
1176 @item -funsigned-char
1177 @opindex funsigned-char
1178 Let the type @code{char} be unsigned, like @code{unsigned char}.
1179
1180 Each kind of machine has a default for what @code{char} should
1181 be.  It is either like @code{unsigned char} by default or like
1182 @code{signed char} by default.
1183
1184 Ideally, a portable program should always use @code{signed char} or
1185 @code{unsigned char} when it depends on the signedness of an object.
1186 But many programs have been written to use plain @code{char} and
1187 expect it to be signed, or expect it to be unsigned, depending on the
1188 machines they were written for.  This option, and its inverse, let you
1189 make such a program work with the opposite default.
1190
1191 The type @code{char} is always a distinct type from each of
1192 @code{signed char} or @code{unsigned char}, even though its behavior
1193 is always just like one of those two.
1194
1195 @item -fsigned-char
1196 @opindex fsigned-char
1197 Let the type @code{char} be signed, like @code{signed char}.
1198
1199 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1200 the negative form of @option{-funsigned-char}.  Likewise, the option
1201 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1202
1203 @item -fsigned-bitfields
1204 @itemx -funsigned-bitfields
1205 @itemx -fno-signed-bitfields
1206 @itemx -fno-unsigned-bitfields
1207 @opindex fsigned-bitfields
1208 @opindex funsigned-bitfields
1209 @opindex fno-signed-bitfields
1210 @opindex fno-unsigned-bitfields
1211 These options control whether a bit-field is signed or unsigned, when the
1212 declaration does not use either @code{signed} or @code{unsigned}.  By
1213 default, such a bit-field is signed, because this is consistent: the
1214 basic integer types such as @code{int} are signed types.
1215
1216 @item -fwritable-strings
1217 @opindex fwritable-strings
1218 Store string constants in the writable data segment and don't uniquize
1219 them.  This is for compatibility with old programs which assume they can
1220 write into string constants.
1221
1222 Writing into string constants is a very bad idea; ``constants'' should
1223 be constant.
1224
1225 @item -fshort-wchar
1226 @opindex fshort-wchar
1227 Override the underlying type for @samp{wchar_t} to be @samp{short
1228 unsigned int} instead of the default for the target.  This option is
1229 useful for building programs to run under WINE@.
1230 @end table
1231
1232 @node C++ Dialect Options
1233 @section Options Controlling C++ Dialect
1234
1235 @cindex compiler options, C++
1236 @cindex C++ options, command line
1237 @cindex options, C++
1238 This section describes the command-line options that are only meaningful
1239 for C++ programs; but you can also use most of the GNU compiler options
1240 regardless of what language your program is in.  For example, you
1241 might compile a file @code{firstClass.C} like this:
1242
1243 @example
1244 g++ -g -frepo -O -c firstClass.C
1245 @end example
1246
1247 @noindent
1248 In this example, only @option{-frepo} is an option meant
1249 only for C++ programs; you can use the other options with any
1250 language supported by GCC@.
1251
1252 Here is a list of options that are @emph{only} for compiling C++ programs:
1253
1254 @table @gcctabopt
1255 @item -fno-access-control
1256 @opindex fno-access-control
1257 Turn off all access checking.  This switch is mainly useful for working
1258 around bugs in the access control code.
1259
1260 @item -fcheck-new
1261 @opindex fcheck-new
1262 Check that the pointer returned by @code{operator new} is non-null
1263 before attempting to modify the storage allocated.  The current Working
1264 Paper requires that @code{operator new} never return a null pointer, so
1265 this check is normally unnecessary.
1266
1267 An alternative to using this option is to specify that your
1268 @code{operator new} does not throw any exceptions; if you declare it
1269 @samp{throw()}, G++ will check the return value.  See also @samp{new
1270 (nothrow)}.
1271
1272 @item -fconserve-space
1273 @opindex fconserve-space
1274 Put uninitialized or runtime-initialized global variables into the
1275 common segment, as C does.  This saves space in the executable at the
1276 cost of not diagnosing duplicate definitions.  If you compile with this
1277 flag and your program mysteriously crashes after @code{main()} has
1278 completed, you may have an object that is being destroyed twice because
1279 two definitions were merged.
1280
1281 This option is no longer useful on most targets, now that support has
1282 been added for putting variables into BSS without making them common.
1283
1284 @item -fno-const-strings
1285 @opindex fno-const-strings
1286 Give string constants type @code{char *} instead of type @code{const
1287 char *}.  By default, G++ uses type @code{const char *} as required by
1288 the standard.  Even if you use @option{-fno-const-strings}, you cannot
1289 actually modify the value of a string constant, unless you also use
1290 @option{-fwritable-strings}.
1291
1292 This option might be removed in a future release of G++.  For maximum
1293 portability, you should structure your code so that it works with
1294 string constants that have type @code{const char *}.
1295
1296 @item -fdollars-in-identifiers
1297 @opindex fdollars-in-identifiers
1298 Accept @samp{$} in identifiers.  You can also explicitly prohibit use of
1299 @samp{$} with the option @option{-fno-dollars-in-identifiers}.  (GNU C allows
1300 @samp{$} by default on most target systems, but there are a few exceptions.)
1301 Traditional C allowed the character @samp{$} to form part of
1302 identifiers.  However, ISO C and C++ forbid @samp{$} in identifiers.
1303
1304 @item -fno-elide-constructors
1305 @opindex fno-elide-constructors
1306 The C++ standard allows an implementation to omit creating a temporary
1307 which is only used to initialize another object of the same type.
1308 Specifying this option disables that optimization, and forces G++ to
1309 call the copy constructor in all cases.
1310
1311 @item -fno-enforce-eh-specs
1312 @opindex fno-enforce-eh-specs
1313 Don't check for violation of exception specifications at runtime.  This
1314 option violates the C++ standard, but may be useful for reducing code
1315 size in production builds, much like defining @samp{NDEBUG}.  The compiler
1316 will still optimize based on the exception specifications.
1317
1318 @item -fexternal-templates
1319 @opindex fexternal-templates
1320
1321 Cause @samp{#pragma interface} and @samp{implementation} to apply to
1322 template instantiation; template instances are emitted or not according
1323 to the location of the template definition.  @xref{Template
1324 Instantiation}, for more information.
1325
1326 This option is deprecated.
1327
1328 @item -falt-external-templates
1329 @opindex falt-external-templates
1330 Similar to @option{-fexternal-templates}, but template instances are
1331 emitted or not according to the place where they are first instantiated.
1332 @xref{Template Instantiation}, for more information.
1333
1334 This option is deprecated.
1335
1336 @item -ffor-scope
1337 @itemx -fno-for-scope
1338 @opindex ffor-scope
1339 @opindex fno-for-scope
1340 If @option{-ffor-scope} is specified, the scope of variables declared in
1341 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1342 as specified by the C++ standard.
1343 If @option{-fno-for-scope} is specified, the scope of variables declared in
1344 a @i{for-init-statement} extends to the end of the enclosing scope,
1345 as was the case in old versions of G++, and other (traditional)
1346 implementations of C++.
1347
1348 The default if neither flag is given to follow the standard,
1349 but to allow and give a warning for old-style code that would
1350 otherwise be invalid, or have different behavior.
1351
1352 @item -fno-gnu-keywords
1353 @opindex fno-gnu-keywords
1354 Do not recognize @code{typeof} as a keyword, so that code can use this
1355 word as an identifier.  You can use the keyword @code{__typeof__} instead.
1356 @option{-ansi} implies @option{-fno-gnu-keywords}.
1357
1358 @item -fno-implicit-templates
1359 @opindex fno-implicit-templates
1360 Never emit code for non-inline templates which are instantiated
1361 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1362 @xref{Template Instantiation}, for more information.
1363
1364 @item -fno-implicit-inline-templates
1365 @opindex fno-implicit-inline-templates
1366 Don't emit code for implicit instantiations of inline templates, either.
1367 The default is to handle inlines differently so that compiles with and
1368 without optimization will need the same set of explicit instantiations.
1369
1370 @item -fno-implement-inlines
1371 @opindex fno-implement-inlines
1372 To save space, do not emit out-of-line copies of inline functions
1373 controlled by @samp{#pragma implementation}.  This will cause linker
1374 errors if these functions are not inlined everywhere they are called.
1375
1376 @item -fms-extensions
1377 @opindex fms-extensions
1378 Disable pedantic warnings about constructs used in MFC, such as implicit
1379 int and getting a pointer to member function via non-standard syntax.
1380
1381 @item -fno-nonansi-builtins
1382 @opindex fno-nonansi-builtins
1383 Disable built-in declarations of functions that are not mandated by
1384 ANSI/ISO C@.  These include @code{ffs}, @code{alloca}, @code{_exit},
1385 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1386
1387 @item -fno-operator-names
1388 @opindex fno-operator-names
1389 Do not treat the operator name keywords @code{and}, @code{bitand},
1390 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1391 synonyms as keywords.
1392
1393 @item -fno-optional-diags
1394 @opindex fno-optional-diags
1395 Disable diagnostics that the standard says a compiler does not need to
1396 issue.  Currently, the only such diagnostic issued by G++ is the one for
1397 a name having multiple meanings within a class.
1398
1399 @item -fpermissive
1400 @opindex fpermissive
1401 Downgrade messages about nonconformant code from errors to warnings.  By
1402 default, G++ effectively sets @option{-pedantic-errors} without
1403 @option{-pedantic}; this option reverses that.  This behavior and this
1404 option are superseded by @option{-pedantic}, which works as it does for GNU C@.
1405
1406 @item -frepo
1407 @opindex frepo
1408 Enable automatic template instantiation at link time.  This option also
1409 implies @option{-fno-implicit-templates}.  @xref{Template
1410 Instantiation}, for more information.
1411
1412 @item -fno-rtti
1413 @opindex fno-rtti
1414 Disable generation of information about every class with virtual
1415 functions for use by the C++ runtime type identification features
1416 (@samp{dynamic_cast} and @samp{typeid}).  If you don't use those parts
1417 of the language, you can save some space by using this flag.  Note that
1418 exception handling uses the same information, but it will generate it as
1419 needed.
1420
1421 @item -fstats
1422 @opindex fstats
1423 Emit statistics about front-end processing at the end of the compilation.
1424 This information is generally only useful to the G++ development team.
1425
1426 @item -ftemplate-depth-@var{n}
1427 @opindex ftemplate-depth
1428 Set the maximum instantiation depth for template classes to @var{n}.
1429 A limit on the template instantiation depth is needed to detect
1430 endless recursions during template class instantiation.  ANSI/ISO C++
1431 conforming programs must not rely on a maximum depth greater than 17.
1432
1433 @item -fuse-cxa-atexit
1434 @opindex fuse-cxa-atexit
1435 Register destructors for objects with static storage duration with the
1436 @code{__cxa_atexit} function rather than the @code{atexit} function.
1437 This option is required for fully standards-compliant handling of static
1438 destructors, but will only work if your C library supports
1439 @code{__cxa_atexit}.
1440
1441 @item -fvtable-gc
1442 @opindex fvtable-gc
1443 Emit special relocations for vtables and virtual function references
1444 so that the linker can identify unused virtual functions and zero out
1445 vtable slots that refer to them.  This is most useful with
1446 @option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to
1447 also discard the functions themselves.
1448
1449 This optimization requires GNU as and GNU ld.  Not all systems support
1450 this option.  @option{-Wl,--gc-sections} is ignored without @option{-static}.
1451
1452 @item -fno-weak
1453 @opindex fno-weak
1454 Do not use weak symbol support, even if it is provided by the linker.
1455 By default, G++ will use weak symbols if they are available.  This
1456 option exists only for testing, and should not be used by end-users;
1457 it will result in inferior code and has no benefits.  This option may
1458 be removed in a future release of G++.
1459
1460 @item -nostdinc++
1461 @opindex nostdinc++
1462 Do not search for header files in the standard directories specific to
1463 C++, but do still search the other standard directories.  (This option
1464 is used when building the C++ library.)
1465 @end table
1466
1467 In addition, these optimization, warning, and code generation options
1468 have meanings only for C++ programs:
1469
1470 @table @gcctabopt
1471 @item -fno-default-inline
1472 @opindex fno-default-inline
1473 Do not assume @samp{inline} for functions defined inside a class scope.
1474 @xref{Optimize Options,,Options That Control Optimization}.  Note that these
1475 functions will have linkage like inline functions; they just won't be
1476 inlined by default.
1477
1478 @item -Wabi @r{(C++ only)}
1479 @opindex Wabi
1480 Warn when G++ generates code that is probably not compatible with the
1481 vendor-neutral C++ ABI.  Although an effort has been made to warn about
1482 all such cases, there are probably some cases that are not warned about, 
1483 even though G++ is generating incompatible code.  There may also be
1484 cases where warnings are emitted even though the code that is generated
1485 will be compatible.
1486
1487 You should rewrite your code to avoid these warnings if you are
1488 concerned about the fact that code generated by G++ may not be binary
1489 compatible with code generated by other compilers.
1490
1491 The known incompatibilites at this point include:
1492
1493 @itemize @bullet
1494
1495 @item
1496 Incorrect handling of tail-padding for bit-fields.  G++ may attempt to
1497 pack data into the same byte as a base class.  For example:
1498
1499 @smallexample
1500 struct A @{ virtual void f(); int f1 : 1; @};
1501 struct B : public A @{ int f2 : 1; @};
1502 @end smallexample
1503
1504 @noindent
1505 In this case, G++ will place @code{B::f2} into the same byte
1506 as@code{A::f1}; other compilers will not.  You can avoid this problem 
1507 by explicitly padding @code{A} so that its size is a multiple of the
1508 byte size on your platform; that will cause G++ and other compilers to
1509 layout @code{B} identically.
1510
1511 @item
1512 Incorrect handling of tail-padding for virtual bases.  G++ does not use
1513 tail padding when laying out virtual bases.  For example:
1514
1515 @smallexample
1516 struct A @{ virtual void f(); char c1; @};
1517 struct B @{ B(); char c2; @};
1518 struct C : public A, public virtual B @{@};
1519 @end smallexample
1520
1521 @noindent
1522 In this case, G++ will not place @code{B} into the tail-padding for
1523 @code{A}; other compilers will.  You can avoid this problem by
1524 explicitly padding @code{A} so that its size is a multiple of its
1525 alignment (ignoring virtual base classes); that will cause G++ and other
1526 compilers to layout @code{C} identically.
1527
1528 @end itemize
1529
1530 @item -Wctor-dtor-privacy @r{(C++ only)}
1531 @opindex Wctor-dtor-privacy
1532 Warn when a class seems unusable, because all the constructors or
1533 destructors in a class are private and the class has no friends or
1534 public static member functions.
1535
1536 @item -Wnon-virtual-dtor @r{(C++ only)}
1537 @opindex Wnon-virtual-dtor
1538 Warn when a class declares a non-virtual destructor that should probably
1539 be virtual, because it looks like the class will be used polymorphically.
1540
1541 @item -Wreorder @r{(C++ only)}
1542 @opindex Wreorder
1543 @cindex reordering, warning
1544 @cindex warning for reordering of member initializers
1545 Warn when the order of member initializers given in the code does not
1546 match the order in which they must be executed.  For instance:
1547
1548 @smallexample
1549 struct A @{
1550   int i;
1551   int j;
1552   A(): j (0), i (1) @{ @}
1553 @};
1554 @end smallexample
1555
1556 Here the compiler will warn that the member initializers for @samp{i}
1557 and @samp{j} will be rearranged to match the declaration order of the
1558 members.
1559 @end table
1560
1561 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1562
1563 @table @gcctabopt
1564 @item -Weffc++ @r{(C++ only)}
1565 @opindex Weffc++
1566 Warn about violations of the following style guidelines from Scott Meyers'
1567 @cite{Effective C++} book:
1568
1569 @itemize @bullet
1570 @item
1571 Item 11:  Define a copy constructor and an assignment operator for classes
1572 with dynamically allocated memory.
1573
1574 @item
1575 Item 12:  Prefer initialization to assignment in constructors.
1576
1577 @item
1578 Item 14:  Make destructors virtual in base classes.
1579
1580 @item
1581 Item 15:  Have @code{operator=} return a reference to @code{*this}.
1582
1583 @item
1584 Item 23:  Don't try to return a reference when you must return an object.
1585
1586 @end itemize
1587
1588 and about violations of the following style guidelines from Scott Meyers'
1589 @cite{More Effective C++} book:
1590
1591 @itemize @bullet
1592 @item
1593 Item 6:  Distinguish between prefix and postfix forms of increment and
1594 decrement operators.
1595
1596 @item
1597 Item 7:  Never overload @code{&&}, @code{||}, or @code{,}.
1598
1599 @end itemize
1600
1601 If you use this option, you should be aware that the standard library
1602 headers do not obey all of these guidelines; you can use @samp{grep -v}
1603 to filter out those warnings.
1604
1605 @item -Wno-deprecated @r{(C++ only)}
1606 @opindex Wno-deprecated
1607 Do not warn about usage of deprecated features.  @xref{Deprecated Features}.
1608
1609 @item -Wno-non-template-friend @r{(C++ only)}
1610 @opindex Wno-non-template-friend
1611 Disable warnings when non-templatized friend functions are declared
1612 within a template.  With the advent of explicit template specification
1613 support in G++, if the name of the friend is an unqualified-id (i.e.,
1614 @samp{friend foo(int)}), the C++ language specification demands that the
1615 friend declare or define an ordinary, nontemplate function.  (Section
1616 14.5.3).  Before G++ implemented explicit specification, unqualified-ids
1617 could be interpreted as a particular specialization of a templatized
1618 function.  Because this non-conforming behavior is no longer the default
1619 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1620 check existing code for potential trouble spots, and is on by default.
1621 This new compiler behavior can be turned off with
1622 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1623 but disables the helpful warning.
1624
1625 @item -Wold-style-cast @r{(C++ only)}
1626 @opindex Wold-style-cast
1627 Warn if an old-style (C-style) cast to a non-void type is used within
1628 a C++ program.  The new-style casts (@samp{static_cast},
1629 @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to
1630 unintended effects, and much easier to grep for.
1631
1632 @item -Woverloaded-virtual @r{(C++ only)}
1633 @opindex Woverloaded-virtual
1634 @cindex overloaded virtual fn, warning
1635 @cindex warning for overloaded virtual fn
1636 Warn when a function declaration hides virtual functions from a
1637 base class.  For example, in:
1638
1639 @smallexample
1640 struct A @{
1641   virtual void f();
1642 @};
1643
1644 struct B: public A @{
1645   void f(int);
1646 @};
1647 @end smallexample
1648
1649 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1650 like this:
1651
1652 @smallexample
1653 B* b;
1654 b->f();
1655 @end smallexample
1656
1657 will fail to compile.
1658
1659 @item -Wno-pmf-conversions @r{(C++ only)}
1660 @opindex Wno-pmf-conversions
1661 Disable the diagnostic for converting a bound pointer to member function
1662 to a plain pointer.
1663
1664 @item -Wsign-promo @r{(C++ only)}
1665 @opindex Wsign-promo
1666 Warn when overload resolution chooses a promotion from unsigned or
1667 enumeral type to a signed type over a conversion to an unsigned type of
1668 the same size.  Previous versions of G++ would try to preserve
1669 unsignedness, but the standard mandates the current behavior.
1670
1671 @item -Wsynth @r{(C++ only)}
1672 @opindex Wsynth
1673 @cindex warning for synthesized methods
1674 @cindex synthesized methods, warning
1675 Warn when G++'s synthesis behavior does not match that of cfront.  For
1676 instance:
1677
1678 @smallexample
1679 struct A @{
1680   operator int ();
1681   A& operator = (int);
1682 @};
1683
1684 main ()
1685 @{
1686   A a,b;
1687   a = b;
1688 @}
1689 @end smallexample
1690
1691 In this example, G++ will synthesize a default @samp{A& operator =
1692 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1693 @end table
1694
1695 @node Objective-C Dialect Options
1696 @section Options Controlling Objective-C Dialect
1697
1698 @cindex compiler options, Objective-C
1699 @cindex Objective-C options, command line
1700 @cindex options, Objective-C
1701 This section describes the command-line options that are only meaningful
1702 for Objective-C programs; but you can also use most of the GNU compiler
1703 options regardless of what language your program is in.  For example,
1704 you might compile a file @code{some_class.m} like this:
1705
1706 @example
1707 gcc -g -fgnu-runtime -O -c some_class.m
1708 @end example
1709
1710 @noindent
1711 In this example, only @option{-fgnu-runtime} is an option meant only for
1712 Objective-C programs; you can use the other options with any language
1713 supported by GCC@.
1714
1715 Here is a list of options that are @emph{only} for compiling Objective-C
1716 programs:
1717
1718 @table @gcctabopt
1719 @item -fconstant-string-class=@var{class-name}
1720 @opindex fconstant-string-class
1721 Use @var{class-name} as the name of the class to instantiate for each
1722 literal string specified with the syntax @code{@@"@dots{}"}.  The default
1723 class name is @code{NXConstantString}.
1724
1725 @item -fgnu-runtime
1726 @opindex fgnu-runtime
1727 Generate object code compatible with the standard GNU Objective-C
1728 runtime.  This is the default for most types of systems.
1729
1730 @item -fnext-runtime
1731 @opindex fnext-runtime
1732 Generate output compatible with the NeXT runtime.  This is the default
1733 for NeXT-based systems, including Darwin and Mac OS X@.
1734
1735 @item -gen-decls
1736 @opindex gen-decls
1737 Dump interface declarations for all classes seen in the source file to a
1738 file named @file{@var{sourcename}.decl}.
1739
1740 @item -Wno-protocol
1741 @opindex Wno-protocol
1742 Do not warn if methods required by a protocol are not implemented
1743 in the class adopting it.
1744
1745 @item -Wselector
1746 @opindex Wselector
1747 Warn if a selector has multiple methods of different types defined.
1748
1749 @c not documented because only avail via -Wp
1750 @c @item -print-objc-runtime-info
1751
1752 @end table
1753
1754 @node Language Independent Options
1755 @section Options to Control Diagnostic Messages Formatting
1756 @cindex options to control diagnostics formatting
1757 @cindex diagnostic messages
1758 @cindex message formatting
1759
1760 Traditionally, diagnostic messages have been formatted irrespective of
1761 the output device's aspect (e.g.@: its width, @dots{}).  The options described
1762 below can be used to control the diagnostic messages formatting
1763 algorithm, e.g.@: how many characters per line, how often source location
1764 information should be reported.  Right now, only the C++ front end can
1765 honor these options.  However it is expected, in the near future, that
1766 the remaining front ends would be able to digest them correctly.
1767
1768 @table @gcctabopt
1769 @item -fmessage-length=@var{n}
1770 @opindex fmessage-length
1771 Try to format error messages so that they fit on lines of about @var{n}
1772 characters.  The default is 72 characters for @command{g++} and 0 for the rest of
1773 the front ends supported by GCC@.  If @var{n} is zero, then no
1774 line-wrapping will be done; each error message will appear on a single
1775 line.
1776
1777 @opindex fdiagnostics-show-location
1778 @item -fdiagnostics-show-location=once
1779 Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
1780 reporter to emit @emph{once} source location information; that is, in
1781 case the message is too long to fit on a single physical line and has to
1782 be wrapped, the source location won't be emitted (as prefix) again,
1783 over and over, in subsequent continuation lines.  This is the default
1784 behavior.
1785
1786 @item -fdiagnostics-show-location=every-line
1787 Only meaningful in line-wrapping mode.  Instructs the diagnostic
1788 messages reporter to emit the same source location information (as
1789 prefix) for physical lines that result from the process of breaking
1790 a message which is too long to fit on a single line.
1791
1792 @end table
1793
1794 @node Warning Options
1795 @section Options to Request or Suppress Warnings
1796 @cindex options to control warnings
1797 @cindex warning messages
1798 @cindex messages, warning
1799 @cindex suppressing warnings
1800
1801 Warnings are diagnostic messages that report constructions which
1802 are not inherently erroneous but which are risky or suggest there
1803 may have been an error.
1804
1805 You can request many specific warnings with options beginning @samp{-W},
1806 for example @option{-Wimplicit} to request warnings on implicit
1807 declarations.  Each of these specific warning options also has a
1808 negative form beginning @samp{-Wno-} to turn off warnings;
1809 for example, @option{-Wno-implicit}.  This manual lists only one of the
1810 two forms, whichever is not the default.
1811
1812 The following options control the amount and kinds of warnings produced
1813 by GCC; for further, language-specific options also refer to
1814 @ref{C++ Dialect Options} and @ref{Objective-C Dialect Options}.
1815
1816 @table @gcctabopt
1817 @cindex syntax checking
1818 @item -fsyntax-only
1819 @opindex fsyntax-only
1820 Check the code for syntax errors, but don't do anything beyond that.
1821
1822 @item -pedantic
1823 @opindex pedantic
1824 Issue all the warnings demanded by strict ISO C and ISO C++;
1825 reject all programs that use forbidden extensions, and some other
1826 programs that do not follow ISO C and ISO C++.  For ISO C, follows the
1827 version of the ISO C standard specified by any @option{-std} option used.
1828
1829 Valid ISO C and ISO C++ programs should compile properly with or without
1830 this option (though a rare few will require @option{-ansi} or a
1831 @option{-std} option specifying the required version of ISO C)@.  However,
1832 without this option, certain GNU extensions and traditional C and C++
1833 features are supported as well.  With this option, they are rejected.
1834
1835 @option{-pedantic} does not cause warning messages for use of the
1836 alternate keywords whose names begin and end with @samp{__}.  Pedantic
1837 warnings are also disabled in the expression that follows
1838 @code{__extension__}.  However, only system header files should use
1839 these escape routes; application programs should avoid them.
1840 @xref{Alternate Keywords}.
1841
1842 Some users try to use @option{-pedantic} to check programs for strict ISO
1843 C conformance.  They soon find that it does not do quite what they want:
1844 it finds some non-ISO practices, but not all---only those for which
1845 ISO C @emph{requires} a diagnostic, and some others for which
1846 diagnostics have been added.
1847
1848 A feature to report any failure to conform to ISO C might be useful in
1849 some instances, but would require considerable additional work and would
1850 be quite different from @option{-pedantic}.  We don't have plans to
1851 support such a feature in the near future.
1852
1853 Where the standard specified with @option{-std} represents a GNU
1854 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
1855 corresponding @dfn{base standard}, the version of ISO C on which the GNU
1856 extended dialect is based.  Warnings from @option{-pedantic} are given
1857 where they are required by the base standard.  (It would not make sense
1858 for such warnings to be given only for features not in the specified GNU
1859 C dialect, since by definition the GNU dialects of C include all
1860 features the compiler supports with the given option, and there would be
1861 nothing to warn about.)
1862
1863 @item -pedantic-errors
1864 @opindex pedantic-errors
1865 Like @option{-pedantic}, except that errors are produced rather than
1866 warnings.
1867
1868 @item -w
1869 @opindex w
1870 Inhibit all warning messages.
1871
1872 @item -Wno-import
1873 @opindex Wno-import
1874 Inhibit warning messages about the use of @samp{#import}.
1875
1876 @item -Wchar-subscripts
1877 @opindex Wchar-subscripts
1878 Warn if an array subscript has type @code{char}.  This is a common cause
1879 of error, as programmers often forget that this type is signed on some
1880 machines.
1881
1882 @item -Wcomment
1883 @opindex Wcomment
1884 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1885 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1886
1887 @item -Wformat
1888 @opindex Wformat
1889 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1890 the arguments supplied have types appropriate to the format string
1891 specified, and that the conversions specified in the format string make
1892 sense.  This includes standard functions, and others specified by format
1893 attributes (@pxref{Function Attributes}), in the @code{printf},
1894 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
1895 not in the C standard) families.
1896
1897 The formats are checked against the format features supported by GNU
1898 libc version 2.2.  These include all ISO C90 and C99 features, as well
1899 as features from the Single Unix Specification and some BSD and GNU
1900 extensions.  Other library implementations may not support all these
1901 features; GCC does not support warning about features that go beyond a
1902 particular library's limitations.  However, if @option{-pedantic} is used
1903 with @option{-Wformat}, warnings will be given about format features not
1904 in the selected standard version (but not for @code{strfmon} formats,
1905 since those are not in any version of the C standard).  @xref{C Dialect
1906 Options,,Options Controlling C Dialect}.
1907
1908 Since @option{-Wformat} also checks for null format arguments for
1909 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
1910
1911 @option{-Wformat} is included in @option{-Wall}.  For more control over some
1912 aspects of format checking, the options @option{-Wno-format-y2k},
1913 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
1914 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
1915 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
1916
1917 @item -Wno-format-y2k
1918 @opindex Wno-format-y2k
1919 If @option{-Wformat} is specified, do not warn about @code{strftime}
1920 formats which may yield only a two-digit year.
1921
1922 @item -Wno-format-extra-args
1923 @opindex Wno-format-extra-args
1924 If @option{-Wformat} is specified, do not warn about excess arguments to a
1925 @code{printf} or @code{scanf} format function.  The C standard specifies
1926 that such arguments are ignored.
1927
1928 Where the unused arguments lie between used arguments that are
1929 specified with @samp{$} operand number specifications, normally
1930 warnings are still given, since the implementation could not know what
1931 type to pass to @code{va_arg} to skip the unused arguments.  However,
1932 in the case of @code{scanf} formats, this option will suppress the
1933 warning if the unused arguments are all pointers, since the Single
1934 Unix Specification says that such unused arguments are allowed.
1935
1936 @item -Wno-format-zero-length
1937 @opindex Wno-format-zero-length
1938 If @option{-Wformat} is specified, do not warn about zero-length formats.
1939 The C standard specifies that zero-length formats are allowed.
1940
1941 @item -Wformat-nonliteral
1942 @opindex Wformat-nonliteral
1943 If @option{-Wformat} is specified, also warn if the format string is not a
1944 string literal and so cannot be checked, unless the format function
1945 takes its format arguments as a @code{va_list}.
1946
1947 @item -Wformat-security
1948 @opindex Wformat-security
1949 If @option{-Wformat} is specified, also warn about uses of format
1950 functions that represent possible security problems.  At present, this
1951 warns about calls to @code{printf} and @code{scanf} functions where the
1952 format string is not a string literal and there are no format arguments,
1953 as in @code{printf (foo);}.  This may be a security hole if the format
1954 string came from untrusted input and contains @samp{%n}.  (This is
1955 currently a subset of what @option{-Wformat-nonliteral} warns about, but
1956 in future warnings may be added to @option{-Wformat-security} that are not
1957 included in @option{-Wformat-nonliteral}.)
1958
1959 @item -Wformat=2
1960 @opindex Wformat=2
1961 Enable @option{-Wformat} plus format checks not included in
1962 @option{-Wformat}.  Currently equivalent to @samp{-Wformat
1963 -Wformat-nonliteral -Wformat-security}.
1964
1965 @item -Wnonnull
1966 @opindex Wnonnull
1967 Enable warning about passing a null pointer for arguments marked as
1968 requiring a non-null value by the @code{nonnull} function attribute.
1969
1970 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}.  It
1971 can be disabled with the @option{-Wno-nonnull} option.
1972
1973 @item -Wimplicit-int
1974 @opindex Wimplicit-int
1975 Warn when a declaration does not specify a type.
1976
1977 @item -Wimplicit-function-declaration
1978 @itemx -Werror-implicit-function-declaration
1979 @opindex Wimplicit-function-declaration
1980 @opindex Werror-implicit-function-declaration
1981 Give a warning (or error) whenever a function is used before being
1982 declared.
1983
1984 @item -Wimplicit
1985 @opindex Wimplicit
1986 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
1987
1988 @item -Wmain
1989 @opindex Wmain
1990 Warn if the type of @samp{main} is suspicious.  @samp{main} should be a
1991 function with external linkage, returning int, taking either zero
1992 arguments, two, or three arguments of appropriate types.
1993
1994 @item -Wmissing-braces
1995 @opindex Wmissing-braces
1996 Warn if an aggregate or union initializer is not fully bracketed.  In
1997 the following example, the initializer for @samp{a} is not fully
1998 bracketed, but that for @samp{b} is fully bracketed.
1999
2000 @smallexample
2001 int a[2][2] = @{ 0, 1, 2, 3 @};
2002 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2003 @end smallexample
2004
2005 @item -Wparentheses
2006 @opindex Wparentheses
2007 Warn if parentheses are omitted in certain contexts, such
2008 as when there is an assignment in a context where a truth value
2009 is expected, or when operators are nested whose precedence people
2010 often get confused about.
2011
2012 Also warn about constructions where there may be confusion to which
2013 @code{if} statement an @code{else} branch belongs.  Here is an example of
2014 such a case:
2015
2016 @smallexample
2017 @group
2018 @{
2019   if (a)
2020     if (b)
2021       foo ();
2022   else
2023     bar ();
2024 @}
2025 @end group
2026 @end smallexample
2027
2028 In C, every @code{else} branch belongs to the innermost possible @code{if}
2029 statement, which in this example is @code{if (b)}.  This is often not
2030 what the programmer expected, as illustrated in the above example by
2031 indentation the programmer chose.  When there is the potential for this
2032 confusion, GCC will issue a warning when this flag is specified.
2033 To eliminate the warning, add explicit braces around the innermost
2034 @code{if} statement so there is no way the @code{else} could belong to
2035 the enclosing @code{if}.  The resulting code would look like this:
2036
2037 @smallexample
2038 @group
2039 @{
2040   if (a)
2041     @{
2042       if (b)
2043         foo ();
2044       else
2045         bar ();
2046     @}
2047 @}
2048 @end group
2049 @end smallexample
2050
2051 @item -Wsequence-point
2052 @opindex Wsequence-point
2053 Warn about code that may have undefined semantics because of violations
2054 of sequence point rules in the C standard.
2055
2056 The C standard defines the order in which expressions in a C program are
2057 evaluated in terms of @dfn{sequence points}, which represent a partial
2058 ordering between the execution of parts of the program: those executed
2059 before the sequence point, and those executed after it.  These occur
2060 after the evaluation of a full expression (one which is not part of a
2061 larger expression), after the evaluation of the first operand of a
2062 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2063 function is called (but after the evaluation of its arguments and the
2064 expression denoting the called function), and in certain other places.
2065 Other than as expressed by the sequence point rules, the order of
2066 evaluation of subexpressions of an expression is not specified.  All
2067 these rules describe only a partial order rather than a total order,
2068 since, for example, if two functions are called within one expression
2069 with no sequence point between them, the order in which the functions
2070 are called is not specified.  However, the standards committee have
2071 ruled that function calls do not overlap.
2072
2073 It is not specified when between sequence points modifications to the
2074 values of objects take effect.  Programs whose behavior depends on this
2075 have undefined behavior; the C standard specifies that ``Between the
2076 previous and next sequence point an object shall have its stored value
2077 modified at most once by the evaluation of an expression.  Furthermore,
2078 the prior value shall be read only to determine the value to be
2079 stored.''.  If a program breaks these rules, the results on any
2080 particular implementation are entirely unpredictable.
2081
2082 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2083 = b[n++]} and @code{a[i++] = i;}.  Some more complicated cases are not
2084 diagnosed by this option, and it may give an occasional false positive
2085 result, but in general it has been found fairly effective at detecting
2086 this sort of problem in programs.
2087
2088 The present implementation of this option only works for C programs.  A
2089 future implementation may also work for C++ programs.
2090
2091 The C standard is worded confusingly, therefore there is some debate
2092 over the precise meaning of the sequence point rules in subtle cases.
2093 Links to discussions of the problem, including proposed formal
2094 definitions, may be found on our readings page, at
2095 @w{@uref{http://gcc.gnu.org/readings.html}}.
2096
2097 @item -Wreturn-type
2098 @opindex Wreturn-type
2099 Warn whenever a function is defined with a return-type that defaults to
2100 @code{int}.  Also warn about any @code{return} statement with no
2101 return-value in a function whose return-type is not @code{void}.
2102
2103 For C++, a function without return type always produces a diagnostic
2104 message, even when @option{-Wno-return-type} is specified.  The only
2105 exceptions are @samp{main} and functions defined in system headers.
2106
2107 @item -Wswitch
2108 @opindex Wswitch
2109 Warn whenever a @code{switch} statement has an index of enumeral type
2110 and lacks a @code{case} for one or more of the named codes of that
2111 enumeration.  (The presence of a @code{default} label prevents this
2112 warning.)  @code{case} labels outside the enumeration range also
2113 provoke warnings when this option is used.
2114
2115 @item -Wswitch-default
2116 @opindex Wswitch-switch
2117 Warn whenever a @code{switch} statement does not have a @code{default}
2118 case.
2119
2120 @item -Wswitch-enum
2121 @opindex Wswitch-enum
2122 Warn whenever a @code{switch} statement has an index of enumeral type
2123 and lacks a @code{case} for one or more of the named codes of that
2124 enumeration.  @code{case} labels outside the enumeration range also
2125 provoke warnings when this option is used.
2126
2127 @item -Wtrigraphs
2128 @opindex Wtrigraphs
2129 Warn if any trigraphs are encountered that might change the meaning of
2130 the program (trigraphs within comments are not warned about).
2131
2132 @item -Wunused-function
2133 @opindex Wunused-function
2134 Warn whenever a static function is declared but not defined or a
2135 non\-inline static function is unused.
2136
2137 @item -Wunused-label
2138 @opindex Wunused-label
2139 Warn whenever a label is declared but not used.
2140
2141 To suppress this warning use the @samp{unused} attribute
2142 (@pxref{Variable Attributes}).
2143
2144 @item -Wunused-parameter
2145 @opindex Wunused-parameter
2146 Warn whenever a function parameter is unused aside from its declaration.
2147
2148 To suppress this warning use the @samp{unused} attribute
2149 (@pxref{Variable Attributes}).
2150
2151 @item -Wunused-variable
2152 @opindex Wunused-variable
2153 Warn whenever a local variable or non-constant static variable is unused
2154 aside from its declaration
2155
2156 To suppress this warning use the @samp{unused} attribute
2157 (@pxref{Variable Attributes}).
2158
2159 @item -Wunused-value
2160 @opindex Wunused-value
2161 Warn whenever a statement computes a result that is explicitly not used.
2162
2163 To suppress this warning cast the expression to @samp{void}.
2164
2165 @item -Wunused
2166 @opindex Wunused
2167 All the above @option{-Wunused} options combined.
2168
2169 In order to get a warning about an unused function parameter, you must
2170 either specify @samp{-W -Wunused} or separately specify
2171 @option{-Wunused-parameter}.
2172
2173 @item -Wuninitialized
2174 @opindex Wuninitialized
2175 Warn if an automatic variable is used without first being initialized or
2176 if a variable may be clobbered by a @code{setjmp} call.
2177
2178 These warnings are possible only in optimizing compilation,
2179 because they require data flow information that is computed only
2180 when optimizing.  If you don't specify @option{-O}, you simply won't
2181 get these warnings.
2182
2183 These warnings occur only for variables that are candidates for
2184 register allocation.  Therefore, they do not occur for a variable that
2185 is declared @code{volatile}, or whose address is taken, or whose size
2186 is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
2187 structures, unions or arrays, even when they are in registers.
2188
2189 Note that there may be no warning about a variable that is used only
2190 to compute a value that itself is never used, because such
2191 computations may be deleted by data flow analysis before the warnings
2192 are printed.
2193
2194 These warnings are made optional because GCC is not smart
2195 enough to see all the reasons why the code might be correct
2196 despite appearing to have an error.  Here is one example of how
2197 this can happen:
2198
2199 @smallexample
2200 @group
2201 @{
2202   int x;
2203   switch (y)
2204     @{
2205     case 1: x = 1;
2206       break;
2207     case 2: x = 4;
2208       break;
2209     case 3: x = 5;
2210     @}
2211   foo (x);
2212 @}
2213 @end group
2214 @end smallexample
2215
2216 @noindent
2217 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2218 always initialized, but GCC doesn't know this.  Here is
2219 another common case:
2220
2221 @smallexample
2222 @{
2223   int save_y;
2224   if (change_y) save_y = y, y = new_y;
2225   @dots{}
2226   if (change_y) y = save_y;
2227 @}
2228 @end smallexample
2229
2230 @noindent
2231 This has no bug because @code{save_y} is used only if it is set.
2232
2233 @cindex @code{longjmp} warnings
2234 This option also warns when a non-volatile automatic variable might be
2235 changed by a call to @code{longjmp}.  These warnings as well are possible
2236 only in optimizing compilation.
2237
2238 The compiler sees only the calls to @code{setjmp}.  It cannot know
2239 where @code{longjmp} will be called; in fact, a signal handler could
2240 call it at any point in the code.  As a result, you may get a warning
2241 even when there is in fact no problem because @code{longjmp} cannot
2242 in fact be called at the place which would cause a problem.
2243
2244 Some spurious warnings can be avoided if you declare all the functions
2245 you use that never return as @code{noreturn}.  @xref{Function
2246 Attributes}.
2247
2248 @item -Wreorder @r{(C++ only)}
2249 @opindex Wreorder
2250 @cindex reordering, warning
2251 @cindex warning for reordering of member initializers
2252 Warn when the order of member initializers given in the code does not
2253 match the order in which they must be executed.  For instance:
2254
2255 @item -Wunknown-pragmas
2256 @opindex Wunknown-pragmas
2257 @cindex warning for unknown pragmas
2258 @cindex unknown pragmas, warning
2259 @cindex pragmas, warning of unknown
2260 Warn when a #pragma directive is encountered which is not understood by
2261 GCC@.  If this command line option is used, warnings will even be issued
2262 for unknown pragmas in system header files.  This is not the case if
2263 the warnings were only enabled by the @option{-Wall} command line option.
2264
2265 @item -Wall
2266 @opindex Wall
2267 All of the above @samp{-W} options combined.  This enables all the
2268 warnings about constructions that some users consider questionable, and
2269 that are easy to avoid (or modify to prevent the warning), even in
2270 conjunction with macros.
2271 @end table
2272
2273 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2274 Some of them warn about constructions that users generally do not
2275 consider questionable, but which occasionally you might wish to check
2276 for; others warn about constructions that are necessary or hard to avoid
2277 in some cases, and there is no simple way to modify the code to suppress
2278 the warning.
2279
2280 @table @gcctabopt
2281 @item -W
2282 @opindex W
2283 Print extra warning messages for these events:
2284
2285 @itemize @bullet
2286 @item
2287 A function can return either with or without a value.  (Falling
2288 off the end of the function body is considered returning without
2289 a value.)  For example, this function would evoke such a
2290 warning:
2291
2292 @smallexample
2293 @group
2294 foo (a)
2295 @{
2296   if (a > 0)
2297     return a;
2298 @}
2299 @end group
2300 @end smallexample
2301
2302 @item
2303 An expression-statement or the left-hand side of a comma expression
2304 contains no side effects.
2305 To suppress the warning, cast the unused expression to void.
2306 For example, an expression such as @samp{x[i,j]} will cause a warning,
2307 but @samp{x[(void)i,j]} will not.
2308
2309 @item
2310 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
2311
2312 @item
2313 A comparison like @samp{x<=y<=z} appears; this is equivalent to
2314 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
2315 that of ordinary mathematical notation.
2316
2317 @item
2318 Storage-class specifiers like @code{static} are not the first things in
2319 a declaration.  According to the C Standard, this usage is obsolescent.
2320
2321 @item
2322 The return type of a function has a type qualifier such as @code{const}.
2323 Such a type qualifier has no effect, since the value returned by a
2324 function is not an lvalue.  (But don't warn about the GNU extension of
2325 @code{volatile void} return types.  That extension will be warned about
2326 if @option{-pedantic} is specified.)
2327
2328 @item
2329 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2330 arguments.
2331
2332 @item
2333 A comparison between signed and unsigned values could produce an
2334 incorrect result when the signed value is converted to unsigned.
2335 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2336
2337 @item
2338 An aggregate has a partly bracketed initializer.
2339 For example, the following code would evoke such a warning,
2340 because braces are missing around the initializer for @code{x.h}:
2341
2342 @smallexample
2343 struct s @{ int f, g; @};
2344 struct t @{ struct s h; int i; @};
2345 struct t x = @{ 1, 2, 3 @};
2346 @end smallexample
2347
2348 @item
2349 An aggregate has an initializer which does not initialize all members.
2350 For example, the following code would cause such a warning, because
2351 @code{x.h} would be implicitly initialized to zero:
2352
2353 @smallexample
2354 struct s @{ int f, g, h; @};
2355 struct s x = @{ 3, 4 @};
2356 @end smallexample
2357 @end itemize
2358
2359 @item -Wno-div-by-zero
2360 @opindex Wno-div-by-zero
2361 @opindex Wdiv-by-zero
2362 Do not warn about compile-time integer division by zero.  Floating point
2363 division by zero is not warned about, as it can be a legitimate way of
2364 obtaining infinities and NaNs.
2365
2366 @item -Wsystem-headers
2367 @opindex Wsystem-headers
2368 @cindex warnings from system headers
2369 @cindex system headers, warnings from
2370 Print warning messages for constructs found in system header files.
2371 Warnings from system headers are normally suppressed, on the assumption
2372 that they usually do not indicate real problems and would only make the
2373 compiler output harder to read.  Using this command line option tells
2374 GCC to emit warnings from system headers as if they occurred in user
2375 code.  However, note that using @option{-Wall} in conjunction with this
2376 option will @emph{not} warn about unknown pragmas in system
2377 headers---for that, @option{-Wunknown-pragmas} must also be used.
2378
2379 @item -Wfloat-equal
2380 @opindex Wfloat-equal
2381 Warn if floating point values are used in equality comparisons.
2382
2383 The idea behind this is that sometimes it is convenient (for the
2384 programmer) to consider floating-point values as approximations to
2385 infinitely precise real numbers.  If you are doing this, then you need
2386 to compute (by analysing the code, or in some other way) the maximum or
2387 likely maximum error that the computation introduces, and allow for it
2388 when performing comparisons (and when producing output, but that's a
2389 different problem).  In particular, instead of testing for equality, you
2390 would check to see whether the two values have ranges that overlap; and
2391 this is done with the relational operators, so equality comparisons are
2392 probably mistaken.
2393
2394 @item -Wtraditional @r{(C only)}
2395 @opindex Wtraditional
2396 Warn about certain constructs that behave differently in traditional and
2397 ISO C@.  Also warn about ISO C constructs that have no traditional C
2398 equivalent, and/or problematic constructs which should be avoided.
2399
2400 @itemize @bullet
2401 @item
2402 Macro parameters that appear within string literals in the macro body.
2403 In traditional C macro replacement takes place within string literals,
2404 but does not in ISO C@.
2405
2406 @item
2407 In traditional C, some preprocessor directives did not exist.
2408 Traditional preprocessors would only consider a line to be a directive
2409 if the @samp{#} appeared in column 1 on the line.  Therefore
2410 @option{-Wtraditional} warns about directives that traditional C
2411 understands but would ignore because the @samp{#} does not appear as the
2412 first character on the line.  It also suggests you hide directives like
2413 @samp{#pragma} not understood by traditional C by indenting them.  Some
2414 traditional implementations would not recognize @samp{#elif}, so it
2415 suggests avoiding it altogether.
2416
2417 @item
2418 A function-like macro that appears without arguments.
2419
2420 @item
2421 The unary plus operator.
2422
2423 @item
2424 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2425 constant suffixes.  (Traditional C does support the @samp{L} suffix on integer
2426 constants.)  Note, these suffixes appear in macros defined in the system
2427 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2428 Use of these macros in user code might normally lead to spurious
2429 warnings, however gcc's integrated preprocessor has enough context to
2430 avoid warning in these cases.
2431
2432 @item
2433 A function declared external in one block and then used after the end of
2434 the block.
2435
2436 @item
2437 A @code{switch} statement has an operand of type @code{long}.
2438
2439 @item
2440 A non-@code{static} function declaration follows a @code{static} one.
2441 This construct is not accepted by some traditional C compilers.
2442
2443 @item
2444 The ISO type of an integer constant has a different width or
2445 signedness from its traditional type.  This warning is only issued if
2446 the base of the constant is ten.  I.e.@: hexadecimal or octal values, which
2447 typically represent bit patterns, are not warned about.
2448
2449 @item
2450 Usage of ISO string concatenation is detected.
2451
2452 @item
2453 Initialization of automatic aggregates.
2454
2455 @item
2456 Identifier conflicts with labels.  Traditional C lacks a separate
2457 namespace for labels.
2458
2459 @item
2460 Initialization of unions.  If the initializer is zero, the warning is
2461 omitted.  This is done under the assumption that the zero initializer in
2462 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2463 initializer warnings and relies on default initialization to zero in the
2464 traditional C case.
2465
2466 @item
2467 Conversions by prototypes between fixed/floating point values and vice
2468 versa.  The absence of these prototypes when compiling with traditional
2469 C would cause serious problems.  This is a subset of the possible
2470 conversion warnings, for the full set use @option{-Wconversion}.
2471
2472 @item
2473 Use of ISO C style function definitions.  This warning intentionally is
2474 @emph{not} issued for prototype declarations or variadic functions
2475 because these ISO C features will appear in your code when using
2476 libiberty's traditional C compatibility macros, @code{PARAMS} and
2477 @code{VPARAMS}.  This warning is also bypassed for nested functions
2478 because that feature is already a gcc extension and thus not relevant to
2479 traditional C compatibility.
2480 @end itemize
2481
2482 @item -Wundef
2483 @opindex Wundef
2484 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2485
2486 @item -Wendif-labels
2487 @opindex Wendif-labels
2488 Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2489
2490 @item -Wshadow
2491 @opindex Wshadow
2492 Warn whenever a local variable shadows another local variable, parameter or
2493 global variable or whenever a built-in function is shadowed.
2494
2495 @item -Wlarger-than-@var{len}
2496 @opindex Wlarger-than
2497 Warn whenever an object of larger than @var{len} bytes is defined.
2498
2499 @item -Wpointer-arith
2500 @opindex Wpointer-arith
2501 Warn about anything that depends on the ``size of'' a function type or
2502 of @code{void}.  GNU C assigns these types a size of 1, for
2503 convenience in calculations with @code{void *} pointers and pointers
2504 to functions.
2505
2506 @item -Wbad-function-cast @r{(C only)}
2507 @opindex Wbad-function-cast
2508 Warn whenever a function call is cast to a non-matching type.
2509 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2510
2511 @item -Wcast-qual
2512 @opindex Wcast-qual
2513 Warn whenever a pointer is cast so as to remove a type qualifier from
2514 the target type.  For example, warn if a @code{const char *} is cast
2515 to an ordinary @code{char *}.
2516
2517 @item -Wcast-align
2518 @opindex Wcast-align
2519 Warn whenever a pointer is cast such that the required alignment of the
2520 target is increased.  For example, warn if a @code{char *} is cast to
2521 an @code{int *} on machines where integers can only be accessed at
2522 two- or four-byte boundaries.
2523
2524 @item -Wwrite-strings
2525 @opindex Wwrite-strings
2526 When compiling C, give string constants the type @code{const
2527 char[@var{length}]} so that
2528 copying the address of one into a non-@code{const} @code{char *}
2529 pointer will get a warning; when compiling C++, warn about the
2530 deprecated conversion from string constants to @code{char *}.
2531 These warnings will help you find at
2532 compile time code that can try to write into a string constant, but
2533 only if you have been very careful about using @code{const} in
2534 declarations and prototypes.  Otherwise, it will just be a nuisance;
2535 this is why we did not make @option{-Wall} request these warnings.
2536
2537 @item -Wconversion
2538 @opindex Wconversion
2539 Warn if a prototype causes a type conversion that is different from what
2540 would happen to the same argument in the absence of a prototype.  This
2541 includes conversions of fixed point to floating and vice versa, and
2542 conversions changing the width or signedness of a fixed point argument
2543 except when the same as the default promotion.
2544
2545 Also, warn if a negative integer constant expression is implicitly
2546 converted to an unsigned type.  For example, warn about the assignment
2547 @code{x = -1} if @code{x} is unsigned.  But do not warn about explicit
2548 casts like @code{(unsigned) -1}.
2549
2550 @item -Wsign-compare
2551 @opindex Wsign-compare
2552 @cindex warning for comparison of signed and unsigned values
2553 @cindex comparison of signed and unsigned values, warning
2554 @cindex signed and unsigned values, comparison warning
2555 Warn when a comparison between signed and unsigned values could produce
2556 an incorrect result when the signed value is converted to unsigned.
2557 This warning is also enabled by @option{-W}; to get the other warnings
2558 of @option{-W} without this warning, use @samp{-W -Wno-sign-compare}.
2559
2560 @item -Waggregate-return
2561 @opindex Waggregate-return
2562 Warn if any functions that return structures or unions are defined or
2563 called.  (In languages where you can return an array, this also elicits
2564 a warning.)
2565
2566 @item -Wstrict-prototypes @r{(C only)}
2567 @opindex Wstrict-prototypes
2568 Warn if a function is declared or defined without specifying the
2569 argument types.  (An old-style function definition is permitted without
2570 a warning if preceded by a declaration which specifies the argument
2571 types.)
2572
2573 @item -Wmissing-prototypes @r{(C only)}
2574 @opindex Wmissing-prototypes
2575 Warn if a global function is defined without a previous prototype
2576 declaration.  This warning is issued even if the definition itself
2577 provides a prototype.  The aim is to detect global functions that fail
2578 to be declared in header files.
2579
2580 @item -Wmissing-declarations
2581 @opindex Wmissing-declarations
2582 Warn if a global function is defined without a previous declaration.
2583 Do so even if the definition itself provides a prototype.
2584 Use this option to detect global functions that are not declared in
2585 header files.
2586
2587 @item -Wmissing-noreturn
2588 @opindex Wmissing-noreturn
2589 Warn about functions which might be candidates for attribute @code{noreturn}.
2590 Note these are only possible candidates, not absolute ones.  Care should
2591 be taken to manually verify functions actually do not ever return before
2592 adding the @code{noreturn} attribute, otherwise subtle code generation
2593 bugs could be introduced.  You will not get a warning for @code{main} in
2594 hosted C environments.
2595
2596 @item -Wmissing-format-attribute
2597 @opindex Wmissing-format-attribute
2598 @opindex Wformat
2599 If @option{-Wformat} is enabled, also warn about functions which might be
2600 candidates for @code{format} attributes.  Note these are only possible
2601 candidates, not absolute ones.  GCC will guess that @code{format}
2602 attributes might be appropriate for any function that calls a function
2603 like @code{vprintf} or @code{vscanf}, but this might not always be the
2604 case, and some functions for which @code{format} attributes are
2605 appropriate may not be detected.  This option has no effect unless
2606 @option{-Wformat} is enabled (possibly by @option{-Wall}).
2607
2608 @item -Wno-multichar
2609 @opindex Wno-multichar
2610 @opindex Wmultichar
2611 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
2612 Usually they indicate a typo in the user's code, as they have
2613 implementation-defined values, and should not be used in portable code.
2614
2615 @item -Wno-deprecated-declarations
2616 @opindex Wno-deprecated-declarations
2617 Do not warn about uses of functions, variables, and types marked as
2618 deprecated by using the @code{deprecated} attribute.
2619 (@pxref{Function Attributes}, @pxref{Variable Attributes},
2620 @pxref{Type Attributes}.)
2621
2622 @item -Wpacked
2623 @opindex Wpacked
2624 Warn if a structure is given the packed attribute, but the packed
2625 attribute has no effect on the layout or size of the structure.
2626 Such structures may be mis-aligned for little benefit.  For
2627 instance, in this code, the variable @code{f.x} in @code{struct bar}
2628 will be misaligned even though @code{struct bar} does not itself
2629 have the packed attribute:
2630
2631 @smallexample
2632 @group
2633 struct foo @{
2634   int x;
2635   char a, b, c, d;
2636 @} __attribute__((packed));
2637 struct bar @{
2638   char z;
2639   struct foo f;
2640 @};
2641 @end group
2642 @end smallexample
2643
2644 @item -Wpadded
2645 @opindex Wpadded
2646 Warn if padding is included in a structure, either to align an element
2647 of the structure or to align the whole structure.  Sometimes when this
2648 happens it is possible to rearrange the fields of the structure to
2649 reduce the padding and so make the structure smaller.
2650
2651 @item -Wredundant-decls
2652 @opindex Wredundant-decls
2653 Warn if anything is declared more than once in the same scope, even in
2654 cases where multiple declaration is valid and changes nothing.
2655
2656 @item -Wnested-externs @r{(C only)}
2657 @opindex Wnested-externs
2658 Warn if an @code{extern} declaration is encountered within a function.
2659
2660 @item -Wunreachable-code
2661 @opindex Wunreachable-code
2662 Warn if the compiler detects that code will never be executed.
2663
2664 This option is intended to warn when the compiler detects that at
2665 least a whole line of source code will never be executed, because
2666 some condition is never satisfied or because it is after a
2667 procedure that never returns.
2668
2669 It is possible for this option to produce a warning even though there
2670 are circumstances under which part of the affected line can be executed,
2671 so care should be taken when removing apparently-unreachable code.
2672
2673 For instance, when a function is inlined, a warning may mean that the
2674 line is unreachable in only one inlined copy of the function.
2675
2676 This option is not made part of @option{-Wall} because in a debugging
2677 version of a program there is often substantial code which checks
2678 correct functioning of the program and is, hopefully, unreachable
2679 because the program does work.  Another common use of unreachable
2680 code is to provide behavior which is selectable at compile-time.
2681
2682 @item -Winline
2683 @opindex Winline
2684 Warn if a function can not be inlined and it was declared as inline.
2685
2686 @item -Wlong-long
2687 @opindex Wlong-long
2688 @opindex Wno-long-long
2689 Warn if @samp{long long} type is used.  This is default.  To inhibit
2690 the warning messages, use @option{-Wno-long-long}.  Flags
2691 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
2692 only when @option{-pedantic} flag is used.
2693
2694 @item -Wdisabled-optimization
2695 @opindex Wdisabled-optimization
2696 Warn if a requested optimization pass is disabled.  This warning does
2697 not generally indicate that there is anything wrong with your code; it
2698 merely indicates that GCC's optimizers were unable to handle the code
2699 effectively.  Often, the problem is that your code is too big or too
2700 complex; GCC will refuse to optimize programs when the optimization
2701 itself is likely to take inordinate amounts of time.
2702
2703 @item -Werror
2704 @opindex Werror
2705 Make all warnings into errors.
2706 @end table
2707
2708 @node Debugging Options
2709 @section Options for Debugging Your Program or GCC
2710 @cindex options, debugging
2711 @cindex debugging information options
2712
2713 GCC has various special options that are used for debugging
2714 either your program or GCC:
2715
2716 @table @gcctabopt
2717 @item -g
2718 @opindex g
2719 Produce debugging information in the operating system's native format
2720 (stabs, COFF, XCOFF, or DWARF)@.  GDB can work with this debugging
2721 information.
2722
2723 On most systems that use stabs format, @option{-g} enables use of extra
2724 debugging information that only GDB can use; this extra information
2725 makes debugging work better in GDB but will probably make other debuggers
2726 crash or
2727 refuse to read the program.  If you want to control for certain whether
2728 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
2729 @option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1},
2730 or @option{-gvms} (see below).
2731
2732 Unlike most other C compilers, GCC allows you to use @option{-g} with
2733 @option{-O}.  The shortcuts taken by optimized code may occasionally
2734 produce surprising results: some variables you declared may not exist
2735 at all; flow of control may briefly move where you did not expect it;
2736 some statements may not be executed because they compute constant
2737 results or their values were already at hand; some statements may
2738 execute in different places because they were moved out of loops.
2739
2740 Nevertheless it proves possible to debug optimized output.  This makes
2741 it reasonable to use the optimizer for programs that might have bugs.
2742
2743 The following options are useful when GCC is generated with the
2744 capability for more than one debugging format.
2745
2746 @item -ggdb
2747 @opindex ggdb
2748 Produce debugging information for use by GDB@.  This means to use the
2749 most expressive format available (DWARF 2, stabs, or the native format
2750 if neither of those are supported), including GDB extensions if at all
2751 possible.
2752
2753 @item -gstabs
2754 @opindex gstabs
2755 Produce debugging information in stabs format (if that is supported),
2756 without GDB extensions.  This is the format used by DBX on most BSD
2757 systems.  On MIPS, Alpha and System V Release 4 systems this option
2758 produces stabs debugging output which is not understood by DBX or SDB@.
2759 On System V Release 4 systems this option requires the GNU assembler.
2760
2761 @item -gstabs+
2762 @opindex gstabs+
2763 Produce debugging information in stabs format (if that is supported),
2764 using GNU extensions understood only by the GNU debugger (GDB)@.  The
2765 use of these extensions is likely to make other debuggers crash or
2766 refuse to read the program.
2767
2768 @item -gcoff
2769 @opindex gcoff
2770 Produce debugging information in COFF format (if that is supported).
2771 This is the format used by SDB on most System V systems prior to
2772 System V Release 4.
2773
2774 @item -gxcoff
2775 @opindex gxcoff
2776 Produce debugging information in XCOFF format (if that is supported).
2777 This is the format used by the DBX debugger on IBM RS/6000 systems.
2778
2779 @item -gxcoff+
2780 @opindex gxcoff+
2781 Produce debugging information in XCOFF format (if that is supported),
2782 using GNU extensions understood only by the GNU debugger (GDB)@.  The
2783 use of these extensions is likely to make other debuggers crash or
2784 refuse to read the program, and may cause assemblers other than the GNU
2785 assembler (GAS) to fail with an error.
2786
2787 @item -gdwarf
2788 @opindex gdwarf
2789 Produce debugging information in DWARF version 1 format (if that is
2790 supported).  This is the format used by SDB on most System V Release 4
2791 systems.
2792
2793 This option is deprecated.
2794
2795 @item -gdwarf+
2796 @opindex gdwarf+
2797 Produce debugging information in DWARF version 1 format (if that is
2798 supported), using GNU extensions understood only by the GNU debugger
2799 (GDB)@.  The use of these extensions is likely to make other debuggers
2800 crash or refuse to read the program.
2801
2802 This option is deprecated.
2803
2804 @item -gdwarf-2
2805 @opindex gdwarf-2
2806 Produce debugging information in DWARF version 2 format (if that is
2807 supported).  This is the format used by DBX on IRIX 6.
2808
2809 @item -gvms
2810 @opindex gvms
2811 Produce debugging information in VMS debug format (if that is
2812 supported).  This is the format used by DEBUG on VMS systems.
2813
2814 @item -g@var{level}
2815 @itemx -ggdb@var{level}
2816 @itemx -gstabs@var{level}
2817 @itemx -gcoff@var{level}
2818 @itemx -gxcoff@var{level}
2819 @itemx -gvms@var{level}
2820 Request debugging information and also use @var{level} to specify how
2821 much information.  The default level is 2.
2822
2823 Level 1 produces minimal information, enough for making backtraces in
2824 parts of the program that you don't plan to debug.  This includes
2825 descriptions of functions and external variables, but no information
2826 about local variables and no line numbers.
2827
2828 Level 3 includes extra information, such as all the macro definitions
2829 present in the program.  Some debuggers support macro expansion when
2830 you use @option{-g3}.
2831
2832 Note that in order to avoid confusion between DWARF1 debug level 2,
2833 and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept
2834 a concatenated debug level.  Instead use an additional @option{-g@var{level}}
2835 option to change the debug level for DWARF1 or DWARF2.
2836
2837 @cindex @code{prof}
2838 @item -p
2839 @opindex p
2840 Generate extra code to write profile information suitable for the
2841 analysis program @code{prof}.  You must use this option when compiling
2842 the source files you want data about, and you must also use it when
2843 linking.
2844
2845 @cindex @code{gprof}
2846 @item -pg
2847 @opindex pg
2848 Generate extra code to write profile information suitable for the
2849 analysis program @code{gprof}.  You must use this option when compiling
2850 the source files you want data about, and you must also use it when
2851 linking.
2852
2853 @item -Q
2854 @opindex Q
2855 Makes the compiler print out each function name as it is compiled, and
2856 print some statistics about each pass when it finishes.
2857
2858 @item -ftime-report
2859 @opindex ftime-report
2860 Makes the compiler print some statistics about the time consumed by each
2861 pass when it finishes.
2862
2863 @item -fmem-report
2864 @opindex fmem-report
2865 Makes the compiler print some statistics about permanent memory
2866 allocation when it finishes.
2867
2868 @item -fprofile-arcs
2869 @opindex fprofile-arcs
2870 Instrument @dfn{arcs} during compilation to generate coverage data or
2871 for profile-directed block ordering.  During execution the program
2872 records how many times each branch is executed and how many times it is
2873 taken.  When the compiled program exits it saves this data to a file
2874 called @file{@var{auxname}.da} for each source file.  @var{auxname} is
2875 generated from the name of the output file, if explicitly specified and
2876 it is not the final executable, otherwise it is the basename of the
2877 source file. In both cases any suffix is removed (e.g.  @file{foo.da}
2878 for input file @file{dir/foo.c}, or @file{dir/foo.da} for output file
2879 specified as @option{-o dir/foo.o}).
2880
2881 For profile-directed block ordering, compile the program with
2882 @option{-fprofile-arcs} plus optimization and code generation options,
2883 generate the arc profile information by running the program on a
2884 selected workload, and then compile the program again with the same
2885 optimization and code generation options plus
2886 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
2887 Control Optimization}).
2888
2889 The other use of @option{-fprofile-arcs} is for use with @code{gcov},
2890 when it is used with the @option{-ftest-coverage} option.
2891
2892 With @option{-fprofile-arcs}, for each function of your program GCC
2893 creates a program flow graph, then finds a spanning tree for the graph.
2894 Only arcs that are not on the spanning tree have to be instrumented: the
2895 compiler adds code to count the number of times that these arcs are
2896 executed.  When an arc is the only exit or only entrance to a block, the
2897 instrumentation code can be added to the block; otherwise, a new basic
2898 block must be created to hold the instrumentation code.
2899
2900 @need 2000
2901 @item -ftest-coverage
2902 @opindex ftest-coverage
2903 Create data files for the @code{gcov} code-coverage utility
2904 (@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}).  See
2905 @option{-fprofile-arcs} option above for a description of @var{auxname}.
2906
2907 @table @gcctabopt
2908 @item @var{auxname}.bb
2909 A mapping from basic blocks to line numbers, which @code{gcov} uses to
2910 associate basic block execution counts with line numbers.
2911
2912 @item @var{auxname}.bbg
2913 A list of all arcs in the program flow graph.  This allows @code{gcov}
2914 to reconstruct the program flow graph, so that it can compute all basic
2915 block and arc execution counts from the information in the
2916 @file{@var{auxname}.da} file.
2917 @end table
2918
2919 Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter
2920 option adds instrumentation to the program, which then writes
2921 execution counts to another data file:
2922
2923 @table @gcctabopt
2924 @item @var{auxname}.da
2925 Runtime arc execution counts, used in conjunction with the arc
2926 information in the file @file{@var{auxname}.bbg}.
2927 @end table
2928
2929 Coverage data will map better to the source files if
2930 @option{-ftest-coverage} is used without optimization.
2931
2932 @item -d@var{letters}
2933 @opindex d
2934 Says to make debugging dumps during compilation at times specified by
2935 @var{letters}.  This is used for debugging the compiler.  The file names
2936 for most of the dumps are made by appending a pass number and a word to
2937 the @var{dumpname}. @var{dumpname} is generated from the name of the
2938 output file, if explicitly specified and it is not an executable,
2939 otherwise it is the basename of the source file. In both cases any
2940 suffix is removed (e.g.  @file{foo.00.rtl} or @file{foo.01.sibling}).
2941 Here are the possible letters for use in @var{letters}, and their
2942 meanings:
2943
2944 @table @samp
2945 @item A
2946 @opindex dA
2947 Annotate the assembler output with miscellaneous debugging information.
2948 @item b
2949 @opindex db
2950 Dump after computing branch probabilities, to @file{@var{file}.15.bp}.
2951 @item B
2952 @opindex dB
2953 Dump after block reordering, to @file{@var{file}.30.bbro}.
2954 @item c
2955 @opindex dc
2956 Dump after instruction combination, to the file @file{@var{file}.17.combine}.
2957 @item C
2958 @opindex dC
2959 Dump after the first if conversion, to the file @file{@var{file}.18.ce}.
2960 @item d
2961 @opindex dd
2962 Dump after delayed branch scheduling, to @file{@var{file}.32.dbr}.
2963 @item D
2964 @opindex dD
2965 Dump all macro definitions, at the end of preprocessing, in addition to
2966 normal output.
2967 @item e
2968 @opindex de
2969 Dump after SSA optimizations, to @file{@var{file}.04.ssa} and
2970 @file{@var{file}.07.ussa}.
2971 @item E
2972 @opindex dE
2973 Dump after the second if conversion, to @file{@var{file}.27.ce2}.
2974 @item f
2975 @opindex df
2976 Dump after life analysis, to @file{@var{file}.16.life}.
2977 @item F
2978 @opindex dF
2979 Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}.
2980 @item g
2981 @opindex dg
2982 Dump after global register allocation, to @file{@var{file}.22.greg}.
2983 @item h
2984 @opindex dh
2985 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
2986 @item k
2987 @opindex dk
2988 Dump after reg-to-stack conversion, to @file{@var{file}.29.stack}.
2989 @item o
2990 @opindex do
2991 Dump after post-reload optimizations, to @file{@var{file}.23.postreload}.
2992 @item G
2993 @opindex dG
2994 Dump after GCSE, to @file{@var{file}.11.gcse}.
2995 @item i
2996 @opindex di
2997 Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
2998 @item j
2999 @opindex dj
3000 Dump after the first jump optimization, to @file{@var{file}.03.jump}.
3001 @item k
3002 @opindex dk
3003 Dump after conversion from registers to stack, to @file{@var{file}.33.stack}.
3004 @item l
3005 @opindex dl
3006 Dump after local register allocation, to @file{@var{file}.21.lreg}.
3007 @item L
3008 @opindex dL
3009 Dump after loop optimization, to @file{@var{file}.12.loop}.
3010 @item M
3011 @opindex dM
3012 Dump after performing the machine dependent reorganisation pass, to
3013 @file{@var{file}.31.mach}.
3014 @item n
3015 @opindex dn
3016 Dump after register renumbering, to @file{@var{file}.26.rnreg}.
3017 @item N
3018 @opindex dN
3019 Dump after the register move pass, to @file{@var{file}.19.regmove}.
3020 @item r
3021 @opindex dr
3022 Dump after RTL generation, to @file{@var{file}.00.rtl}.
3023 @item R
3024 @opindex dR
3025 Dump after the second scheduling pass, to @file{@var{file}.28.sched2}.
3026 @item s
3027 @opindex ds
3028 Dump after CSE (including the jump optimization that sometimes follows
3029 CSE), to @file{@var{file}.09.cse}.
3030 @item S
3031 @opindex dS
3032 Dump after the first scheduling pass, to @file{@var{file}.20.sched}.
3033 @item t
3034 @opindex dt
3035 Dump after the second CSE pass (including the jump optimization that
3036 sometimes follows CSE), to @file{@var{file}.13.cse2}.
3037 @item u
3038 @opindex du
3039 Dump after null pointer ellimination pass ti @file{@var{file}.08.null}.
3040 @item w
3041 @opindex dw
3042 Dump after the second flow pass, to @file{@var{file}.24.flow2}.
3043 @item X
3044 @opindex dX
3045 Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}.
3046 @item z
3047 @opindex dz
3048 Dump after the peephole pass, to @file{@var{file}.25.peephole2}.
3049 @item a
3050 @opindex da
3051 Produce all the dumps listed above.
3052 @item m
3053 @opindex dm
3054 Print statistics on memory usage, at the end of the run, to
3055 standard error.
3056 @item p
3057 @opindex dp
3058 Annotate the assembler output with a comment indicating which
3059 pattern and alternative was used.  The length of each instruction is
3060 also printed.
3061 @item P
3062 @opindex dP
3063 Dump the RTL in the assembler output as a comment before each instruction.
3064 Also turns on @option{-dp} annotation.
3065 @item v
3066 @opindex dv
3067 For each of the other indicated dump files (except for
3068 @file{@var{file}.00.rtl}), dump a representation of the control flow graph
3069 suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3070 @item x
3071 @opindex dx
3072 Just generate RTL for a function instead of compiling it.  Usually used
3073 with @samp{r}.
3074 @item y
3075 @opindex dy
3076 Dump debugging information during parsing, to standard error.
3077 @end table
3078
3079 @item -fdump-unnumbered
3080 @opindex fdump-unnumbered
3081 When doing debugging dumps (see @option{-d} option above), suppress instruction
3082 numbers and line number note output.  This makes it more feasible to
3083 use diff on debugging dumps for compiler invocations with different
3084 options, in particular with and without @option{-g}.
3085
3086 @item -fdump-translation-unit @r{(C and C++ only)}
3087 @itemx -fdump-translation-unit-@var{options} @r{(C and C++ only)}
3088 @opindex fdump-translation-unit
3089 Dump a representation of the tree structure for the entire translation
3090 unit to a file.  The file name is made by appending @file{.tu} to the
3091 source file name.  If the @samp{-@var{options}} form is used, @var{options}
3092 controls the details of the dump as described for the
3093 @option{-fdump-tree} options.
3094
3095 @item -fdump-class-hierarchy @r{(C++ only)}
3096 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3097 @opindex fdump-class-hierarchy
3098 Dump a representation of each class's hierarchy and virtual function
3099 table layout to a file.  The file name is made by appending @file{.class}
3100 to the source file name.  If the @samp{-@var{options}} form is used,
3101 @var{options} controls the details of the dump as described for the
3102 @option{-fdump-tree} options.
3103
3104 @item -fdump-tree-@var{switch} @r{(C++ only)}
3105 @itemx -fdump-tree-@var{switch}-@var{options} @r{(C++ only)}
3106 @opindex fdump-tree
3107 Control the dumping at various stages of processing the intermediate
3108 language tree to a file.  The file name is generated by appending a switch
3109 specific suffix to the source file name.  If the @samp{-@var{options}}
3110 form is used, @var{options} is a list of @samp{-} separated options that
3111 control the details of the dump. Not all options are applicable to all
3112 dumps, those which are not meaningful will be ignored. The following
3113 options are available
3114
3115 @table @samp
3116 @item address
3117 Print the address of each node.  Usually this is not meaningful as it
3118 changes according to the environment and source file. Its primary use
3119 is for tying up a dump file with a debug environment.
3120 @item slim
3121 Inhibit dumping of members of a scope or body of a function merely
3122 because that scope has been reached. Only dump such items when they
3123 are directly reachable by some other path.
3124 @item all
3125 Turn on all options.
3126 @end table
3127
3128 The following tree dumps are possible:
3129 @table @samp
3130 @item original
3131 Dump before any tree based optimization, to @file{@var{file}.original}.
3132 @item optimized
3133 Dump after all tree based optimization, to @file{@var{file}.optimized}.
3134 @item inlined
3135 Dump after function inlining, to @file{@var{file}.inlined}.
3136 @end table
3137
3138 @item -save-temps
3139 @opindex save-temps
3140 Store the usual ``temporary'' intermediate files permanently; place them
3141 in the current directory and name them based on the source file.  Thus,
3142 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
3143 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.  This creates a
3144 preprocessed @file{foo.i} output file even though the compiler now
3145 normally uses an integrated preprocessor.
3146
3147 @item -time
3148 @opindex time
3149 Report the CPU time taken by each subprocess in the compilation
3150 sequence.  For C source files, this is the compiler proper and assembler
3151 (plus the linker if linking is done).  The output looks like this:
3152
3153 @smallexample
3154 # cc1 0.12 0.01
3155 # as 0.00 0.01
3156 @end smallexample
3157
3158 The first number on each line is the ``user time,'' that is time spent
3159 executing the program itself.  The second number is ``system time,''
3160 time spent executing operating system routines on behalf of the program.
3161 Both numbers are in seconds.
3162
3163 @item -print-file-name=@var{library}
3164 @opindex print-file-name
3165 Print the full absolute name of the library file @var{library} that
3166 would be used when linking---and don't do anything else.  With this
3167 option, GCC does not compile or link anything; it just prints the
3168 file name.
3169
3170 @item -print-multi-directory
3171 @opindex print-multi-directory
3172 Print the directory name corresponding to the multilib selected by any
3173 other switches present in the command line.  This directory is supposed
3174 to exist in @env{GCC_EXEC_PREFIX}.
3175
3176 @item -print-multi-lib
3177 @opindex print-multi-lib
3178 Print the mapping from multilib directory names to compiler switches
3179 that enable them.  The directory name is separated from the switches by
3180 @samp{;}, and each switch starts with an @samp{@@} instead of the
3181 @samp{-}, without spaces between multiple switches.  This is supposed to
3182 ease shell-processing.
3183
3184 @item -print-prog-name=@var{program}
3185 @opindex print-prog-name
3186 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
3187
3188 @item -print-libgcc-file-name
3189 @opindex print-libgcc-file-name
3190 Same as @option{-print-file-name=libgcc.a}.
3191
3192 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
3193 but you do want to link with @file{libgcc.a}.  You can do
3194
3195 @example
3196 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
3197 @end example
3198
3199 @item -print-search-dirs
3200 @opindex print-search-dirs
3201 Print the name of the configured installation directory and a list of
3202 program and library directories gcc will search---and don't do anything else.
3203
3204 This is useful when gcc prints the error message
3205 @samp{installation problem, cannot exec cpp0: No such file or directory}.
3206 To resolve this you either need to put @file{cpp0} and the other compiler
3207 components where gcc expects to find them, or you can set the environment
3208 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
3209 Don't forget the trailing '/'.
3210 @xref{Environment Variables}.
3211
3212 @item -dumpmachine
3213 @opindex dumpmachine
3214 Print the compiler's target machine (for example,
3215 @samp{i686-pc-linux-gnu})---and don't do anything else.
3216
3217 @item -dumpversion
3218 @opindex dumpversion
3219 Print the compiler version (for example, @samp{3.0})---and don't do
3220 anything else.
3221
3222 @item -dumpspecs
3223 @opindex dumpspecs
3224 Print the compiler's built-in specs---and don't do anything else.  (This
3225 is used when GCC itself is being built.)  @xref{Spec Files}.
3226 @end table
3227
3228 @node Optimize Options
3229 @section Options That Control Optimization
3230 @cindex optimize options
3231 @cindex options, optimization
3232
3233 These options control various sorts of optimizations:
3234
3235 @table @gcctabopt
3236 @item -O
3237 @itemx -O1
3238 @opindex O
3239 @opindex O1
3240 Optimize.  Optimizing compilation takes somewhat more time, and a lot
3241 more memory for a large function.
3242
3243 Without @option{-O}, the compiler's goal is to reduce the cost of
3244 compilation and to make debugging produce the expected results.
3245 Statements are independent: if you stop the program with a breakpoint
3246 between statements, you can then assign a new value to any variable or
3247 change the program counter to any other statement in the function and
3248 get exactly the results you would expect from the source code.
3249
3250 With @option{-O}, the compiler tries to reduce code size and execution
3251 time, without performing any optimizations that take a great deal of
3252 compilation time.
3253
3254 @item -O2
3255 @opindex O2
3256 Optimize even more.  GCC performs nearly all supported optimizations
3257 that do not involve a space-speed tradeoff.  The compiler does not
3258 perform loop unrolling or function inlining when you specify @option{-O2}.
3259 As compared to @option{-O}, this option increases both compilation time
3260 and the performance of the generated code.
3261
3262 @option{-O2} turns on all optional optimizations except for loop
3263 unrolling, function inlining, and register renaming.  It also turns on
3264 the @option{-fforce-mem} and @option{-fstrict-aliasing} option on all
3265 machines and frame pointer elimination on machines where doing so does
3266 not interfere with debugging.
3267
3268 Please note the warning under @option{-fgcse} about
3269 invoking @option{-O2} on programs that use computed gotos.
3270
3271 @item -O3
3272 @opindex O3
3273 Optimize yet more.  @option{-O3} turns on all optimizations specified by
3274 @option{-O2} and also turns on the @option{-finline-functions} and
3275 @option{-frename-registers} options.
3276
3277 @item -O0
3278 @opindex O0
3279 Do not optimize.
3280
3281 @item -Os
3282 @opindex Os
3283 Optimize for size.  @option{-Os} enables all @option{-O2} optimizations that
3284 do not typically increase code size.  It also performs further
3285 optimizations designed to reduce code size.
3286
3287 If you use multiple @option{-O} options, with or without level numbers,
3288 the last such option is the one that is effective.
3289 @end table
3290
3291 Options of the form @option{-f@var{flag}} specify machine-independent
3292 flags.  Most flags have both positive and negative forms; the negative
3293 form of @option{-ffoo} would be @option{-fno-foo}.  In the table below,
3294 only one of the forms is listed---the one which is not the default.
3295 You can figure out the other form by either removing @samp{no-} or
3296 adding it.
3297
3298 @table @gcctabopt
3299 @item -ffloat-store
3300 @opindex ffloat-store
3301 Do not store floating point variables in registers, and inhibit other
3302 options that might change whether a floating point value is taken from a
3303 register or memory.
3304
3305 @cindex floating point precision
3306 This option prevents undesirable excess precision on machines such as
3307 the 68000 where the floating registers (of the 68881) keep more
3308 precision than a @code{double} is supposed to have.  Similarly for the
3309 x86 architecture.  For most programs, the excess precision does only
3310 good, but a few programs rely on the precise definition of IEEE floating
3311 point.  Use @option{-ffloat-store} for such programs, after modifying
3312 them to store all pertinent intermediate computations into variables.
3313
3314 @item -fno-default-inline
3315 @opindex fno-default-inline
3316 Do not make member functions inline by default merely because they are
3317 defined inside the class scope (C++ only).  Otherwise, when you specify
3318 @w{@option{-O}}, member functions defined inside class scope are compiled
3319 inline by default; i.e., you don't need to add @samp{inline} in front of
3320 the member function name.
3321
3322 @item -fno-defer-pop
3323 @opindex fno-defer-pop
3324 Always pop the arguments to each function call as soon as that function
3325 returns.  For machines which must pop arguments after a function call,
3326 the compiler normally lets arguments accumulate on the stack for several
3327 function calls and pops them all at once.
3328
3329 @item -fforce-mem
3330 @opindex fforce-mem
3331 Force memory operands to be copied into registers before doing
3332 arithmetic on them.  This produces better code by making all memory
3333 references potential common subexpressions.  When they are not common
3334 subexpressions, instruction combination should eliminate the separate
3335 register-load.  The @option{-O2} option turns on this option.
3336
3337 @item -fforce-addr
3338 @opindex fforce-addr
3339 Force memory address constants to be copied into registers before
3340 doing arithmetic on them.  This may produce better code just as
3341 @option{-fforce-mem} may.
3342
3343 @item -fomit-frame-pointer
3344 @opindex fomit-frame-pointer
3345 Don't keep the frame pointer in a register for functions that
3346 don't need one.  This avoids the instructions to save, set up and
3347 restore frame pointers; it also makes an extra register available
3348 in many functions.  @strong{It also makes debugging impossible on
3349 some machines.}
3350
3351 On some machines, such as the VAX, this flag has no effect, because
3352 the standard calling sequence automatically handles the frame pointer
3353 and nothing is saved by pretending it doesn't exist.  The
3354 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
3355 whether a target machine supports this flag.  @xref{Registers,,Register
3356 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
3357
3358 @item -foptimize-sibling-calls
3359 @opindex foptimize-sibling-calls
3360 Optimize sibling and tail recursive calls.
3361
3362 @item -ftrapv
3363 @opindex ftrapv
3364 This option generates traps for signed overflow on addition, subtraction,
3365 multiplication operations.
3366
3367 @item -fno-inline
3368 @opindex fno-inline
3369 Don't pay attention to the @code{inline} keyword.  Normally this option
3370 is used to keep the compiler from expanding any functions inline.
3371 Note that if you are not optimizing, no functions can be expanded inline.
3372
3373 @item -finline-functions
3374 @opindex finline-functions
3375 Integrate all simple functions into their callers.  The compiler
3376 heuristically decides which functions are simple enough to be worth
3377 integrating in this way.
3378
3379 If all calls to a given function are integrated, and the function is
3380 declared @code{static}, then the function is normally not output as
3381 assembler code in its own right.
3382
3383 @item -finline-limit=@var{n}
3384 @opindex finline-limit
3385 By default, gcc limits the size of functions that can be inlined.  This flag
3386 allows the control of this limit for functions that are explicitly marked as
3387 inline (ie marked with the inline keyword or defined within the class
3388 definition in c++).  @var{n} is the size of functions that can be inlined in
3389 number of pseudo instructions (not counting parameter handling).  The default
3390 value of @var{n} is 600.
3391 Increasing this value can result in more inlined code at
3392 the cost of compilation time and memory consumption.  Decreasing usually makes
3393 the compilation faster and less code will be inlined (which presumably
3394 means slower programs).  This option is particularly useful for programs that
3395 use inlining heavily such as those based on recursive templates with C++.
3396
3397 @emph{Note:} pseudo instruction represents, in this particular context, an
3398 abstract measurement of function's size.  In no way, it represents a count
3399 of assembly instructions and as such its exact meaning might change from one
3400 release to an another.
3401
3402 @item -fkeep-inline-functions
3403 @opindex fkeep-inline-functions
3404 Even if all calls to a given function are integrated, and the function
3405 is declared @code{static}, nevertheless output a separate run-time
3406 callable version of the function.  This switch does not affect
3407 @code{extern inline} functions.
3408
3409 @item -fkeep-static-consts
3410 @opindex fkeep-static-consts
3411 Emit variables declared @code{static const} when optimization isn't turned
3412 on, even if the variables aren't referenced.
3413
3414 GCC enables this option by default.  If you want to force the compiler to
3415 check if the variable was referenced, regardless of whether or not
3416 optimization is turned on, use the @option{-fno-keep-static-consts} option.
3417
3418 @item -fmerge-constants
3419 Attempt to merge identical constants (string constants and floating point
3420 constants) accross compilation units.
3421
3422 This option is default for optimized compilation if assembler and linker
3423 support it.  Use @option{-fno-merge-constants} to inhibit this behavior.
3424
3425 @item -fmerge-all-constants
3426 Attempt to merge identical constants and identical variables.
3427
3428 This option implies @option{-fmerge-constants}.  In addition to
3429 @option{-fmerge-constants} this considers e.g. even constant initialized
3430 arrays or initialized constant variables with integral or floating point
3431 types.  Languages like C or C++ require each non-automatic variable to
3432 have distinct location, so using this option will result in non-conforming
3433 behavior.
3434
3435 @item -fnew-ra
3436 @opindex fnew-ra
3437 Use a graph coloring register allocator.  Currently this option is meant
3438 for testing, so we are interested to hear about miscompilations with
3439 @option{-fnew-ra}.
3440
3441 @item -fno-function-cse
3442 @opindex fno-function-cse
3443 Do not put function addresses in registers; make each instruction that
3444 calls a constant function contain the function's address explicitly.
3445
3446 This option results in less efficient code, but some strange hacks
3447 that alter the assembler output may be confused by the optimizations
3448 performed when this option is not used.
3449
3450 @item -ffast-math
3451 @opindex ffast-math
3452 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
3453 @option{-fno-trapping-math}, @option{-ffinite-math-only} and @*
3454 @option{-fno-signaling-nans}.
3455
3456 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
3457
3458 This option should never be turned on by any @option{-O} option since
3459 it can result in incorrect output for programs which depend on
3460 an exact implementation of IEEE or ISO rules/specifications for
3461 math functions.
3462
3463 @item -fno-math-errno
3464 @opindex fno-math-errno
3465 Do not set ERRNO after calling math functions that are executed
3466 with a single instruction, e.g., sqrt.  A program that relies on
3467 IEEE exceptions for math error handling may want to use this flag
3468 for speed while maintaining IEEE arithmetic compatibility.
3469
3470 This option should never be turned on by any @option{-O} option since
3471 it can result in incorrect output for programs which depend on
3472 an exact implementation of IEEE or ISO rules/specifications for
3473 math functions.
3474
3475 The default is @option{-fmath-errno}.
3476
3477 @item -funsafe-math-optimizations
3478 @opindex funsafe-math-optimizations
3479 Allow optimizations for floating-point arithmetic that (a) assume
3480 that arguments and results are valid and (b) may violate IEEE or
3481 ANSI standards.  When used at link-time, it may include libraries
3482 or startup files that change the default FPU control word or other
3483 similar optimizations.
3484
3485 This option should never be turned on by any @option{-O} option since
3486 it can result in incorrect output for programs which depend on
3487 an exact implementation of IEEE or ISO rules/specifications for
3488 math functions.
3489
3490 The default is @option{-fno-unsafe-math-optimizations}.
3491
3492 @item -ffinite-math-only
3493 @opindex ffinite-math-only
3494 Allow optimizations for floating-point arithmetic that assume
3495 that arguments and results are not NaNs or +-Infs.
3496
3497 This option should never be turned on by any @option{-O} option since
3498 it can result in incorrect output for programs which depend on
3499 an exact implementation of IEEE or ISO rules/specifications.
3500
3501 The default is @option{-fno-finite-math-only}.
3502
3503 @item -fno-trapping-math
3504 @opindex fno-trapping-math
3505 Compile code assuming that floating-point operations cannot generate
3506 user-visible traps.  These traps include division by zero, overflow,
3507 underflow, inexact result and invalid operation.  This option implies
3508 @option{-fno-signaling-nans}.  Setting this option may allow faster
3509 code if one relies on ``non-stop'' IEEE arithmetic, for example.
3510
3511 This option should never be turned on by any @option{-O} option since
3512 it can result in incorrect output for programs which depend on
3513 an exact implementation of IEEE or ISO rules/specifications for
3514 math functions.
3515
3516 The default is @option{-ftrapping-math}.
3517
3518 @item -fsignaling-nans
3519 @opindex fsignaling-nans
3520 Compile code assuming that IEEE signaling NaNs may generate user-visible
3521 traps during floating-point operations.  Setting this option disables
3522 optimizations that may change the number of exceptions visible with
3523 signaling NaNs.  This option implies @option{-ftrapping-math}.
3524
3525 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
3526 be defined.
3527
3528 The default is @option{-fno-signaling-nans}.
3529
3530 This option is experimental and does not currently guarantee to
3531 disable all GCC optimizations that affect signaling NaN behavior.
3532
3533 @item -fno-zero-initialized-in-bss
3534 @opindex fno-zero-initialized-in-bss
3535 If the target supports a BSS section, GCC by default puts variables that
3536 are initialized to zero into BSS@.  This can save space in the resulting
3537 code.
3538
3539 This option turns off this behavior because some programs explicitly
3540 rely on variables going to the data section.  E.g., so that the
3541 resulting executable can find the beginning of that section and/or make
3542 assumptions based on that.
3543
3544 The default is @option{-fzero-initialized-in-bss}.
3545 @end table
3546
3547 The following options control specific optimizations.  The @option{-O2}
3548 option turns on all of these optimizations except @option{-funroll-loops}
3549 and @option{-funroll-all-loops}.  On most machines, the @option{-O} option
3550 turns on the @option{-fthread-jumps} and @option{-fdelayed-branch} options,
3551 but specific machines may handle it differently.
3552
3553 You can use the following flags in the rare cases when ``fine-tuning''
3554 of optimizations to be performed is desired.
3555
3556 Not all of the optimizations performed by GCC have @option{-f} options
3557 to control them.
3558
3559 @table @gcctabopt
3560 @item -fstrength-reduce
3561 @opindex fstrength-reduce
3562 Perform the optimizations of loop strength reduction and
3563 elimination of iteration variables.
3564
3565 @item -fthread-jumps
3566 @opindex fthread-jumps
3567 Perform optimizations where we check to see if a jump branches to a
3568 location where another comparison subsumed by the first is found.  If
3569 so, the first branch is redirected to either the destination of the
3570 second branch or a point immediately following it, depending on whether
3571 the condition is known to be true or false.
3572
3573 @item -fcse-follow-jumps
3574 @opindex fcse-follow-jumps
3575 In common subexpression elimination, scan through jump instructions
3576 when the target of the jump is not reached by any other path.  For
3577 example, when CSE encounters an @code{if} statement with an
3578 @code{else} clause, CSE will follow the jump when the condition
3579 tested is false.
3580
3581 @item -fcse-skip-blocks
3582 @opindex fcse-skip-blocks
3583 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
3584 follow jumps which conditionally skip over blocks.  When CSE
3585 encounters a simple @code{if} statement with no else clause,
3586 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
3587 body of the @code{if}.
3588
3589 @item -frerun-cse-after-loop
3590 @opindex frerun-cse-after-loop
3591 Re-run common subexpression elimination after loop optimizations has been
3592 performed.
3593
3594 @item -frerun-loop-opt
3595 @opindex frerun-loop-opt
3596 Run the loop optimizer twice.
3597
3598 @item -fgcse
3599 @opindex fgcse
3600 Perform a global common subexpression elimination pass.
3601 This pass also performs global constant and copy propagation.
3602
3603 @emph{Note:} When compiling a program using computed gotos, a GCC
3604 extension, you may get better runtime performance if you disable
3605 the global common subexpression elmination pass by adding
3606 @option{-fno-gcse} to the command line.
3607
3608 @item -fgcse-lm
3609 @opindex fgcse-lm
3610 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
3611 attempt to move loads which are only killed by stores into themselves.  This
3612 allows a loop containing a load/store sequence to be changed to a load outside
3613 the loop, and a copy/store within the loop.
3614
3615 @item -fgcse-sm
3616 @opindex fgcse-sm
3617 When @option{-fgcse-sm} is enabled, A store motion pass is run after global common
3618 subexpression elimination.  This pass will attempt to move stores out of loops.
3619 When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence
3620 can be changed to a load before the loop and a store after the loop.
3621
3622 @item -floop-optimize
3623 @opindex floop-optimize
3624 Perform loop optimizations: move constant expressions out of loops, simplify
3625 exit test conditions and optionally do strength-reduction and loop unrolling as
3626 well.
3627
3628 @item -fcrossjumping
3629 @opindex crossjumping
3630 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
3631 resulting code may or may not perform better than without cross-jumping.
3632
3633 @item -fif-conversion
3634 @opindex if-conversion
3635 Attempt to transform conditional jumps into branch-less equivalents.  This
3636 include use of conditional moves, min, max, set flags and abs instructions, and
3637 some tricks doable by standard arithmetics.  The use of conditional execution
3638 on chips where it is available is controlled by @code{if-conversion2}.
3639
3640 @item -fif-conversion2
3641 @opindex if-conversion2
3642 Use conditional execution (where available) to transform conditional jumps into
3643 branch-less equivalents.
3644
3645 @item -fdelete-null-pointer-checks
3646 @opindex fdelete-null-pointer-checks
3647 Use global dataflow analysis to identify and eliminate useless checks
3648 for null pointers.  The compiler assumes that dereferencing a null
3649 pointer would have halted the program.  If a pointer is checked after
3650 it has already been dereferenced, it cannot be null.
3651
3652 In some environments, this assumption is not true, and programs can
3653 safely dereference null pointers.  Use
3654 @option{-fno-delete-null-pointer-checks} to disable this optimization
3655 for programs which depend on that behavior.
3656
3657 @item -fexpensive-optimizations
3658 @opindex fexpensive-optimizations
3659 Perform a number of minor optimizations that are relatively expensive.
3660
3661 @item -foptimize-register-move
3662 @itemx -fregmove
3663 @opindex foptimize-register-move
3664 @opindex fregmove
3665 Attempt to reassign register numbers in move instructions and as
3666 operands of other simple instructions in order to maximize the amount of
3667 register tying.  This is especially helpful on machines with two-operand
3668 instructions.  GCC enables this optimization by default with @option{-O2}
3669 or higher.
3670
3671 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
3672 optimization.
3673
3674 @item -fdelayed-branch
3675 @opindex fdelayed-branch
3676 If supported for the target machine, attempt to reorder instructions
3677 to exploit instruction slots available after delayed branch
3678 instructions.
3679
3680 @item -fschedule-insns
3681 @opindex fschedule-insns
3682 If supported for the target machine, attempt to reorder instructions to
3683 eliminate execution stalls due to required data being unavailable.  This
3684 helps machines that have slow floating point or memory load instructions
3685 by allowing other instructions to be issued until the result of the load
3686 or floating point instruction is required.
3687
3688 @item -fschedule-insns2
3689 @opindex fschedule-insns2
3690 Similar to @option{-fschedule-insns}, but requests an additional pass of
3691 instruction scheduling after register allocation has been done.  This is
3692 especially useful on machines with a relatively small number of
3693 registers and where memory load instructions take more than one cycle.
3694
3695 @item -ffunction-sections
3696 @itemx -fdata-sections
3697 @opindex ffunction-sections
3698 @opindex fdata-sections
3699 Place each function or data item into its own section in the output
3700 file if the target supports arbitrary sections.  The name of the
3701 function or the name of the data item determines the section's name
3702 in the output file.
3703
3704 Use these options on systems where the linker can perform optimizations
3705 to improve locality of reference in the instruction space.  HPPA
3706 processors running HP-UX and Sparc processors running Solaris 2 have
3707 linkers with such optimizations.  Other systems using the ELF object format
3708 as well as AIX may have these optimizations in the future.
3709
3710 Only use these options when there are significant benefits from doing
3711 so.  When you specify these options, the assembler and linker will
3712 create larger object and executable files and will also be slower.
3713 You will not be able to use @code{gprof} on all systems if you
3714 specify this option and you may have problems with debugging if
3715 you specify both this option and @option{-g}.
3716
3717 @item -fcaller-saves
3718 @opindex fcaller-saves
3719 Enable values to be allocated in registers that will be clobbered by
3720 function calls, by emitting extra instructions to save and restore the
3721 registers around such calls.  Such allocation is done only when it
3722 seems to result in better code than would otherwise be produced.
3723
3724 This option is always enabled by default on certain machines, usually
3725 those which have no call-preserved registers to use instead.
3726
3727 For all machines, optimization level 2 and higher enables this flag by
3728 default.
3729
3730 @item -ftracer
3731 @opindex ftracer
3732 Perform tail duplication to enlarge superblock size. This transformation
3733 simplifies the control flow of the function allowing other optimizations to do
3734 better job.
3735
3736 @item -funroll-loops
3737 @opindex funroll-loops
3738 Unroll loops whose number of iterations can be determined at compile
3739 time or upon entry to the loop.  @option{-funroll-loops} implies both
3740 @option{-fstrength-reduce} and @option{-frerun-cse-after-loop}.  This
3741 option makes code larger, and may or may not make it run faster.
3742
3743 @item -funroll-all-loops
3744 @opindex funroll-all-loops
3745 Unroll all loops, even if their number of iterations is uncertain when
3746 the loop is entered.  This usually makes programs run more slowly.
3747 @option{-funroll-all-loops} implies the same options as
3748 @option{-funroll-loops},
3749
3750 @item -fprefetch-loop-arrays
3751 @opindex fprefetch-loop-arrays
3752 If supported by the target machine, generate instructions to prefetch
3753 memory to improve the performance of loops that access large arrays.
3754
3755 @item -fmove-all-movables
3756 @opindex fmove-all-movables
3757 Forces all invariant computations in loops to be moved
3758 outside the loop.
3759
3760 @item -freduce-all-givs
3761 @opindex freduce-all-givs
3762 Forces all general-induction variables in loops to be
3763 strength-reduced.
3764
3765 @emph{Note:} When compiling programs written in Fortran,
3766 @option{-fmove-all-movables} and @option{-freduce-all-givs} are enabled
3767 by default when you use the optimizer.
3768
3769 These options may generate better or worse code; results are highly
3770 dependent on the structure of loops within the source code.
3771
3772 These two options are intended to be removed someday, once
3773 they have helped determine the efficacy of various
3774 approaches to improving loop optimizations.
3775
3776 Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}})
3777 know how use of these options affects
3778 the performance of your production code.
3779 We're very interested in code that runs @emph{slower}
3780 when these options are @emph{enabled}.
3781
3782 @item -fno-peephole
3783 @itemx -fno-peephole2
3784 @opindex fno-peephole
3785 @opindex fno-peephole2
3786 Disable any machine-specific peephole optimizations.  The difference
3787 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
3788 are implemented in the compiler; some targets use one, some use the
3789 other, a few use both.
3790
3791 @item -fbranch-probabilities
3792 @opindex fbranch-probabilities
3793 After running a program compiled with @option{-fprofile-arcs}
3794 (@pxref{Debugging Options,, Options for Debugging Your Program or
3795 @command{gcc}}), you can compile it a second time using
3796 @option{-fbranch-probabilities}, to improve optimizations based on
3797 the number of times each branch was taken.  When the program
3798 compiled with @option{-fprofile-arcs} exits it saves arc execution
3799 counts to a file called @file{@var{sourcename}.da} for each source
3800 file  The information in this data file is very dependent on the
3801 structure of the generated code, so you must use the same source code
3802 and the same optimization options for both compilations.
3803
3804 With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
3805 note on the first instruction of each basic block, and a
3806 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
3807 These can be used to improve optimization.  Currently, they are only
3808 used in one place: in @file{reorg.c}, instead of guessing which path a
3809 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
3810 exactly determine which path is taken more often.
3811
3812 @item -fno-guess-branch-probability
3813 @opindex fno-guess-branch-probability
3814 Do not guess branch probabilities using a randomized model.
3815
3816 Sometimes gcc will opt to use a randomized model to guess branch
3817 probabilities, when none are available from either profiling feedback
3818 (@option{-fprofile-arcs}) or @samp{__builtin_expect}.  This means that
3819 different runs of the compiler on the same program may produce different
3820 object code.
3821
3822 In a hard real-time system, people don't want different runs of the
3823 compiler to produce code that has different behavior; minimizing
3824 non-determinism is of paramount import.  This switch allows users to
3825 reduce non-determinism, possibly at the expense of inferior
3826 optimization.
3827
3828 @item -freorder-blocks
3829 @opindex freorder-blocks
3830 Reorder basic blocks in the compiled function in order to reduce number of
3831 taken branches and improve code locality.
3832
3833 @item -freorder-functions
3834 @opindex freorder-functions
3835 Reorder basic blocks in the compiled function in order to reduce number of
3836 taken branches and improve code locality. This is implemented by using special
3837 subsections @code{text.hot} for most frequently executed functions and
3838 @code{text.unlikely} for unlikely executed functions.  Reordering is done by
3839 the linker so object file format must support named sections and linker must
3840 place them in resonable way.
3841
3842 Also profile feedback must be available in to make this option effective.  See
3843 @option{-fprofile-arcs} for details.
3844
3845 @item -fstrict-aliasing
3846 @opindex fstrict-aliasing
3847 Allows the compiler to assume the strictest aliasing rules applicable to
3848 the language being compiled.  For C (and C++), this activates
3849 optimizations based on the type of expressions.  In particular, an
3850 object of one type is assumed never to reside at the same address as an
3851 object of a different type, unless the types are almost the same.  For
3852 example, an @code{unsigned int} can alias an @code{int}, but not a
3853 @code{void*} or a @code{double}.  A character type may alias any other
3854 type.
3855
3856 Pay special attention to code like this:
3857 @example
3858 union a_union @{
3859   int i;
3860   double d;
3861 @};
3862
3863 int f() @{
3864   a_union t;
3865   t.d = 3.0;
3866   return t.i;
3867 @}
3868 @end example
3869 The practice of reading from a different union member than the one most
3870 recently written to (called ``type-punning'') is common.  Even with
3871 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
3872 is accessed through the union type.  So, the code above will work as
3873 expected.  However, this code might not:
3874 @example
3875 int f() @{
3876   a_union t;
3877   int* ip;
3878   t.d = 3.0;
3879   ip = &t.i;
3880   return *ip;
3881 @}
3882 @end example
3883
3884 Every language that wishes to perform language-specific alias analysis
3885 should define a function that computes, given an @code{tree}
3886 node, an alias set for the node.  Nodes in different alias sets are not
3887 allowed to alias.  For an example, see the C front-end function
3888 @code{c_get_alias_set}.
3889
3890 For all machines, optimization level 2 and higher enables this flag by
3891 default.
3892
3893 @item -falign-functions
3894 @itemx -falign-functions=@var{n}
3895 @opindex falign-functions
3896 Align the start of functions to the next power-of-two greater than
3897 @var{n}, skipping up to @var{n} bytes.  For instance,
3898 @option{-falign-functions=32} aligns functions to the next 32-byte
3899 boundary, but @option{-falign-functions=24} would align to the next
3900 32-byte boundary only if this can be done by skipping 23 bytes or less.
3901
3902 @option{-fno-align-functions} and @option{-falign-functions=1} are
3903 equivalent and mean that functions will not be aligned.
3904
3905 Some assemblers only support this flag when @var{n} is a power of two;
3906 in that case, it is rounded up.
3907
3908 If @var{n} is not specified, use a machine-dependent default.
3909
3910 @item -falign-labels
3911 @itemx -falign-labels=@var{n}
3912 @opindex falign-labels
3913 Align all branch targets to a power-of-two boundary, skipping up to
3914 @var{n} bytes like @option{-falign-functions}.  This option can easily
3915 make code slower, because it must insert dummy operations for when the
3916 branch target is reached in the usual flow of the code.
3917
3918 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
3919 are greater than this value, then their values are used instead.
3920
3921 If @var{n} is not specified, use a machine-dependent default which is
3922 very likely to be @samp{1}, meaning no alignment.
3923
3924 @item -falign-loops
3925 @itemx -falign-loops=@var{n}
3926 @opindex falign-loops
3927 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
3928 like @option{-falign-functions}.  The hope is that the loop will be
3929 executed many times, which will make up for any execution of the dummy
3930 operations.
3931
3932 If @var{n} is not specified, use a machine-dependent default.
3933
3934 @item -falign-jumps
3935 @itemx -falign-jumps=@var{n}
3936 @opindex falign-jumps
3937 Align branch targets to a power-of-two boundary, for branch targets
3938 where the targets can only be reached by jumping, skipping up to @var{n}
3939 bytes like @option{-falign-functions}.  In this case, no dummy operations
3940 need be executed.
3941
3942 If @var{n} is not specified, use a machine-dependent default.
3943
3944 @item -fssa
3945 @opindex fssa
3946 Perform optimizations in static single assignment form.  Each function's
3947 flow graph is translated into SSA form, optimizations are performed, and
3948 the flow graph is translated back from SSA form.  Users should not
3949 specify this option, since it is not yet ready for production use.
3950
3951 @item -fssa-ccp
3952 @opindex fssa-ccp
3953 Perform Sparse Conditional Constant Propagation in SSA form.  Requires
3954 @option{-fssa}.  Like @option{-fssa}, this is an experimental feature.
3955
3956 @item -fssa-dce
3957 @opindex fssa-dce
3958 Perform aggressive dead-code elimination in SSA form.  Requires @option{-fssa}.
3959 Like @option{-fssa}, this is an experimental feature.
3960
3961 @item -fsingle-precision-constant
3962 @opindex fsingle-precision-constant
3963 Treat floating point constant as single precision constant instead of
3964 implicitly converting it to double precision constant.
3965
3966 @item -frename-registers
3967 @opindex frename-registers
3968 Attempt to avoid false dependencies in scheduled code by making use
3969 of registers left over after register allocation.  This optimization
3970 will most benefit processors with lots of registers.  It can, however,
3971 make debugging impossible, since variables will no longer stay in
3972 a ``home register''.
3973
3974 @item -fno-cprop-registers
3975 @opindex fno-cprop-registers
3976 After register allocation and post-register allocation instruction splitting,
3977 we perform a copy-propagation pass to try to reduce scheduling dependencies
3978 and occasionally eliminate the copy.
3979
3980 @item --param @var{name}=@var{value}
3981 @opindex param
3982 In some places, GCC uses various constants to control the amount of
3983 optimization that is done.  For example, GCC will not inline functions
3984 that contain more that a certain number of instructions.  You can
3985 control some of these constants on the command-line using the
3986 @option{--param} option.
3987
3988 In each case, the @var{value} is an integer.  The allowable choices for
3989 @var{name} are given in the following table:
3990
3991 @table @gcctabopt
3992 @item max-delay-slot-insn-search
3993 The maximum number of instructions to consider when looking for an
3994 instruction to fill a delay slot.  If more than this arbitrary number of
3995 instructions is searched, the time savings from filling the delay slot
3996 will be minimal so stop searching.  Increasing values mean more
3997 aggressive optimization, making the compile time increase with probably
3998 small improvement in executable run time.
3999
4000 @item max-delay-slot-live-search
4001 When trying to fill delay slots, the maximum number of instructions to
4002 consider when searching for a block with valid live register
4003 information.  Increasing this arbitrarily chosen value means more
4004 aggressive optimization, increasing the compile time.  This parameter
4005 should be removed when the delay slot code is rewritten to maintain the
4006 control-flow graph.
4007
4008 @item max-gcse-memory
4009 The approximate maximum amount of memory that will be allocated in
4010 order to perform the global common subexpression elimination
4011 optimization.  If more memory than specified is required, the
4012 optimization will not be done.
4013
4014 @item max-gcse-passes
4015 The maximum number of passes of GCSE to run.
4016
4017 @item max-pending-list-length
4018 The maximum number of pending dependencies scheduling will allow
4019 before flushing the current state and starting over.  Large functions
4020 with few branches or calls can create excessively large lists which
4021 needlessly consume memory and resources.
4022
4023 @item max-inline-insns
4024 If an function contains more than this many instructions, it
4025 will not be inlined.  This option is precisely equivalent to
4026 @option{-finline-limit}.
4027
4028 @item max-unrolled-insns
4029 The maximum number of instructions that a loop should have if that loop
4030 is unrolled, and if the loop is unrolled, it determines how many times
4031 the loop code is unrolled.
4032
4033 @item hot-bb-count-fraction
4034 Select fraction of the maximal count of repetitions of basic block in program
4035 given basic block needs to have to be considered hot.
4036
4037 @item hot-bb-frequency-fraction
4038 Select fraction of the maximal frequency of executions of basic block in
4039 function given basic block needs to have to be considered hot
4040
4041 @item tracer-dynamic-coverage
4042 @itemx tracer-dynamic-coverage-feedback
4043
4044 This value is used to limit superblock formation once given percentage of
4045 executed instructions is covered.  This limits unnecesary code size expansion.
4046
4047 The @option{tracer-dynamic-coverage-feedback} is used only when profile
4048 feedback is available.  The real profiles (as opposed to statically estimated
4049 ones) are much less balanced allowing the threshold to be larger value.
4050
4051 @item tracer-max-code-growth
4052 Stop tail duplication once code growth has reached given percentage.  This is
4053 rather hokey argument, as most of the duplicates will be elliminated later in
4054 cross jumping, so it may be set to much higher values than is the desired code
4055 growth.
4056
4057 @item tracer-min-branch-ratio
4058
4059 Stop reverse growth when the reverse probability of best edge is less than this
4060 threshold (in percent).
4061
4062 @item tracer-min-branch-ratio
4063 @itemx tracer-min-branch-ratio-feedback
4064
4065 Stop forward growth if the best edge do have probability lower than this
4066 threshold.
4067
4068 Similary to @option{tracer-dynamic-coverage} two values are present, one for
4069 compilation for profile feedback and one for compilation without.  The value
4070 for compilation with profile feedback needs to be more conservative (higher) in
4071 order to make tracer effective.
4072
4073 @end table
4074 @end table
4075
4076 @node Preprocessor Options
4077 @section Options Controlling the Preprocessor
4078 @cindex preprocessor options
4079 @cindex options, preprocessor
4080
4081 These options control the C preprocessor, which is run on each C source
4082 file before actual compilation.
4083
4084 If you use the @option{-E} option, nothing is done except preprocessing.
4085 Some of these options make sense only together with @option{-E} because
4086 they cause the preprocessor output to be unsuitable for actual
4087 compilation.
4088
4089 @opindex Wp
4090 You can use @option{-Wp,@var{option}} to bypass the compiler driver
4091 and pass @var{option} directly through to the preprocessor.  If
4092 @var{option} contains commas, it is split into multiple options at the
4093 commas.  However, many options are modified, translated or interpreted
4094 by the compiler driver before being passed to the preprocessor, and
4095 @option{-Wp} forcibly bypasses this phase.  The preprocessor's direct
4096 interface is undocumented and subject to change, so whenever possible
4097 you should avoid using @option{-Wp} and let the driver handle the
4098 options instead.
4099
4100 @include cppopts.texi
4101
4102 @node Assembler Options
4103 @section Passing Options to the Assembler
4104
4105 @c prevent bad page break with this line
4106 You can pass options to the assembler.
4107
4108 @table @gcctabopt
4109 @item -Wa,@var{option}
4110 @opindex Wa
4111 Pass @var{option} as an option to the assembler.  If @var{option}
4112 contains commas, it is split into multiple options at the commas.
4113 @end table
4114
4115 @node Link Options
4116 @section Options for Linking
4117 @cindex link options
4118 @cindex options, linking
4119
4120 These options come into play when the compiler links object files into
4121 an executable output file.  They are meaningless if the compiler is
4122 not doing a link step.
4123
4124 @table @gcctabopt
4125 @cindex file names
4126 @item @var{object-file-name}
4127 A file name that does not end in a special recognized suffix is
4128 considered to name an object file or library.  (Object files are
4129 distinguished from libraries by the linker according to the file
4130 contents.)  If linking is done, these object files are used as input
4131 to the linker.
4132
4133 @item -c
4134 @itemx -S
4135 @itemx -E
4136 @opindex c
4137 @opindex S
4138 @opindex E
4139 If any of these options is used, then the linker is not run, and
4140 object file names should not be used as arguments.  @xref{Overall
4141 Options}.
4142
4143 @cindex Libraries
4144 @item -l@var{library}
4145 @itemx -l @var{library}
4146 @opindex l
4147 Search the library named @var{library} when linking.  (The second
4148 alternative with the library as a separate argument is only for
4149 POSIX compliance and is not recommended.)
4150
4151 It makes a difference where in the command you write this option; the
4152 linker searches and processes libraries and object files in the order they
4153 are specified.  Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
4154 after file @file{foo.o} but before @file{bar.o}.  If @file{bar.o} refers
4155 to functions in @samp{z}, those functions may not be loaded.
4156
4157 The linker searches a standard list of directories for the library,
4158 which is actually a file named @file{lib@var{library}.a}.  The linker
4159 then uses this file as if it had been specified precisely by name.
4160
4161 The directories searched include several standard system directories
4162 plus any that you specify with @option{-L}.
4163
4164 Normally the files found this way are library files---archive files
4165 whose members are object files.  The linker handles an archive file by
4166 scanning through it for members which define symbols that have so far
4167 been referenced but not defined.  But if the file that is found is an
4168 ordinary object file, it is linked in the usual fashion.  The only
4169 difference between using an @option{-l} option and specifying a file name
4170 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
4171 and searches several directories.
4172
4173 @item -lobjc
4174 @opindex lobjc
4175 You need this special case of the @option{-l} option in order to
4176 link an Objective-C program.
4177
4178 @item -nostartfiles
4179 @opindex nostartfiles
4180 Do not use the standard system startup files when linking.
4181 The standard system libraries are used normally, unless @option{-nostdlib}
4182 or @option{-nodefaultlibs} is used.
4183
4184 @item -nodefaultlibs
4185 @opindex nodefaultlibs
4186 Do not use the standard system libraries when linking.
4187 Only the libraries you specify will be passed to the linker.
4188 The standard startup files are used normally, unless @option{-nostartfiles}
4189 is used.  The compiler may generate calls to memcmp, memset, and memcpy
4190 for System V (and ISO C) environments or to bcopy and bzero for
4191 BSD environments.  These entries are usually resolved by entries in
4192 libc.  These entry points should be supplied through some other
4193 mechanism when this option is specified.
4194
4195 @item -nostdlib
4196 @opindex nostdlib
4197 Do not use the standard system startup files or libraries when linking.
4198 No startup files and only the libraries you specify will be passed to
4199 the linker.  The compiler may generate calls to memcmp, memset, and memcpy
4200 for System V (and ISO C) environments or to bcopy and bzero for
4201 BSD environments.  These entries are usually resolved by entries in
4202 libc.  These entry points should be supplied through some other
4203 mechanism when this option is specified.
4204
4205 @cindex @option{-lgcc}, use with @option{-nostdlib}
4206 @cindex @option{-nostdlib} and unresolved references
4207 @cindex unresolved references and @option{-nostdlib}
4208 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
4209 @cindex @option{-nodefaultlibs} and unresolved references
4210 @cindex unresolved references and @option{-nodefaultlibs}
4211 One of the standard libraries bypassed by @option{-nostdlib} and
4212 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
4213 that GCC uses to overcome shortcomings of particular machines, or special
4214 needs for some languages.
4215 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
4216 Collection (GCC) Internals},
4217 for more discussion of @file{libgcc.a}.)
4218 In most cases, you need @file{libgcc.a} even when you want to avoid
4219 other standard libraries.  In other words, when you specify @option{-nostdlib}
4220 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
4221 This ensures that you have no unresolved references to internal GCC
4222 library subroutines.  (For example, @samp{__main}, used to ensure C++
4223 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
4224 GNU Compiler Collection (GCC) Internals}.)
4225
4226 @item -s
4227 @opindex s
4228 Remove all symbol table and relocation information from the executable.
4229
4230 @item -static
4231 @opindex static
4232 On systems that support dynamic linking, this prevents linking with the shared
4233 libraries.  On other systems, this option has no effect.
4234
4235 @item -shared
4236 @opindex shared
4237 Produce a shared object which can then be linked with other objects to
4238 form an executable.  Not all systems support this option.  For predictable
4239 results, you must also specify the same set of options that were used to
4240 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
4241 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
4242 needs to build supplementary stub code for constructors to work.  On
4243 multi-libbed systems, @samp{gcc -shared} must select the correct support
4244 libraries to link against.  Failing to supply the correct flags may lead
4245 to subtle defects.  Supplying them in cases where they are not necessary
4246 is innocuous.}
4247
4248 @item -shared-libgcc
4249 @itemx -static-libgcc
4250 @opindex shared-libgcc
4251 @opindex static-libgcc
4252 On systems that provide @file{libgcc} as a shared library, these options
4253 force the use of either the shared or static version respectively.
4254 If no shared version of @file{libgcc} was built when the compiler was
4255 configured, these options have no effect.
4256
4257 There are several situations in which an application should use the
4258 shared @file{libgcc} instead of the static version.  The most common
4259 of these is when the application wishes to throw and catch exceptions
4260 across different shared libraries.  In that case, each of the libraries
4261 as well as the application itself should use the shared @file{libgcc}.
4262
4263 Therefore, the G++ and GCJ drivers automatically add
4264 @option{-shared-libgcc} whenever you build a shared library or a main
4265 executable, because C++ and Java programs typically use exceptions, so
4266 this is the right thing to do.
4267
4268 If, instead, you use the GCC driver to create shared libraries, you may
4269 find that they will not always be linked with the shared @file{libgcc}.
4270 If GCC finds, at its configuration time, that you have a GNU linker that
4271 does not support option @option{--eh-frame-hdr}, it will link the shared
4272 version of @file{libgcc} into shared libraries by default.  Otherwise,
4273 it will take advantage of the linker and optimize away the linking with
4274 the shared version of @file{libgcc}, linking with the static version of
4275 libgcc by default.  This allows exceptions to propagate through such
4276 shared libraries, without incurring relocation costs at library load
4277 time.
4278
4279 However, if a library or main executable is supposed to throw or catch
4280 exceptions, you must link it using the G++ or GCJ driver, as appropriate
4281 for the languages used in the program, or using the option
4282 @option{-shared-libgcc}, such that it is linked with the shared
4283 @file{libgcc}.
4284
4285 @item -symbolic
4286 @opindex symbolic
4287 Bind references to global symbols when building a shared object.  Warn
4288 about any unresolved references (unless overridden by the link editor
4289 option @samp{-Xlinker -z -Xlinker defs}).  Only a few systems support
4290 this option.
4291
4292 @item -Xlinker @var{option}
4293 @opindex Xlinker
4294 Pass @var{option} as an option to the linker.  You can use this to
4295 supply system-specific linker options which GCC does not know how to
4296 recognize.
4297
4298 If you want to pass an option that takes an argument, you must use
4299 @option{-Xlinker} twice, once for the option and once for the argument.
4300 For example, to pass @option{-assert definitions}, you must write
4301 @samp{-Xlinker -assert -Xlinker definitions}.  It does not work to write
4302 @option{-Xlinker "-assert definitions"}, because this passes the entire
4303 string as a single argument, which is not what the linker expects.
4304
4305 @item -Wl,@var{option}
4306 @opindex Wl
4307 Pass @var{option} as an option to the linker.  If @var{option} contains
4308 commas, it is split into multiple options at the commas.
4309