OSDN Git Service

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