OSDN Git Service

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